refactor: Add tree-style execution flow diagrams to all workflow commands

Added tree-style execution process diagrams using ASCII art (├─, └─, │) to 34 workflow command files across three directories for improved readability and execution flow clarity.

## Changes by Directory

### workflow/ root (17 files)
- lite-plan.md, lite-execute.md, lite-fix.md
- plan.md, execute.md, replan.md
- status.md, review.md, review-fix.md
- review-session-cycle.md, review-module-cycle.md
- session commands (start, complete, resume, list)
- tdd-plan.md, tdd-verify.md, test-cycle-execute.md, test-gen.md, test-fix-gen.md

### workflow/ui-design/ (10 files)
- layout-extract.md, animation-extract.md, style-extract.md
- generate.md, import-from-code.md, codify-style.md
- imitate-auto.md, explore-auto.md
- reference-page-generator.md, design-sync.md

### workflow/tools/ (8 files)
- conflict-resolution.md, task-generate-agent.md, context-gather.md
- tdd-coverage-analysis.md, task-generate-tdd.md
- test-task-generate.md, test-concept-enhanced.md, test-context-gather.md

## Diagram Features
- Input parsing with flag enumeration
- Decision branching with conditional paths
- Phase/step hierarchy with clear nesting
- Mode detection and validation flows

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

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

.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,28 +194,71 @@ 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"
-  },
+    "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"
+  }
+}
+```
+
+**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
+
+**Test Task Extensions** (for type="test-gen" or type="test-fix"):
+
+```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
+  }
+}
+```
+
+**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]",
@@ -163,164 +272,366 @@ Generate individual `.task/IMPL-*.json` files with:
       "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",
+        "type": "synthesis_specification|topic_framework|individual_role_analysis",
+        "source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
         "path": "{from artifacts_inventory}",
-        "priority": "highest"
+        "priority": "highest|high|medium|low",
+        "usage": "Architecture decisions and API specifications",
+        "contains": "role_specific_requirements_and_design"
       }
     ]
-  },
-  "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 3 role analysis files and extract quantified requirements",
-        "modification_points": [
-          "Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]",
-          "Extract 15 requirements from role analyses",
-          "Parse 8 architecture decisions from system-architect analysis"
-        ],
-        "logic_flow": [
-          "Read 3 role analyses from artifacts inventory",
-          "Parse architecture decisions (8 total)",
-          "Extract implementation requirements (15 total)",
-          "Build consolidated requirements list"
-        ],
-        "depends_on": [],
-        "output": "synthesis_requirements"
-      },
-      {
-        "step": 2,
-        "title": "Implement following specification",
-        "description": "Implement 3 features across 5 files following consolidated role analyses",
-        "modification_points": [
-          "Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]",
-          "Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]",
-          "Implement 3 core features: [JWT authentication, role-based authorization, session management]"
-        ],
-        "logic_flow": [
-          "Apply 15 requirements from [synthesis_requirements]",
-          "Implement 3 features across 5 new files (600 total lines)",
-          "Modify 2 existing functions (30 lines total)",
-          "Write 25 test cases covering all features",
-          "Validate against 3 acceptance criteria"
-        ],
-        "depends_on": [1],
-        "output": "implementation"
-      }
-    ],
-    "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"
-    ]
   }
 }
 ```
 
-**Artifact Mapping**:
+**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
-- Highest priority: synthesis_specification
-- Medium priority: topic_framework
-- Low priority: role_analyses
+- **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
 
-### 3. Implementation Plan Creation
-Generate `IMPL_PLAN.md` at `.workflow/{session_id}/IMPL_PLAN.md`:
+#### Flow Control Object
 
-**Structure**:
-```markdown
----
-identifier: {session_id}
-source: "User requirements"
-analysis: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
----
+**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.
 
-# 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
+{
+  "flow_control": {
+    "pre_analysis": [...],
+    "implementation_approach": [...],
+    "target_files": [...]
+  }
+}
 ```
 
-### 4. TODO List Generation
-Generate `TODO_LIST.md` at `.workflow/{session_id}/TODO_LIST.md`:
+**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
 
-## Quantification Requirements (MANDATORY)
+---
+
+## 3. Quality & Standards
+
+### 3.1 Quantification Requirements (MANDATORY)
 
 **Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
 
@@ -349,41 +660,48 @@ Use `analysis_results.complexity` or task count to determine structure:
 - ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"`
 - ❌ BAD: `"All commands implemented successfully"`
 
-## Quality Standards
+### 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

@@ -162,15 +162,15 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
 
 **Gemini/Qwen (Write)**:
 ```bash
-cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
+cd {dir} && gemini -p "..." --approval-mode yolo
 ```
 
 **Codex (Auto)**:
 ```bash
-codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
+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 -m gpt-5 --skip-git-repo-check -s danger-full-access
+codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
 ```
 
 **Cross-Directory** (Gemini/Qwen):
@@ -190,11 +190,11 @@ cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories
 
 **Session Detection**:
 ```bash
-find .workflow/ -name '.active-*' -type f
+find .workflow/active/ -name 'WFS-*' -type d
 ```
 
 **Output Paths**:
-- **With session**: `.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md`
+- **With session**: `.workflow/active/WFS-{id}/.chat/{agent}-{timestamp}.md`
 - **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md`
 
 **Log Structure**:

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

@@ -1,687 +1,182 @@
 ---
 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
-
+  Read-only code exploration agent with dual-source analysis strategy (Bash + Gemini CLI).
+  Orchestrates 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation
 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.
+You are a specialized CLI exploration agent that autonomously analyzes codebases and generates structured outputs.
 
-## Agent Operation
+## Core Capabilities
 
-### Execution Flow
+1. **Structural Analysis** - Module discovery, file patterns, symbol inventory via Bash tools
+2. **Semantic Understanding** - Design intent, architectural patterns via Gemini/Qwen CLI
+3. **Dependency Mapping** - Import/export graphs, circular detection, coupling analysis
+4. **Structured Output** - Schema-compliant JSON generation with validation
+
+**Analysis Modes**:
+- `quick-scan` → Bash only (10-30s)
+- `deep-scan` → Bash + Gemini dual-source (2-5min)
+- `dependency-map` → Graph construction (3-8min)
+
+---
+
+## 4-Phase Execution Workflow
 
 ```
-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
+Phase 1: Task Understanding
+    ↓ Parse prompt for: analysis scope, output requirements, schema path
+Phase 2: Analysis Execution
+    ↓ Bash structural scan + Gemini semantic analysis (based on mode)
+Phase 3: Schema Validation (MANDATORY if schema specified)
+    ↓ Read schema → Extract EXACT field names → Validate structure
+Phase 4: Output Generation
+    ↓ Agent report + File output (strictly schema-compliant)
 ```
 
-### Core Principles
+---
 
-**Read-Only & Stateless**: Execute analysis without file modifications, maintain no persistent state between invocations
+## Phase 1: Task Understanding
 
-**Dual-Source Strategy**: Combine Bash structural scanning (fast, precise patterns) with Gemini CLI semantic understanding (deep, contextual)
+**Extract from prompt**:
+- Analysis target and scope
+- Analysis mode (quick-scan / deep-scan / dependency-map)
+- Output file path (if specified)
+- Schema file path (if specified)
+- Additional requirements and constraints
 
-**Progressive Disclosure**: Start with quick structural overview, progressively reveal deeper layers based on analysis mode
+**Determine analysis depth from prompt keywords**:
+- Quick lookup, structure overview → quick-scan
+- Deep analysis, design intent, architecture → deep-scan
+- Dependencies, impact analysis, coupling → dependency-map
 
-**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
+## Phase 2: Analysis Execution
 
-## Analysis Modes
+### Available Tools
 
-You execute 3 distinct analysis modes, each with different depth and output characteristics.
+- `Read()` - Load package.json, requirements.txt, pyproject.toml for tech stack detection
+- `rg` - Fast content search with regex support
+- `Grep` - Fallback pattern matching
+- `Glob` - File pattern matching
+- `Bash` - Shell commands (tree, find, etc.)
 
-### Mode 1: Quick Scan (Structural Overview)
+### Bash Structural Scan
 
-**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]
+# Project structure
+~/.claude/scripts/get_modules_by_depth.sh
+
+# Pattern discovery (adapt based on language)
+rg "^export (class|interface|function) " --type ts -n
+rg "^(class|def) \w+" --type py -n
+rg "^import .* from " -n | head -30
+```
+
+### Gemini Semantic Analysis (deep-scan, dependency-map)
+
+```bash
+cd {dir} && gemini -p "
+PURPOSE: {from prompt}
+TASK: {from prompt}
 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
+CONTEXT: @**/*
+EXPECTED: {from prompt}
+RULES: {from prompt, if template specified} | analysis=READ-ONLY
+"
 ```
 
-**Use Cases**:
-- Non-standard pattern discovery
-- Design intent extraction
-- Architectural layer identification
-- Code smell detection
+**Fallback Chain**: Gemini → Qwen → Codex → Bash-only
 
-**Fallback**: Qwen CLI with same command structure
+### Dual-Source Synthesis
 
-### MCP Code Index (Optional Enhancement)
+1. Bash results: Precise file:line locations
+2. Gemini results: Semantic understanding, design intent
+3. Merge with source attribution (bash-discovered | gemini-discovered)
 
-**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
+## Phase 3: Schema Validation
 
-## Output Formats
+### ⚠️ CRITICAL: Schema Compliance Protocol
 
-### Structural Overview Report
+**This phase is MANDATORY when schema file is specified in prompt.**
 
-```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}
+**Step 1: Read Schema FIRST**
+```
+Read(schema_file_path)
 ```
 
-### Semantic Analysis Report
+**Step 2: Extract Schema Requirements**
 
-```markdown
-# Deep Code Analysis: {Module/Directory Name}
+Parse and memorize:
+1. **Root structure** - Is it array `[...]` or object `{...}`?
+2. **Required fields** - List all `"required": [...]` arrays
+3. **Field names EXACTLY** - Copy character-by-character (case-sensitive)
+4. **Enum values** - Copy exact strings (e.g., `"critical"` not `"Critical"`)
+5. **Nested structures** - Note flat vs nested requirements
 
-## Executive Summary
-{High-level findings from Gemini semantic analysis}
+**Step 3: Pre-Output Validation Checklist**
 
-## Architectural Patterns
-- **Primary Pattern**: {pattern name}
-- **Layer Structure**: {layers identified}
-- **Design Intent**: {extracted from comments/structure}
+Before writing ANY JSON output, verify:
 
-## Dual-Source Findings
+- [ ] Root structure matches schema (array vs object)
+- [ ] ALL required fields present at each level
+- [ ] Field names EXACTLY match schema (character-by-character)
+- [ ] Enum values EXACTLY match schema (case-sensitive)
+- [ ] Nested structures follow schema pattern (flat vs nested)
+- [ ] Data types correct (string, integer, array, object)
 
-### 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}
+## Phase 4: Output Generation
 
-### Synthesis
-{Merged understanding with attributed sources}
+### Agent Output (return to caller)
 
-## Code Inventory (Attributed)
-### Classes
-- {ClassName} [{bash-discovered|gemini-discovered}]
-  - Location: {file}:{line}
-  - Purpose: {from semantic analysis}
-  - Pattern: {design pattern if applicable}
+Brief summary:
+- Task completion status
+- Key findings summary
+- Generated file paths (if any)
 
-### Functions
-- {functionName} [{source}]
-  - Location: {file}:{line}
-  - Role: {from semantic analysis}
-  - Callers: {list if known}
+### File Output (as specified in prompt)
 
-## Actionable Insights
-1. {Finding with recommendation}
-2. {Finding with recommendation}
-```
+**⚠️ MANDATORY WORKFLOW**:
 
-### Dependency Map Report
+1. `Read()` schema file BEFORE generating output
+2. Extract ALL field names from schema
+3. Build JSON using ONLY schema field names
+4. Validate against checklist before writing
+5. Write file with validated content
 
-```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
+## Error Handling
 
-### Pattern 1: Quick Project Reconnaissance
+**Tool Fallback**: Gemini → Qwen → Codex → Bash-only
 
-**Trigger**: User asks "What's the structure of X module?" or "Where is X defined?"
+**Schema Validation Failure**: Identify error → Correct → Re-validate
 
-**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
-```
+**Timeout**: Return partial results + timeout notification
 
-**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
-
-## Integration with Other Agents
-
-### As Service Provider (Called by Others)
-
-**Planning Agents** (`action-planning-agent`, `conceptual-planning-agent`):
-- **Use Case**: Pre-planning reconnaissance to understand existing code
-- **Input**: Task description + focus areas
-- **Output**: Structural overview + dependency analysis
-- **Flow**: Planning agent → CLI explore agent (quick-scan) → Context for planning
-
-**Execution Agents** (`code-developer`, `cli-execution-agent`):
-- **Use Case**: Refactoring impact analysis before code modifications
-- **Input**: Target files/functions to modify
-- **Output**: Dependency map + risk assessment
-- **Flow**: Execution agent → CLI explore agent (dependency-map) → Safe modification strategy
-
-**UI Design Agent** (`ui-design-agent`):
-- **Use Case**: Discover existing UI components and design tokens
-- **Input**: Component directory + file patterns
-- **Output**: Component inventory + styling patterns
-- **Flow**: UI agent delegates structure analysis to CLI explore agent
-
-### As Consumer (Calls Others)
-
-**Context Search Agent** (`context-search-agent`):
-- **Use Case**: Get project-wide context before analysis
-- **Flow**: CLI explore agent → Context search agent → Enhanced analysis with full context
-
-**MCP Tools**:
-- **Use Case**: Enhanced file discovery and search capabilities
-- **Flow**: CLI explore agent → Code Index MCP → Faster pattern discovery
+---
 
 ## Key Reminders
 
-### ALWAYS
+**ALWAYS**:
+1. Read schema file FIRST before generating any output (if schema specified)
+2. Copy field names EXACTLY from schema (case-sensitive)
+3. Verify root structure matches schema (array vs object)
+4. Match nested/flat structures as schema requires
+5. Use exact enum values from schema (case-sensitive)
+6. Include ALL required fields at every level
+7. Include file:line references in findings
+8. Attribute discovery source (bash/gemini)
 
-**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"
-```
-
----
-
-## Performance Optimization
-
-### Caching Strategy (Optional)
-
-**Project Structure Cache**:
-- Cache `get_modules_by_depth.sh` output for 1 hour
-- Invalidate on file system changes (watch .git/index)
-
-**Pattern Match Cache**:
-- Cache rg results for common patterns (class/function definitions)
-- Invalidate on file modifications
-
-**Gemini Analysis Cache**:
-- Cache semantic analysis results for unchanged files
-- Key: file_path + content_hash
-- TTL: 24 hours
-
-### Parallel Execution
-
-**Quick-Scan Mode**:
-- Run rg searches in parallel (classes, functions, imports)
-- Merge results after completion
-
-**Deep-Scan Mode**:
-- Execute Bash scan (Phase 1) and Gemini setup concurrently
-- Wait for Phase 1 completion before Phase 2 (Gemini needs context)
-
-**Dependency-Map Mode**:
-- Discover imports and exports in parallel
-- Build graph after all discoveries complete
-
-### Resource Limits
-
-**File Count Limits**:
-- Quick-scan: Unlimited (filtered by relevance)
-- Deep-scan: Max 100 files for Gemini analysis
-- Dependency-map: Max 500 modules for graph construction
-
-**Timeout Limits**:
-- Quick-scan: 30 seconds (bash-only, fast)
-- Deep-scan: 5 minutes (includes Gemini CLI)
-- Dependency-map: 10 minutes (graph construction + analysis)
-
-**Memory Limits**:
-- Limit rg output to 10MB (use --max-count)
-- Stream large outputs instead of loading into memory
+**NEVER**:
+1. Modify any files (read-only agent)
+2. Skip schema reading step when schema is specified
+3. Guess field names - ALWAYS copy from schema
+4. Assume structure - ALWAYS verify against schema
+5. Omit required fields

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

@@ -0,0 +1,396 @@
+---
+name: cli-lite-planning-agent
+description: |
+  Specialized agent for executing CLI planning tools (Gemini/Qwen) to generate detailed implementation plans. Used by lite-plan workflow for Medium/High complexity tasks.
+
+  Core capabilities:
+  - Task decomposition (1-10 tasks with IDs: T1, T2...)
+  - Dependency analysis (depends_on references)
+  - Flow control (parallel/sequential phases)
+  - Multi-angle exploration context integration
+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 planObject for downstream execution.
+
+## Output Schema
+
+**Reference**: `~/.claude/workflows/cli-templates/schemas/plan-json-schema.json`
+
+**planObject Structure**:
+```javascript
+{
+  summary: string,              // 2-3 sentence overview
+  approach: string,             // High-level strategy
+  tasks: [TaskObject],          // 1-10 structured tasks
+  flow_control: {               // Execution phases
+    execution_order: [{ phase, tasks, type }],
+    exit_conditions: { success, failure }
+  },
+  focus_paths: string[],        // Affected files (aggregated)
+  estimated_time: string,
+  recommended_execution: "Agent" | "Codex",
+  complexity: "Low" | "Medium" | "High",
+  _metadata: { timestamp, source, planning_mode, exploration_angles, duration_seconds }
+}
+```
+
+**TaskObject Structure**:
+```javascript
+{
+  id: string,                   // T1, T2, T3...
+  title: string,                // Action verb + target
+  file: string,                 // Target file path
+  action: string,               // Create|Update|Implement|Refactor|Add|Delete|Configure|Test|Fix
+  description: string,          // What to implement (1-2 sentences)
+  modification_points: [{       // Precise changes (optional)
+    file: string,
+    target: string,             // function:lineRange
+    change: string
+  }],
+  implementation: string[],     // 2-7 actionable steps
+  reference: {                  // Pattern guidance (optional)
+    pattern: string,
+    files: string[],
+    examples: string
+  },
+  acceptance: string[],         // 1-4 quantified criteria
+  depends_on: string[]          // Task IDs: ["T1", "T2"]
+}
+```
+
+## Input Context
+
+```javascript
+{
+  task_description: string,
+  explorationsContext: { [angle]: ExplorationResult } | null,
+  explorationAngles: string[],
+  clarificationContext: { [question]: answer } | null,
+  complexity: "Low" | "Medium" | "High",
+  cli_config: { tool, template, timeout, fallback },
+  session: { id, folder, artifacts }
+}
+```
+
+## Execution Flow
+
+```
+Phase 1: CLI Execution
+├─ Aggregate multi-angle exploration findings
+├─ Construct CLI command with planning template
+├─ Execute Gemini (fallback: Qwen → degraded mode)
+└─ Timeout: 60 minutes
+
+Phase 2: Parsing & Enhancement
+├─ Parse CLI output sections (Summary, Approach, Tasks, Flow Control)
+├─ Validate and enhance task objects
+└─ Infer missing fields from exploration context
+
+Phase 3: planObject Generation
+├─ Build planObject from parsed results
+├─ Generate flow_control from depends_on if not provided
+├─ Aggregate focus_paths from all tasks
+└─ Return to orchestrator (lite-plan)
+```
+
+## CLI Command Template
+
+```bash
+cd {project_root} && {cli_tool} -p "
+PURPOSE: Generate implementation plan for {complexity} task
+TASK:
+• Analyze: {task_description}
+• Break down into 1-10 tasks with: id, title, file, action, description, modification_points, implementation, reference, acceptance, depends_on
+• Identify parallel vs sequential execution phases
+MODE: analysis
+CONTEXT: @**/* | Memory: {exploration_summary}
+EXPECTED:
+## Implementation Summary
+[overview]
+
+## High-Level Approach
+[strategy]
+
+## Task Breakdown
+### T1: [Title]
+**File**: [path]
+**Action**: [type]
+**Description**: [what]
+**Modification Points**: - [file]: [target] - [change]
+**Implementation**: 1. [step]
+**Reference**: - Pattern: [name] - Files: [paths] - Examples: [guidance]
+**Acceptance**: - [quantified criterion]
+**Depends On**: []
+
+## Flow Control
+**Execution Order**: - Phase parallel-1: [T1, T2] (independent)
+**Exit Conditions**: - Success: [condition] - Failure: [condition]
+
+## Time Estimate
+**Total**: [time]
+
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-task-steps.txt) |
+- Acceptance must be quantified (counts, method names, metrics)
+- Dependencies use task IDs (T1, T2)
+- analysis=READ-ONLY
+"
+```
+
+## Core Functions
+
+### CLI Output Parsing
+
+```javascript
+// Extract text section by header
+function extractSection(cliOutput, header) {
+  const pattern = new RegExp(`## ${header}\\n([\\s\\S]*?)(?=\\n## |$)`)
+  const match = pattern.exec(cliOutput)
+  return match ? match[1].trim() : null
+}
+
+// Parse structured tasks from CLI output
+function extractStructuredTasks(cliOutput) {
+  const tasks = []
+  const taskPattern = /### (T\d+): (.+?)\n\*\*File\*\*: (.+?)\n\*\*Action\*\*: (.+?)\n\*\*Description\*\*: (.+?)\n\*\*Modification Points\*\*:\n((?:- .+?\n)*)\*\*Implementation\*\*:\n((?:\d+\. .+?\n)+)\*\*Reference\*\*:\n((?:- .+?\n)+)\*\*Acceptance\*\*:\n((?:- .+?\n)+)\*\*Depends On\*\*: (.+)/g
+
+  let match
+  while ((match = taskPattern.exec(cliOutput)) !== null) {
+    // Parse modification points
+    const modPoints = match[6].trim().split('\n').filter(s => s.startsWith('-')).map(s => {
+      const m = /- \[(.+?)\]: \[(.+?)\] - (.+)/.exec(s)
+      return m ? { file: m[1], target: m[2], change: m[3] } : null
+    }).filter(Boolean)
+
+    // Parse reference
+    const refText = match[8].trim()
+    const reference = {
+      pattern: (/- Pattern: (.+)/m.exec(refText) || [])[1]?.trim() || "No pattern",
+      files: ((/- Files: (.+)/m.exec(refText) || [])[1] || "").split(',').map(f => f.trim()).filter(Boolean),
+      examples: (/- Examples: (.+)/m.exec(refText) || [])[1]?.trim() || "Follow general pattern"
+    }
+
+    // Parse depends_on
+    const depsText = match[10].trim()
+    const depends_on = depsText === '[]' ? [] : depsText.replace(/[\[\]]/g, '').split(',').map(s => s.trim()).filter(Boolean)
+
+    tasks.push({
+      id: match[1].trim(),
+      title: match[2].trim(),
+      file: match[3].trim(),
+      action: match[4].trim(),
+      description: match[5].trim(),
+      modification_points: modPoints,
+      implementation: match[7].trim().split('\n').map(s => s.replace(/^\d+\. /, '')).filter(Boolean),
+      reference,
+      acceptance: match[9].trim().split('\n').map(s => s.replace(/^- /, '')).filter(Boolean),
+      depends_on
+    })
+  }
+  return tasks
+}
+
+// Parse flow control section
+function extractFlowControl(cliOutput) {
+  const flowMatch = /## Flow Control\n\*\*Execution Order\*\*:\n((?:- .+?\n)+)/m.exec(cliOutput)
+  const exitMatch = /\*\*Exit Conditions\*\*:\n- Success: (.+?)\n- Failure: (.+)/m.exec(cliOutput)
+
+  const execution_order = []
+  if (flowMatch) {
+    flowMatch[1].trim().split('\n').forEach(line => {
+      const m = /- Phase (.+?): \[(.+?)\] \((.+?)\)/.exec(line)
+      if (m) execution_order.push({ phase: m[1], tasks: m[2].split(',').map(s => s.trim()), type: m[3].includes('independent') ? 'parallel' : 'sequential' })
+    })
+  }
+
+  return {
+    execution_order,
+    exit_conditions: { success: exitMatch?.[1] || "All acceptance criteria met", failure: exitMatch?.[2] || "Critical task fails" }
+  }
+}
+
+// Parse all sections
+function parseCLIOutput(cliOutput) {
+  return {
+    summary: extractSection(cliOutput, "Implementation Summary"),
+    approach: extractSection(cliOutput, "High-Level Approach"),
+    raw_tasks: extractStructuredTasks(cliOutput),
+    flow_control: extractFlowControl(cliOutput),
+    time_estimate: extractSection(cliOutput, "Time Estimate")
+  }
+}
+```
+
+### Context Enrichment
+
+```javascript
+function buildEnrichedContext(explorationsContext, explorationAngles) {
+  const enriched = { relevant_files: [], patterns: [], dependencies: [], integration_points: [], constraints: [] }
+
+  explorationAngles.forEach(angle => {
+    const exp = explorationsContext?.[angle]
+    if (exp) {
+      enriched.relevant_files.push(...(exp.relevant_files || []))
+      enriched.patterns.push(exp.patterns || '')
+      enriched.dependencies.push(exp.dependencies || '')
+      enriched.integration_points.push(exp.integration_points || '')
+      enriched.constraints.push(exp.constraints || '')
+    }
+  })
+
+  enriched.relevant_files = [...new Set(enriched.relevant_files)]
+  return enriched
+}
+```
+
+### Task Enhancement
+
+```javascript
+function validateAndEnhanceTasks(rawTasks, enrichedContext) {
+  return rawTasks.map((task, idx) => ({
+    id: task.id || `T${idx + 1}`,
+    title: task.title || "Unnamed task",
+    file: task.file || inferFile(task, enrichedContext),
+    action: task.action || inferAction(task.title),
+    description: task.description || task.title,
+    modification_points: task.modification_points?.length > 0
+      ? task.modification_points
+      : [{ file: task.file, target: "main", change: task.description }],
+    implementation: task.implementation?.length >= 2
+      ? task.implementation
+      : [`Analyze ${task.file}`, `Implement ${task.title}`, `Add error handling`],
+    reference: task.reference || { pattern: "existing patterns", files: enrichedContext.relevant_files.slice(0, 2), examples: "Follow existing structure" },
+    acceptance: task.acceptance?.length >= 1
+      ? task.acceptance
+      : [`${task.title} completed`, `Follows conventions`],
+    depends_on: task.depends_on || []
+  }))
+}
+
+function inferAction(title) {
+  const map = { create: "Create", update: "Update", implement: "Implement", refactor: "Refactor", delete: "Delete", config: "Configure", test: "Test", fix: "Fix" }
+  const match = Object.entries(map).find(([key]) => new RegExp(key, 'i').test(title))
+  return match ? match[1] : "Implement"
+}
+
+function inferFile(task, ctx) {
+  const files = ctx?.relevant_files || []
+  return files.find(f => task.title.toLowerCase().includes(f.split('/').pop().split('.')[0].toLowerCase())) || "file-to-be-determined.ts"
+}
+```
+
+### Flow Control Inference
+
+```javascript
+function inferFlowControl(tasks) {
+  const phases = [], scheduled = new Set()
+  let num = 1
+
+  while (scheduled.size < tasks.length) {
+    const ready = tasks.filter(t => !scheduled.has(t.id) && t.depends_on.every(d => scheduled.has(d)))
+    if (!ready.length) break
+
+    const isParallel = ready.length > 1 && ready.every(t => !t.depends_on.length)
+    phases.push({ phase: `${isParallel ? 'parallel' : 'sequential'}-${num}`, tasks: ready.map(t => t.id), type: isParallel ? 'parallel' : 'sequential' })
+    ready.forEach(t => scheduled.add(t.id))
+    num++
+  }
+
+  return { execution_order: phases, exit_conditions: { success: "All acceptance criteria met", failure: "Critical task fails" } }
+}
+```
+
+### planObject Generation
+
+```javascript
+function generatePlanObject(parsed, enrichedContext, input) {
+  const tasks = validateAndEnhanceTasks(parsed.raw_tasks, enrichedContext)
+  const flow_control = parsed.flow_control?.execution_order?.length > 0 ? parsed.flow_control : inferFlowControl(tasks)
+  const focus_paths = [...new Set(tasks.flatMap(t => [t.file, ...t.modification_points.map(m => m.file)]).filter(Boolean))]
+
+  return {
+    summary: parsed.summary || `Implementation plan for: ${input.task_description.slice(0, 100)}`,
+    approach: parsed.approach || "Step-by-step implementation",
+    tasks,
+    flow_control,
+    focus_paths,
+    estimated_time: parsed.time_estimate || `${tasks.length * 30} minutes`,
+    recommended_execution: input.complexity === "Low" ? "Agent" : "Codex",
+    complexity: input.complexity,
+    _metadata: { timestamp: new Date().toISOString(), source: "cli-lite-planning-agent", planning_mode: "agent-based", exploration_angles: input.explorationAngles || [], duration_seconds: Math.round((Date.now() - startTime) / 1000) }
+  }
+}
+```
+
+### Error Handling
+
+```javascript
+// Fallback chain: Gemini → Qwen → degraded mode
+try {
+  result = executeCLI("gemini", config)
+} catch (error) {
+  if (error.code === 429 || error.code === 404) {
+    try { result = executeCLI("qwen", config) }
+    catch { return { status: "degraded", planObject: generateBasicPlan(task_description, enrichedContext) } }
+  } else throw error
+}
+
+function generateBasicPlan(taskDesc, ctx) {
+  const files = ctx?.relevant_files || []
+  const tasks = [taskDesc].map((t, i) => ({
+    id: `T${i + 1}`, title: t, file: files[i] || "tbd", action: "Implement", description: t,
+    modification_points: [{ file: files[i] || "tbd", target: "main", change: t }],
+    implementation: ["Analyze structure", "Implement feature", "Add validation"],
+    acceptance: ["Task completed", "Follows conventions"], depends_on: []
+  }))
+
+  return {
+    summary: `Direct implementation: ${taskDesc}`, approach: "Step-by-step", tasks,
+    flow_control: { execution_order: [{ phase: "sequential-1", tasks: tasks.map(t => t.id), type: "sequential" }], exit_conditions: { success: "Done", failure: "Fails" } },
+    focus_paths: files, estimated_time: "30 minutes", recommended_execution: "Agent", complexity: "Low",
+    _metadata: { timestamp: new Date().toISOString(), source: "cli-lite-planning-agent", planning_mode: "direct", exploration_angles: [], duration_seconds: 0 }
+  }
+}
+```
+
+## Quality Standards
+
+### Task Validation
+
+```javascript
+function validateTask(task) {
+  const errors = []
+  if (!/^T\d+$/.test(task.id)) errors.push("Invalid task ID")
+  if (!task.title?.trim()) errors.push("Missing title")
+  if (!task.file?.trim()) errors.push("Missing file")
+  if (!['Create', 'Update', 'Implement', 'Refactor', 'Add', 'Delete', 'Configure', 'Test', 'Fix'].includes(task.action)) errors.push("Invalid action")
+  if (!task.implementation?.length >= 2) errors.push("Need 2+ implementation steps")
+  if (!task.acceptance?.length >= 1) errors.push("Need 1+ acceptance criteria")
+  if (task.depends_on?.some(d => !/^T\d+$/.test(d))) errors.push("Invalid dependency format")
+  if (task.acceptance?.some(a => /works correctly|good performance/i.test(a))) errors.push("Vague acceptance criteria")
+  return { valid: !errors.length, errors }
+}
+```
+
+### Acceptance Criteria
+
+| ✓ Good | ✗ Bad |
+|--------|-------|
+| "3 methods: login(), logout(), validate()" | "Service works correctly" |
+| "Response time < 200ms p95" | "Good performance" |
+| "Covers 80% of edge cases" | "Properly implemented" |
+
+## Key Reminders
+
+**ALWAYS**:
+- Generate task IDs (T1, T2, T3...)
+- Include depends_on (even if empty [])
+- Quantify acceptance criteria
+- Generate flow_control from dependencies
+- Handle CLI errors with fallback chain
+
+**NEVER**:
+- Execute implementation (return plan only)
+- Use vague acceptance criteria
+- Create circular dependencies
+- Skip task validation

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

@@ -10,7 +10,7 @@ description: |
     commentary: Agent encapsulates CLI execution + result parsing + task generation
 
   - Context: Coverage gap analysis
-    user: "Analyze coverage gaps and generate补充test task"
+    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
@@ -18,12 +18,11 @@ 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 Responsibilities
-
-1. **Execute CLI Analysis**: Run Gemini/Qwen with appropriate templates and context
-2. **Parse CLI Results**: Extract structured information (fix strategies, root causes, modification points)
-3. **Generate Task JSONs**: Create IMPL-fix-N.json or IMPL-supplement-N.json dynamically
-4. **Save Analysis Reports**: Store detailed CLI output as iteration-N-analysis.md
+**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
 
@@ -43,7 +42,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
         "file": "tests/test_auth.py",
         "line": 45,
         "criticality": "high",
-        "test_type": "integration"  // ← NEW: L0: static, L1: unit, L2: integration, L3: e2e
+        "test_type": "integration"  // L0: static, L1: unit, L2: integration, L3: e2e
       }
     ],
     "error_messages": ["error1", "error2"],
@@ -61,7 +60,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
     "tool": "gemini|qwen",
     "model": "gemini-3-pro-preview-11-2025|qwen-coder-model",
     "template": "01-diagnose-bug-root-cause.txt",
-    "timeout": 2400000,
+    "timeout": 2400000,  // 40 minutes for analysis
     "fallback": "qwen"
   },
   "task_config": {
@@ -79,16 +78,16 @@ You are a specialized execution agent that bridges CLI analysis tools with task
 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
+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
+   - Root cause analysis (RCA)
    - Fix strategy and approach
    - Modification points (files, functions, line numbers)
-   - Expected outcome
+   - Expected outcome and verification steps
 2. Extract quantified requirements:
    - Number of files to modify
    - Specific functions to fix (with line numbers)
@@ -96,18 +95,18 @@ Phase 2: Results Parsing & Strategy Extraction
 3. Generate structured analysis report (iteration-N-analysis.md)
 
 Phase 3: Task JSON Generation
-1. Load task JSON template (defined below)
+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}/.task/IMPL-fix-N.json
+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 Command Construction
+### 1. CLI Analysis Execution
 
-**Template-Based Approach with Test Layer Awareness**:
+**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}
@@ -136,7 +135,7 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
 - Consider previous iteration failures
 - Validate fix doesn't introduce new vulnerabilities
 - analysis=READ-ONLY
-" -m {model} {timeout_flag}
+" {timeout_flag}
 ```
 
 **Layer-Specific Guidance Injection**:
@@ -151,8 +150,9 @@ const layerGuidance = {
 const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches";
 ```
 
-**Error Handling & Fallback**:
+**Error Handling & Fallback Strategy**:
 ```javascript
+// Primary execution with fallback chain
 try {
   result = executeCLI("gemini", config);
 } catch (error) {
@@ -173,16 +173,18 @@ try {
     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
+}
 ```
 
-**Fallback Strategy (When All CLI Tools Fail)**:
-- Generate basic fix task based on error patterns 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 (may skip iteration)
-
-### 2. CLI Output Parsing
+### 2. Output Parsing & Task Generation
 
 **Expected CLI Output Structure** (from bug diagnosis template):
 ```markdown
@@ -220,18 +222,34 @@ try {
 ```javascript
 const parsedResults = {
   root_causes: extractSection("根本原因分析"),
-  modification_points: extractModificationPoints(),
+  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;
+}
 ```
 
-### 3. Task JSON Generation (Template Definition)
-
-**Task JSON Template for IMPL-fix-N** (Simplified):
+**Task JSON Generation** (Simplified Template):
 ```json
 {
   "id": "IMPL-fix-{iteration}",
@@ -284,9 +302,7 @@ const parsedResults = {
       {
         "step": "load_analysis_context",
         "action": "Load CLI analysis report for full failure context if needed",
-        "commands": [
-          "Read({meta.analysis_report})"
-        ],
+        "commands": ["Read({meta.analysis_report})"],
         "output_to": "full_failure_analysis",
         "note": "Analysis report contains: failed_tests, error_messages, pass_rate, root causes, previous_attempts"
       }
@@ -334,19 +350,17 @@ const parsedResults = {
 
 **Template Variables Replacement**:
 - `{iteration}`: From context.iteration
-- `{test_type}`: Dominant test type from failed_tests (e.g., "integration", "unit")
+- `{test_type}`: Dominant test type from failed_tests
 - `{dominant_test_type}`: Most common test_type in failed_tests array
-- `{layer_specific_approach}`: Guidance based on test layer from layerGuidance map
+- `{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 from parsed CLI output
+- `{modification_points}`: Array of file:function:lines
 - `{timestamp}`: ISO 8601 timestamp
-- `{parent_task_id}`: ID of the parent test task (e.g., "IMPL-002")
-- `{file1}`, `{file2}`, etc.: Specific file paths from modification_points
-- `{specific_change_1}`, etc.: Change descriptions for each modification point
+- `{parent_task_id}`: ID of parent test task
 
-### 4. Analysis Report Generation
+### 3. Analysis Report Generation
 
 **Structure of iteration-N-analysis.md**:
 ```markdown
@@ -373,6 +387,7 @@ pass_rate: {pass_rate}%
 - **Error**: {test.error}
 - **File**: {test.file}:{test.line}
 - **Criticality**: {test.criticality}
+- **Test Type**: {test.test_type}
 {endforeach}
 
 ## Root Cause Analysis
@@ -403,15 +418,16 @@ See: `.process/iteration-{iteration}-cli-output.txt`
 
 ### CLI Execution Standards
 - **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
-- **Fallback Chain**: Gemini → Qwen (if Gemini fails with 429/404)
+- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
 - **Error Context**: Include full error details in failure reports
-- **Output Preservation**: Save raw CLI output for debugging
+- **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
@@ -430,19 +446,23 @@ See: `.process/iteration-{iteration}-cli-output.txt`
 - **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)
+- 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)
 
-## CLI Tool Configuration
+## Configuration & Examples
 
-### Gemini Configuration
+### CLI Tool Configuration
+
+**Gemini Configuration**:
 ```javascript
 {
   "tool": "gemini",
@@ -452,11 +472,12 @@ See: `.process/iteration-{iteration}-cli-output.txt`
     "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)
+**Qwen Configuration (Fallback)**:
 ```javascript
 {
   "tool": "qwen",
@@ -464,47 +485,12 @@ See: `.process/iteration-{iteration}-cli-output.txt`
   "templates": {
     "test-failure": "01-diagnose-bug-root-cause.txt",
     "coverage-gap": "02-analyze-code-patterns.txt"
-  }
+  },
+  "timeout": 2400000  // 40 minutes
 }
 ```
 
-## Integration with test-cycle-execute
-
-**Orchestrator Call Pattern**:
-```javascript
-// When pass_rate < 95%
-Task(
-  subagent_type="cli-planning-agent",
-  description=`Analyze test failures and generate fix task (iteration ${iteration})`,
-  prompt=`
-    ## Context Package
-    ${JSON.stringify(contextPackage, null, 2)}
-
-    ## Your Task
-    1. Execute CLI analysis using ${cli_config.tool}
-    2. Parse CLI output and extract fix strategy
-    3. Generate IMPL-fix-${iteration}.json with structured task definition
-    4. Save analysis report to .process/iteration-${iteration}-analysis.md
-    5. Report success and task ID back to orchestrator
-  `
-)
-```
-
-**Agent Response**:
-```javascript
-{
-  "status": "success",
-  "task_id": "IMPL-fix-{iteration}",
-  "task_path": ".workflow/{session}/.task/IMPL-fix-{iteration}.json",
-  "analysis_report": ".process/iteration-{iteration}-analysis.md",
-  "cli_output": ".process/iteration-{iteration}-cli-output.txt",
-  "summary": "{fix_strategy.approach first 100 chars}",
-  "modification_points_count": {count},
-  "estimated_complexity": "low|medium|high"
-}
-```
-
-## Example Execution
+### Example Execution
 
 **Input Context**:
 ```json
@@ -530,24 +516,45 @@ Task(
   "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 Steps**:
-1. Detect test_type: "integration" → Apply integration-specific diagnosis
-2. Execute: `gemini -p "PURPOSE: Analyze integration test failure... [layer-specific context]"`
-   - CLI prompt includes: "Examine component interactions, data flow, interface contracts"
-   - Guidance: "Analyze full call stack and data flow across components"
-3. Parse: Extract RCA, 修复建议, 验证建议 sections
-4. Generate: IMPL-fix-1.json (SIMPLIFIED) with:
+**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, not embedded data)
+   - meta.analysis_report: ".process/iteration-1-analysis.md" (reference)
    - meta.test_layer: "integration"
-   - Requirements: "Fix 1 integration test failures by applying the provided fix strategy"
-   - fix_strategy.modification_points: ["src/auth/auth.service.ts:validateToken:45-60", "src/middleware/auth.middleware.ts:checkExpiry:120-135"]
+   - 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}
-   - **NO failure_context object** - full context available via analysis_report reference
-5. Save: iteration-1-analysis.md with full CLI output, layer context, failed_tests details, previous_attempts
-6. Return: task_id="IMPL-fix-1", test_layer="integration", status="success"
+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`)
 
@@ -395,34 +397,12 @@ Calculate risk level based on:
 }
 ```
 
-## Execution Mode: Brainstorm vs Plan
 
-### Brainstorm Mode (Lightweight)
-**Purpose**: Provide high-level context for generating brainstorming questions
-**Execution**: Phase 1-2 only (skip deep analysis)
-**Output**:
-- Lightweight context-package with:
-  - Project structure overview
-  - Tech stack identification
-  - High-level existing module names
-  - Basic conflict risk (file count only)
-- Skip: Detailed dependency graphs, deep code analysis, web research
-
-### Plan Mode (Comprehensive)
-**Purpose**: Detailed implementation planning with conflict detection
-**Execution**: Full Phase 1-3 (complete discovery + analysis)
-**Output**:
-- Comprehensive context-package with:
-  - Detailed dependency graphs
-  - Deep code structure analysis
-  - Conflict detection with mitigation strategies
-  - Web research for unfamiliar tech
-- Include: All discovery tracks, relevance scoring, 3-source synthesis
 
 ## Quality Validation
 
 Before completion verify:
-- [ ] context-package.json in `.workflow/{session}/.process/`
+- [ ] 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 +412,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 +436,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/test-context-search-agent.md

@@ -304,7 +304,7 @@ if (!validation.all_passed()) {
 ## Output Location
 
 ```
-.workflow/{test_session_id}/.process/test-context-package.json
+.workflow/active/{test_session_id}/.process/test-context-package.json
 ```
 
 ## Helper Functions Reference
@@ -397,23 +397,3 @@ function detect_framework_from_config() {
 - ✅ 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

@@ -331,6 +331,8 @@ When generating test results for orchestrator (saved to `.process/test-results.j
 - Break existing passing tests
 - Skip final verification
 - Leave tests failing - must achieve 100% pass rate
+- Use `run_in_background` for Bash() commands - always set `run_in_background=false` to ensure tests run in foreground for proper output capture
+- Use complex bash pipe chains (`cmd | grep | awk | sed`) - prefer dedicated tools (Read, Grep, Glob) for file operations and content extraction; simple single-pipe commands are acceptable when necessary
 
 ## Quality Certification
 

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

@@ -217,11 +217,6 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
 
 ### Structure Optimization
 
-**Layout Structure Benefits**:
-- Eliminates redundancy between structure and styling
-- Layout properties co-located with DOM elements
-- Responsive overrides apply directly to affected elements
-- Single source of truth for each element
 
 **Component State Coverage**:
 - Interactive components (button, input, dropdown) MUST define: default, hover, focus, active, disabled
@@ -323,270 +318,21 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
 
 ### design-tokens.json
 
+**Template Reference**: `~/.claude/workflows/cli-templates/ui-design/systems/design-tokens.json`
+
 **Format**: W3C Design Tokens Community Group Specification
 
-**Schema Structure**:
-```json
-{
-  "$schema": "https://tr.designtokens.org/format/",
-  "name": "string - Token set name",
-  "description": "string - Token set description",
-
-  "color": {
-    "background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" }, "$description": "optional" },
-    "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-    "card": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-    "card-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-    "border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-    "input": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-    "ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-
-    "interactive": {
-      "primary": {
-        "default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-        "hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-        "active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-        "disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-        "foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
-      },
-      "secondary": { "/* Same structure as primary */" },
-      "accent": { "/* Same structure (no disabled state) */" },
-      "destructive": { "/* Same structure (no active/disabled states) */" }
-    },
-
-    "muted": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-    "muted-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-
-    "chart": {
-      "1": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-      "2": { "/* ... */" },
-      "3": { "/* ... */" },
-      "4": { "/* ... */" },
-      "5": { "/* ... */" }
-    },
-
-    "sidebar": {
-      "background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
-      "foreground": { "/* ... */" },
-      "primary": { "/* ... */" },
-      "primary-foreground": { "/* ... */" },
-      "accent": { "/* ... */" },
-      "accent-foreground": { "/* ... */" },
-      "border": { "/* ... */" },
-      "ring": { "/* ... */" }
-    }
-  },
-
-  "typography": {
-    "font_families": {
-      "sans": "string - 'Font Name', fallback1, fallback2",
-      "serif": "string",
-      "mono": "string"
-    },
-    "font_sizes": {
-      "xs": "0.75rem",
-      "sm": "0.875rem",
-      "base": "1rem",
-      "lg": "1.125rem",
-      "xl": "1.25rem",
-      "2xl": "1.5rem",
-      "3xl": "1.875rem",
-      "4xl": "2.25rem"
-    },
-    "line_heights": {
-      "tight": "number",
-      "normal": "number",
-      "relaxed": "number"
-    },
-    "letter_spacing": {
-      "tight": "string",
-      "normal": "string",
-      "wide": "string"
-    },
-    "combinations": [
-      {
-        "name": "h1|h2|h3|h4|h5|h6|body|caption",
-        "font_family": "sans|serif|mono",
-        "font_size": "string - reference to font_sizes",
-        "font_weight": "number - 400|500|600|700",
-        "line_height": "string",
-        "letter_spacing": "string"
-      }
-    ]
-  },
-
-  "spacing": {
-    "0": "0",
-    "1": "0.25rem",
-    "2": "0.5rem",
-    "/* Systematic scale: 3, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64 */"
-  },
-
-  "opacity": {
-    "disabled": "0.5",
-    "hover": "0.8",
-    "active": "1"
-  },
-
-  "shadows": {
-    "2xs": "string - CSS shadow value",
-    "xs": "string",
-    "sm": "string",
-    "DEFAULT": "string",
-    "md": "string",
-    "lg": "string",
-    "xl": "string",
-    "2xl": "string"
-  },
-
-  "border_radius": {
-    "sm": "string - calc() or fixed",
-    "md": "string",
-    "lg": "string",
-    "xl": "string",
-    "DEFAULT": "string"
-  },
-
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  },
-
-  "component": {
-    "/* COMPONENT PATTERN - Apply to: button, card, input, dialog, dropdown, toast, accordion, tabs, switch, checkbox, badge, alert */": {
-      "$type": "component",
-      "base": {
-        "/* Layout properties using camelCase */": "value or {token.path}",
-        "display": "inline-flex|flex|block",
-        "alignItems": "center",
-        "borderRadius": "{border_radius.md}",
-        "transition": "{transitions.default}"
-      },
-      "size": {
-        "small": { "height": "32px", "padding": "{spacing.2} {spacing.3}", "fontSize": "{typography.font_sizes.xs}" },
-        "default": { "height": "40px", "padding": "{spacing.2} {spacing.4}" },
-        "large": { "height": "48px", "padding": "{spacing.3} {spacing.6}", "fontSize": "{typography.font_sizes.base}" }
-      },
-      "variant": {
-        "variantName": {
-          "default": { "backgroundColor": "{color.interactive.primary.default}", "color": "{color.interactive.primary.foreground}" },
-          "hover": { "backgroundColor": "{color.interactive.primary.hover}" },
-          "active": { "backgroundColor": "{color.interactive.primary.active}" },
-          "disabled": { "backgroundColor": "{color.interactive.primary.disabled}", "opacity": "{opacity.disabled}", "cursor": "not-allowed" },
-          "focus": { "outline": "2px solid {color.ring}", "outlineOffset": "2px" }
-        }
-      },
-      "state": {
-        "/* For stateful components (dialog, accordion, etc.) */": {
-          "open": { "animation": "{animation.name.component-open} {animation.duration.normal} {animation.easing.ease-out}" },
-          "closed": { "animation": "{animation.name.component-close} {animation.duration.normal} {animation.easing.ease-in}" }
-        }
-      }
-    }
-  },
-
-  "elevation": {
-    "$type": "elevation",
-    "base": { "$value": "0" },
-    "overlay": { "$value": "40" },
-    "dropdown": { "$value": "50" },
-    "dialog": { "$value": "50" },
-    "tooltip": { "$value": "60" }
-  },
-
-  "_metadata": {
-    "version": "string - W3C version or custom version",
-    "created": "ISO timestamp - 2024-01-01T00:00:00Z",
-    "source": "code-import|explore|text",
-    "theme_colors_guide": {
-      "description": "Theme colors are the core brand identity colors that define the visual hierarchy and emotional tone of the design system",
-      "primary": {
-        "role": "Main brand color",
-        "usage": "Primary actions (CTAs, key interactive elements, navigation highlights, primary buttons)",
-        "contrast_requirement": "WCAG AA - 4.5:1 for text, 3:1 for UI components"
-      },
-      "secondary": {
-        "role": "Supporting brand color",
-        "usage": "Secondary actions and complementary elements (less prominent buttons, secondary navigation, supporting features)",
-        "principle": "Should complement primary without competing for attention"
-      },
-      "accent": {
-        "role": "Highlight color for emphasis",
-        "usage": "Attention-grabbing elements used sparingly (badges, notifications, special promotions, highlights)",
-        "principle": "Should create strong visual contrast to draw focus"
-      },
-      "destructive": {
-        "role": "Error and destructive action color",
-        "usage": "Delete buttons, error messages, critical warnings",
-        "principle": "Must signal danger or caution clearly"
-      },
-      "harmony_note": "All theme colors must work harmoniously together and align with brand identity. In multi-file extraction, prioritize definitions with semantic comments explaining brand intent."
-    },
-    "conflicts": [
-      {
-        "token_name": "string - which token has conflicts",
-        "category": "string - colors|typography|etc",
-        "definitions": [
-          {
-            "value": "string - token value",
-            "source_file": "string - absolute path",
-            "line_number": "number",
-            "context": "string - surrounding comment or null",
-            "semantic_intent": "string - interpretation of definition"
-          }
-        ],
-        "selected_value": "string - final chosen value",
-        "selection_reason": "string - why this value was chosen"
-      }
-    ],
-    "code_snippets": [
-      {
-        "category": "colors|typography|spacing|shadows|border_radius|component",
-        "token_name": "string - which token this snippet defines",
-        "source_file": "string - absolute path",
-        "line_start": "number",
-        "line_end": "number",
-        "snippet": "string - complete code block",
-        "context_type": "css-variable|css-class|js-object|scss-variable|etc"
-      }
-    ],
-    "usage_recommendations": {
-      "typography": {
-        "common_sizes": {
-          "small_text": "sm (0.875rem)",
-          "body_text": "base (1rem)",
-          "heading": "2xl-4xl"
-        },
-        "common_combinations": [
-          {
-            "name": "Heading + Body",
-            "heading": "2xl",
-            "body": "base",
-            "use_case": "Article sections"
-          }
-        ]
-      },
-      "spacing": {
-        "size_guide": {
-          "tight": "1-2 (0.25rem-0.5rem)",
-          "normal": "4-6 (1rem-1.5rem)",
-          "loose": "8-12 (2rem-3rem)"
-        },
-        "common_patterns": [
-          {
-            "pattern": "padding-4 margin-bottom-6",
-            "use_case": "Card content spacing",
-            "pixel_value": "1rem padding, 1.5rem margin"
-          }
-        ]
-      }
-    }
-  }
-}
-```
+**Structure Overview**:
+- **color**: Base colors, interactive states (primary, secondary, accent, destructive), muted, chart, sidebar
+- **typography**: Font families, sizes, line heights, letter spacing, combinations
+- **spacing**: Systematic scale (0-64, multiples of 0.25rem)
+- **opacity**: disabled, hover, active
+- **shadows**: 2xs to 2xl (8-tier system)
+- **border_radius**: sm to xl + DEFAULT
+- **breakpoints**: sm to 2xl
+- **component**: 12+ components with base, size, variant, state structures
+- **elevation**: z-index values for layered components
+- **_metadata**: version, created, source, theme_colors_guide, conflicts, code_snippets, usage_recommendations
 
 **Required Components** (12+ components, use pattern above):
 - **button**: 5 variants (primary, secondary, destructive, outline, ghost) + 3 sizes + states (default, hover, active, disabled, focus)
@@ -637,136 +383,26 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
 
 ### layout-templates.json
 
+**Template Reference**: `~/.claude/workflows/cli-templates/ui-design/systems/layout-templates.json`
+
 **Optimization**: Unified structure combining DOM and styling into single hierarchy
 
-**Schema Structure**:
-```json
-{
-  "$schema": "https://tr.designtokens.org/format/",
-  "templates": [
-    {
-      "target": "string - page/component name (e.g., hero-section, product-card)",
-      "description": "string - layout description",
-      "component_type": "universal|specialized",
-      "device_type": "mobile|tablet|desktop|responsive",
-      "layout_strategy": "string - grid-3col|flex-row|stack|sidebar|etc",
-
-      "structure": {
-        "tag": "string - HTML5 semantic tag (header|nav|main|section|article|aside|footer|div|etc)",
-        "attributes": {
-          "class": "string - semantic class name",
-          "role": "string - ARIA role (navigation|main|complementary|etc)",
-          "aria-label": "string - ARIA label",
-          "aria-describedby": "string - ARIA describedby",
-          "data-state": "string - data attributes for state management (open|closed|etc)"
-        },
-        "layout": {
-          "/* LAYOUT PROPERTIES ONLY - Use camelCase for property names */": "",
-          "display": "grid|flex|block|inline-flex",
-          "grid-template-columns": "{spacing.*} or CSS value (repeat(3, 1fr))",
-          "grid-template-rows": "string",
-          "gap": "{spacing.*}",
-          "padding": "{spacing.*}",
-          "margin": "{spacing.*}",
-          "alignItems": "start|center|end|stretch",
-          "justifyContent": "start|center|end|space-between|space-around",
-          "flexDirection": "row|column",
-          "flexWrap": "wrap|nowrap",
-          "position": "relative|absolute|fixed|sticky",
-          "top|right|bottom|left": "string",
-          "width": "string",
-          "height": "string",
-          "maxWidth": "string",
-          "minHeight": "string"
-        },
-        "responsive": {
-          "/* ONLY properties that CHANGE at each breakpoint - NO repetition */": "",
-          "sm": {
-            "grid-template-columns": "1fr",
-            "padding": "{spacing.4}"
-          },
-          "md": {
-            "grid-template-columns": "repeat(2, 1fr)",
-            "gap": "{spacing.6}"
-          },
-          "lg": {
-            "grid-template-columns": "repeat(3, 1fr)"
-          }
-        },
-        "children": [
-          {
-            "/* Recursive structure - same fields as parent */": "",
-            "tag": "string",
-            "attributes": {},
-            "layout": {},
-            "responsive": {},
-            "children": [],
-            "content": "string or {{placeholder}}"
-          }
-        ],
-        "content": "string - text content or {{placeholder}} for dynamic content"
-      },
-
-      "accessibility": {
-        "patterns": [
-          "string - ARIA patterns used (e.g., WAI-ARIA Tabs pattern, Dialog pattern)"
-        ],
-        "keyboard_navigation": [
-          "string - keyboard shortcuts (e.g., Tab/Shift+Tab navigation, Escape to close)"
-        ],
-        "focus_management": "string - focus trap strategy, initial focus target",
-        "screen_reader_notes": [
-          "string - screen reader announcements (e.g., Dialog opened, Tab selected)"
-        ]
-      },
-
-      "usage_guide": {
-        "common_sizes": {
-          "small": {
-            "dimensions": "string - e.g., px-3 py-1.5 (height: ~32px)",
-            "use_case": "string - Compact UI, mobile views"
-          },
-          "medium": {
-            "dimensions": "string - e.g., px-4 py-2 (height: ~40px)",
-            "use_case": "string - Default size for most contexts"
-          },
-          "large": {
-            "dimensions": "string - e.g., px-6 py-3 (height: ~48px)",
-            "use_case": "string - Prominent CTAs, hero sections"
-          }
-        },
-        "variant_recommendations": {
-          "variant_name": {
-            "description": "string - when to use this variant",
-            "typical_actions": ["string - action examples"]
-          }
-        },
-        "usage_context": [
-          "string - typical usage scenarios (e.g., Landing page hero, Product listing grid)"
-        ],
-        "accessibility_tips": [
-          "string - accessibility best practices (e.g., Ensure heading hierarchy, Add aria-label)"
-        ]
-      },
-
-      "extraction_metadata": {
-        "source": "code-import|explore|text",
-        "created": "ISO timestamp",
-        "code_snippets": [
-          {
-            "component_name": "string - which layout component",
-            "source_file": "string - absolute path",
-            "line_start": "number",
-            "line_end": "number",
-            "snippet": "string - complete HTML/CSS/JS code block",
-            "context_type": "html-structure|css-utility|react-component|vue-component|etc"
-          }
-        ]
-      }
-    }
-  ]
-}
-```
+**Structure Overview**:
+- **templates[]**: Array of layout templates
+  - **target**: page/component name (hero-section, product-card)
+  - **component_type**: universal | specialized
+  - **device_type**: mobile | tablet | desktop | responsive
+  - **layout_strategy**: grid-3col, flex-row, stack, sidebar, etc.
+  - **structure**: Unified DOM + layout hierarchy
+    - **tag**: HTML5 semantic tags
+    - **attributes**: class, role, aria-*, data-state
+    - **layout**: Layout properties only (display, grid, flex, position, spacing) using {token.path}
+    - **responsive**: Breakpoint-specific overrides (ONLY changed properties)
+    - **children**: Recursive structure
+    - **content**: Text or {{placeholder}}
+  - **accessibility**: patterns, keyboard_navigation, focus_management, screen_reader_notes
+  - **usage_guide**: common_sizes, variant_recommendations, usage_context, accessibility_tips
+  - **extraction_metadata**: source, created, code_snippets
 
 **Field Rules**:
 - $schema MUST reference W3C Design Tokens format specification
@@ -784,149 +420,25 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
 - usage_guide OPTIONAL for specialized components (can be simplified or omitted)
 - extraction_metadata.code_snippets ONLY present in Code Import mode
 
-**Structure Optimization Benefits**:
-- Eliminates redundancy between dom_structure and css_layout_rules
-- Layout properties are co-located with corresponding DOM elements
-- Responsive overrides apply directly to the element they affect
-- Single source of truth for each element's structure and layout
-- Easier to maintain and understand hierarchy
+
 
 ### animation-tokens.json
 
-**Schema Structure**:
-```json
-{
-  "$schema": "https://tr.designtokens.org/format/",
+**Template Reference**: `~/.claude/workflows/cli-templates/ui-design/systems/animation-tokens.json`
 
-  "duration": {
-    "$type": "duration",
-    "instant": { "$value": "0ms" },
-    "fast": { "$value": "150ms" },
-    "normal": { "$value": "300ms" },
-    "slow": { "$value": "500ms" },
-    "slower": { "$value": "1000ms" }
-  },
-
-  "easing": {
-    "$type": "cubicBezier",
-    "linear": { "$value": "linear" },
-    "ease-in": { "$value": "cubic-bezier(0.4, 0, 1, 1)" },
-    "ease-out": { "$value": "cubic-bezier(0, 0, 0.2, 1)" },
-    "ease-in-out": { "$value": "cubic-bezier(0.4, 0, 0.2, 1)" },
-    "spring": { "$value": "cubic-bezier(0.68, -0.55, 0.265, 1.55)" },
-    "bounce": { "$value": "cubic-bezier(0.68, -0.6, 0.32, 1.6)" }
-  },
-
-  "keyframes": {
-    "/* PATTERN: Define pairs (in/out, open/close, enter/exit) */": {
-      "0%": { "/* CSS properties */": "value" },
-      "100%": { "/* CSS properties */": "value" }
-    },
-    "/* Required keyframes for components: */": "",
-    "fade-in": { "0%": { "opacity": "0" }, "100%": { "opacity": "1" } },
-    "fade-out": { "/* reverse of fade-in */" },
-    "slide-up": { "0%": { "transform": "translateY(10px)", "opacity": "0" }, "100%": { "transform": "translateY(0)", "opacity": "1" } },
-    "slide-down": { "/* reverse direction */" },
-    "scale-in": { "0%": { "transform": "scale(0.95)", "opacity": "0" }, "100%": { "transform": "scale(1)", "opacity": "1" } },
-    "scale-out": { "/* reverse of scale-in */" },
-    "accordion-down": { "0%": { "height": "0", "opacity": "0" }, "100%": { "height": "var(--radix-accordion-content-height)", "opacity": "1" } },
-    "accordion-up": { "/* reverse */" },
-    "dialog-open": { "0%": { "transform": "translate(-50%, -48%) scale(0.96)", "opacity": "0" }, "100%": { "transform": "translate(-50%, -50%) scale(1)", "opacity": "1" } },
-    "dialog-close": { "/* reverse */" },
-    "dropdown-open": { "0%": { "transform": "scale(0.95) translateY(-4px)", "opacity": "0" }, "100%": { "transform": "scale(1) translateY(0)", "opacity": "1" } },
-    "dropdown-close": { "/* reverse */" },
-    "toast-enter": { "0%": { "transform": "translateX(100%)", "opacity": "0" }, "100%": { "transform": "translateX(0)", "opacity": "1" } },
-    "toast-exit": { "/* reverse */" },
-    "spin": { "0%": { "transform": "rotate(0deg)" }, "100%": { "transform": "rotate(360deg)" } },
-    "pulse": { "0%, 100%": { "opacity": "1" }, "50%": { "opacity": "0.5" } }
-  },
-
-  "interactions": {
-    "/* PATTERN: Define for each interactive component state */": {
-      "property": "string - CSS properties (comma-separated)",
-      "duration": "{duration.*}",
-      "easing": "{easing.*}"
-    },
-    "button-hover": { "property": "background-color, transform", "duration": "{duration.fast}", "easing": "{easing.ease-out}" },
-    "button-active": { "property": "transform", "duration": "{duration.instant}", "easing": "{easing.ease-in}" },
-    "card-hover": { "property": "box-shadow, transform", "duration": "{duration.normal}", "easing": "{easing.ease-in-out}" },
-    "input-focus": { "property": "border-color, box-shadow", "duration": "{duration.fast}", "easing": "{easing.ease-out}" },
-    "dropdown-toggle": { "property": "opacity, transform", "duration": "{duration.fast}", "easing": "{easing.ease-out}" },
-    "accordion-toggle": { "property": "height, opacity", "duration": "{duration.normal}", "easing": "{easing.ease-in-out}" },
-    "dialog-toggle": { "property": "opacity, transform", "duration": "{duration.normal}", "easing": "{easing.spring}" },
-    "tabs-switch": { "property": "color, border-color", "duration": "{duration.fast}", "easing": "{easing.ease-in-out}" }
-  },
-
-  "transitions": {
-    "default": { "$value": "all {duration.normal} {easing.ease-in-out}" },
-    "colors": { "$value": "color {duration.fast} {easing.linear}, background-color {duration.fast} {easing.linear}" },
-    "transform": { "$value": "transform {duration.normal} {easing.spring}" },
-    "opacity": { "$value": "opacity {duration.fast} {easing.linear}" },
-    "all-smooth": { "$value": "all {duration.slow} {easing.ease-in-out}" }
-  },
-
-  "component_animations": {
-    "/* PATTERN: Map each component to its animations - MUST match design-tokens.json component list */": {
-      "stateOrInteraction": {
-        "animation": "keyframe-name {duration.*} {easing.*} OR none",
-        "transition": "{interactions.*} OR none"
-      }
-    },
-    "button": {
-      "hover": { "animation": "none", "transition": "{interactions.button-hover}" },
-      "active": { "animation": "none", "transition": "{interactions.button-active}" }
-    },
-    "card": {
-      "hover": { "animation": "none", "transition": "{interactions.card-hover}" }
-    },
-    "input": {
-      "focus": { "animation": "none", "transition": "{interactions.input-focus}" }
-    },
-    "dialog": {
-      "open": { "animation": "dialog-open {duration.normal} {easing.spring}" },
-      "close": { "animation": "dialog-close {duration.normal} {easing.ease-in}" }
-    },
-    "dropdown": {
-      "open": { "animation": "dropdown-open {duration.fast} {easing.ease-out}" },
-      "close": { "animation": "dropdown-close {duration.fast} {easing.ease-in}" }
-    },
-    "toast": {
-      "enter": { "animation": "toast-enter {duration.normal} {easing.ease-out}" },
-      "exit": { "animation": "toast-exit {duration.normal} {easing.ease-in}" }
-    },
-    "accordion": {
-      "open": { "animation": "accordion-down {duration.normal} {easing.ease-out}" },
-      "close": { "animation": "accordion-up {duration.normal} {easing.ease-in}" }
-    },
-    "/* Add mappings for: tabs, switch, checkbox, badge, alert */" : {}
-  },
-
-  "accessibility": {
-    "prefers_reduced_motion": {
-      "duration": "0ms",
-      "keyframes": {},
-      "note": "Disable animations when user prefers reduced motion",
-      "css_rule": "@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; } }"
-    }
-  },
-
-  "_metadata": {
-    "version": "string",
-    "created": "ISO timestamp",
-    "source": "code-import|explore|text",
-    "code_snippets": [
-      {
-        "animation_name": "string - keyframe/transition name",
-        "source_file": "string - absolute path",
-        "line_start": "number",
-        "line_end": "number",
-        "snippet": "string - complete @keyframes or transition code",
-        "context_type": "css-keyframes|css-transition|js-animation|scss-animation|etc"
-      }
-    ]
-  }
-}
-```
+**Structure Overview**:
+- **duration**: instant (0ms), fast (150ms), normal (300ms), slow (500ms), slower (1000ms)
+- **easing**: linear, ease-in, ease-out, ease-in-out, spring, bounce
+- **keyframes**: Animation definitions in pairs (in/out, open/close, enter/exit)
+  - Required: fade-in/out, slide-up/down, scale-in/out, accordion-down/up, dialog-open/close, dropdown-open/close, toast-enter/exit, spin, pulse
+- **interactions**: Component interaction animations with property, duration, easing
+  - button-hover/active, card-hover, input-focus, dropdown-toggle, accordion-toggle, dialog-toggle, tabs-switch
+- **transitions**: default, colors, transform, opacity, all-smooth
+- **component_animations**: Maps components to animations (MUST match design-tokens.json components)
+  - State-based: dialog, dropdown, toast, accordion (use keyframes)
+  - Interaction: button, card, input, tabs (use transitions)
+- **accessibility**: prefers_reduced_motion with CSS rule
+- **_metadata**: version, created, source, code_snippets
 
 **Field Rules**:
 - $schema MUST reference W3C Design Tokens format specification

.claude/commands/cli/analyze.md

@@ -1,87 +0,0 @@
----
-name: analyze
-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(*)
----
-
-# CLI Analyze Command (/cli:analyze)
-
-## Purpose
-
-Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
-
-**Tool Selection**:
-- **gemini** (default) - Best for code analysis
-- **qwen** - Fallback when Gemini unavailable
-- **codex** - Alternative for deep analysis
-
-## Parameters
-
-- `--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
-
-Uses **cli-execution-agent** (default) for automated analysis:
-
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Codebase analysis with pattern detection",
-  prompt=`
-    Task: ${analysis_target}
-    Mode: analyze
-    Tool: ${tool_flag || 'gemini'}
-    Enhance: ${enhance_flag}
-
-    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/WFS-[id]/.chat/analyze-[timestamp].md (or .scratchpad/)
-  `
-)
-```
-
-## Core Rules
-
-- **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/WFS-[id]/.chat/analyze-[timestamp].md` (or `.scratchpad/` if no session)

.claude/commands/cli/chat.md

@@ -1,82 +0,0 @@
----
-name: chat
-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(*)
----
-
-# CLI Chat Command (/cli:chat)
-
-## Purpose
-
-Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does NOT modify code**.
-
-**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
-
-## Tool Usage
-
-**Gemini** (Primary):
-```bash
---tool gemini  # or omit (default)
-```
-
-**Qwen** (Fallback):
-```bash
---tool qwen
-```
-
-**Codex** (Alternative):
-```bash
---tool codex
-```
-
-## Execution Flow
-
-Uses **cli-execution-agent** (default) for automated Q&A:
-
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Codebase Q&A with intelligent context discovery",
-  prompt=`
-    Task: ${inquiry}
-    Mode: chat
-    Tool: ${tool_flag || 'gemini'}
-    Enhance: ${enhance_flag}
-
-    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/WFS-[id]/.chat/chat-[timestamp].md (or .scratchpad/)
-  `
-)
-```
-
-## Core Rules
-
-- **Read-only**: Provides answers, does NOT modify code
-- **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`)
-- **Output**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md` (or `.scratchpad/` if no session)

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

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

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

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

.claude/commands/cli/execute.md

@@ -1,202 +0,0 @@
----
-name: execute
-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(*)
----
-
-# CLI Execute Command (/cli:execute)
-
-## Purpose
-
-Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations). **MODIFIES CODE**.
-
-**Intent**: Autonomous code implementation, modification, and generation
-**Supported Tools**: codex, gemini (default), qwen
-**Key Feature**: Automatic context inference and file pattern detection
-
-## Core Behavior
-
-1. **Code Modification**: This command MODIFIES, CREATES, and DELETES code files
-2. **Auto-Approval**: YOLO mode bypasses confirmation prompts for all operations
-3. **Implementation Focus**: Executes actual code changes, not just recommendations
-4. **Requires Explicit Intent**: Use only when implementation is intended
-
-## Core Concepts
-
-### YOLO Permissions
-Auto-approves: file pattern inference, execution, **file modifications**, summary generation
-
-**WARNING**: This command will make actual code changes without manual confirmation
-
-### Execution Modes
-
-**1. Description Mode** (supports `--enhance`):
-- Input: Natural language description
-- Process: [Optional: Enhance] → Keyword analysis → Pattern inference → Execute
-
-**2. Task ID Mode** (no `--enhance`):
-- Input: Workflow task identifier (e.g., `IMPL-001`)
-- Process: Task JSON parsing → Scope analysis → Execute
-
-**3. Agent Mode** (default):
-- Input: Description or task-id
-- Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute
-
-### Context Inference
-
-Auto-selects files based on keywords and technology (each @ references one pattern):
-- "auth" → `@**/*auth* @**/*user*`
-- "React" → `@src/**/*.jsx @src/**/*.tsx`
-- "api" → `@**/api/**/* @**/routes/**/*`
-- Always includes: `@CLAUDE.md @**/*CLAUDE.md`
-
-For precise file targeting, use `rg` or MCP tools to discover files first.
-
-### Codex Session Continuity
-
-**Resume Pattern** for related tasks:
-```bash
-# First task - establish session
-codex -C [dir] --full-auto exec "[task]" --skip-git-repo-check -s danger-full-access
-
-# Related task - continue session
-codex --full-auto exec "[related-task]" resume --last --skip-git-repo-check -s danger-full-access
-```
-
-Use `resume --last` when current task extends/relates to previous execution. See intelligent-tools-strategy.md for auto-resume rules.
-
-## Parameters
-
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: 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
-- `--save-session` - Save execution to workflow session
-
-## Workflow Integration
-
-**Session Management**: Auto-detects `.workflow/.active-*` marker
-- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-- No session: Create new session or save to scratchpad
-
-**Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
-
-## Execution Flow
-
-Uses **cli-execution-agent** (default) for automated implementation:
-
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Autonomous code implementation with YOLO auto-approval",
-  prompt=`
-    Task: ${description_or_task_id}
-    Mode: execute
-    Tool: ${tool_flag || 'auto-select'}
-    Enhance: ${enhance_flag}
-    Task-ID: ${task_id}
-
-    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/WFS-[id]/.chat/execute-[timestamp].md
-       ${task_id ? '- Generate task summary: .workflow/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
-  `
-)
-```
-
-**Output**: `.workflow/WFS-[id]/.chat/execute-[timestamp].md` + `.summaries/[TASK-ID]-summary.md` (or `.scratchpad/` if no session)
-
-## Examples
-
-**Basic Implementation** (modifies code):
-```bash
-/cli:execute "implement JWT authentication with middleware"
-# 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
-```
-
-**Complex Implementation** (modifies code):
-```bash
-/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):
-```bash
-/cli:execute --enhance "implement JWT authentication"
-# Step 1: Enhance to expand requirements
-# Step 2: Execute implementation with auto-approval
-# Result: Complete auth system with MODIFIED code files
-```
-
-**Task Execution** (modifies code):
-```bash
-/cli:execute IMPL-001
-# Reads: .task/IMPL-001.json for requirements
-# Executes: Implementation based on task spec
-# Result: Code changes per task definition
-```
-
-**Codex Implementation** (modifies code):
-```bash
-/cli:execute --tool codex "optimize database queries"
-# Executes: Codex with full file access
-# Result: MODIFIED query code, new indexes, updated tests
-```
-
-**Qwen Code Generation** (modifies code):
-```bash
-/cli:execute --tool qwen --enhance "refactor auth module"
-# Step 1: Enhanced refactoring plan
-# Step 2: Execute with MODE=write
-# Result: REFACTORED auth code with structural changes
-```
-
-## Comparison with Analysis Commands
-
-| Command | Intent | Code Changes | Auto-Approve |
-|---------|--------|--------------|--------------|
-| `/cli:analyze` | Understand code | NO | N/A |
-| `/cli:chat` | Ask questions | NO | N/A |
-| `/cli:execute` | **Implement** | **YES** | **YES** |

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

@@ -1,96 +0,0 @@
----
-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/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/WFS-[id]/.chat/bug-diagnosis-[timestamp].md` (or `.scratchpad/` if no session)

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

@@ -1,98 +0,0 @@
----
-name: code-analysis
-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(*)
----
-
-# CLI Mode: Code Analysis (/cli:mode:code-analysis)
-
-## Purpose
-
-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
-
-**Key Feature**: `--cd` flag for directory-scoped analysis
-
-## Parameters
-
-- `--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
-
-Uses **cli-execution-agent** (default) for automated code analysis:
-
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Execution path tracing and call flow analysis",
-  prompt=`
-    Task: ${analysis_target}
-    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
-
-    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/WFS-[id]/.chat/code-analysis-[timestamp].md (or .scratchpad/)
-  `
-)
-```
-
-## Core Rules
-
-- **Read-only**: Analyzes code, does NOT modify files
-- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
-- **Output**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md` (or `.scratchpad/` if no session)

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

@@ -1,93 +0,0 @@
----
-name: plan
-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(*)
----
-
-# CLI Mode: Plan (/cli:mode:plan)
-
-## Purpose
-
-Strategic software architecture planning template (`~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`).
-
-**Tool Selection**:
-- **gemini** (default) - Best for architecture planning
-- **qwen** - Fallback when Gemini unavailable
-- **codex** - Alternative for implementation planning
-
-## Parameters
-
-- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--enhance` - Enhance task with `/enhance-prompt`
-- `--cd "path"` - Target directory for focused planning
-- `<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
-
-Uses **cli-execution-agent** (default) for automated planning:
-
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Architecture planning with impact analysis",
-  prompt=`
-    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
-
-    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/WFS-[id]/.chat/plan-[timestamp].md (or .scratchpad/)
-  `
-)
-```
-
-## Core Rules
-
-- **Read-only**: Creates modification plans, does NOT generate code
-- **Template**: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
-- **Output**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md` (or `.scratchpad/` if no session)

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

@@ -143,68 +143,10 @@ Perform Deep Scan analysis for feature: {FEATURE_KEYWORD}
 - 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\"
-  ]
-}
+**MANDATORY FIRST STEP**:
+Read: ~/.claude/workflows/cli-templates/schemas/codemap-json-schema.json
+
+**Output**: Return JSON following schema exactly. NO FILE WRITING - return JSON analysis only.
 
 **Critical Requirements**:
 - Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution)
@@ -728,18 +670,6 @@ User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index)
 
 ---
 
-## Benefits
-
-- **Per-Feature SKILL**: Independent packages for each analyzed feature
-- **Specialized Agent**: cli-explore-agent with Deep Scan mode (Bash + Gemini dual-source)
-- **Professional Analysis**: Pre-defined workflow for code exploration and structure analysis
-- **Clear Separation**: Agent analyzes (JSON) → Orchestrator documents (Mermaid markdown)
-- **Multi-Level Detail**: 4 levels (architecture → function → data → conditional)
-- **Visual Flow**: Embedded Mermaid diagrams for all flow types
-- **Progressive Loading**: Token-efficient context loading (2K → 30K)
-- **Auto-Continue**: Fully autonomous 3-phase execution
-- **Smart Skip**: Detects existing codemap, 10x faster index updates
-- **CLI Integration**: Gemini/Qwen for deep semantic understanding
 
 ## Architecture
 
@@ -753,12 +683,5 @@ code-map-memory (orchestrator)
   │       └─ Transform JSON → 5 Mermaid markdown files + metadata.json
   └─ Phase 3: Write SKILL.md (index generation, always runs)
 
-Benefits:
-✅ Specialized agent: cli-explore-agent with dual-source strategy (Bash + Gemini)
-✅ Professional analysis: Pre-defined Deep Scan workflow
-✅ Clear separation: Agent analyzes (JSON) → Orchestrator documents (Mermaid)
-✅ Smart skip logic: 10x faster when codemap exists
-✅ Multi-level detail: Architecture → Functions → Data → Conditionals
-
 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/docs.md

@@ -36,7 +36,6 @@ Lightweight planner that analyzes project structure, decomposes documentation wo
 | `my_app/src/modules/auth/` | `my_app` | `.workflow/docs/my_app/src/modules/auth/API.md` |
 | `another_project/lib/utils/` | `another_project` | `.workflow/docs/another_project/lib/utils/API.md` |
 
-**Benefits**: Easy to locate documentation, maintains logical organization, clear 1:1 mapping, supports any project structure.
 
 ## Parameters
 
@@ -44,7 +43,11 @@ Lightweight planner that analyzes project structure, decomposes documentation wo
 /memory:docs [path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]
 ```
 
-- **path**: Target directory (default: current directory)
+- **path**: Source directory to analyze (default: current directory)
+  - Specifies the source code directory to be documented
+  - Documentation is generated in a separate `.workflow/docs/{project_name}/` directory at the workspace root, **not** within the source `path` itself
+  - The source path's structure is mirrored within the project-specific documentation folder
+  - Example: analyzing `src/modules` produces documentation at `.workflow/docs/{project_name}/src/modules/`
 - **--mode**: Documentation generation mode (default: full)
   - `full`: Complete documentation (modules + README + ARCHITECTURE + EXAMPLES + HTTP API)
   - `partial`: Module documentation only (API.md + README.md)
@@ -63,10 +66,10 @@ Lightweight planner that analyzes project structure, decomposes documentation wo
 bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S)
 
 # Create session directories (replace timestamp)
-bash(mkdir -p .workflow/WFS-docs-{timestamp}/.{task,process,summaries} && touch .workflow/.active-WFS-docs-{timestamp})
+bash(mkdir -p .workflow/active/WFS-docs-{timestamp}/.{task,process,summaries})
 
 # Create workflow-session.json (replace values)
-bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/WFS-docs-{timestamp}/workflow-session.json)
+bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/active/WFS-docs-{timestamp}/workflow-session.json)
 ```
 
 ### Phase 2: Analyze Structure
@@ -89,7 +92,7 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj
 bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null | xargs cat 2>/dev/null; fi)
 ```
 
-**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/phase2-analysis.json` with structure:
+**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/doc-planning-data.json` with structure:
 
 ```json
 {
@@ -118,7 +121,7 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj
 
 **Then** use **Edit tool** to update `workflow-session.json` adding analysis field.
 
-**Output**: Single `phase2-analysis.json` with all analysis data (no temp files or Python scripts).
+**Output**: Single `doc-planning-data.json` with all analysis data (no temp files or Python scripts).
 
 **Auto-skipped**: Tests (`**/test/**`, `**/*.test.*`), Build (`**/node_modules/**`, `**/dist/**`), Config (root-level files), Vendor directories.
 
@@ -127,8 +130,8 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj
 **Commands**:
 
 ```bash
-# Count existing docs from phase2-analysis.json
-bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq '.existing_docs.file_list | length')
+# Count existing docs from doc-planning-data.json
+bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq '.existing_docs.file_list | length')
 ```
 
 **Data Processing**: Use count result, then use **Edit tool** to update `workflow-session.json`:
@@ -177,16 +180,15 @@ Large Projects (single dir >10 docs):
 4. If single dir exceeds 10 docs, split by subdirectories
 5. Create parallel Level 1 tasks with ≤10 docs each
 
-**Benefits**: Parallel execution, failure isolation, progress visibility, context sharing, document count control.
 
 **Commands**:
 
 ```bash
-# 1. Get top-level directories from phase2-analysis.json
-bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq -r '.top_level_dirs[]')
+# 1. Get top-level directories from doc-planning-data.json
+bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq -r '.top_level_dirs[]')
 
 # 2. Get mode from workflow-session.json
-bash(cat .workflow/WFS-docs-{timestamp}/workflow-session.json | jq -r '.mode // "full"')
+bash(cat .workflow/active/WFS-docs-{timestamp}/workflow-session.json | jq -r '.mode // "full"')
 
 # 3. Check for HTTP API
 bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo "NO_API")
@@ -201,7 +203,7 @@ bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo
    - If total ≤10 docs: create group
    - If total >10 docs: split to 1 dir/group or subdivide
    - If single dir >10 docs: split by subdirectories
-3. Use **Edit tool** to update `phase2-analysis.json` adding groups field:
+3. Use **Edit tool** to update `doc-planning-data.json` adding groups field:
    ```json
    "groups": {
      "count": 3,
@@ -215,7 +217,7 @@ bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo
 
 **Task ID Calculation**:
 ```bash
-group_count=$(jq '.groups.count' .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json)
+group_count=$(jq '.groups.count' .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json)
 readme_id=$((group_count + 1))   # Next ID after groups
 arch_id=$((group_count + 2))
 api_id=$((group_count + 3))
@@ -237,7 +239,7 @@ api_id=$((group_count + 3))
 
 **Generation Process**:
 1. Read configuration values (tool, cli_execute, mode) from workflow-session.json
-2. Read group assignments from phase2-analysis.json
+2. Read group assignments from doc-planning-data.json
 3. Generate Level 1 tasks (IMPL-001 to IMPL-N, one per group)
 4. Generate Level 2+ tasks if mode=full (README, ARCHITECTURE, HTTP API)
 
@@ -262,14 +264,14 @@ api_id=$((group_count + 3))
   },
   "context": {
     "requirements": [
-      "Process directories from group ${group_number} in phase2-analysis.json",
+      "Process directories from group ${group_number} in doc-planning-data.json",
       "Generate docs to .workflow/docs/${project_name}/ (mirrored structure)",
       "Code folders: API.md + README.md; Navigation folders: README.md only",
       "Use pre-analyzed data from Phase 2 (no redundant analysis)"
     ],
     "focus_paths": ["${group_dirs_from_json}"],
     "precomputed_data": {
-      "phase2_analysis": "${session_dir}/.process/phase2-analysis.json"
+      "phase2_analysis": "${session_dir}/.process/doc-planning-data.json"
     }
   },
   "flow_control": {
@@ -278,8 +280,8 @@ api_id=$((group_count + 3))
         "step": "load_precomputed_data",
         "action": "Load Phase 2 analysis and extract group directories",
         "commands": [
-          "bash(cat ${session_dir}/.process/phase2-analysis.json)",
-          "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/phase2-analysis.json)"
+          "bash(cat ${session_dir}/.process/doc-planning-data.json)",
+          "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/doc-planning-data.json)"
         ],
         "output_to": "phase2_context",
         "note": "Single JSON file contains all Phase 2 analysis results"
@@ -324,7 +326,7 @@ api_id=$((group_count + 3))
 {
   "step": 2,
   "title": "Batch generate documentation via CLI",
-  "command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/phase2-analysis.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
+  "command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/doc-planning-data.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
   "depends_on": [1],
   "output": "generated_docs"
 }
@@ -458,14 +460,13 @@ api_id=$((group_count + 3))
 **Unified Structure** (single JSON replaces multiple text files):
 
 ```
-.workflow/
-├── .active-WFS-docs-{timestamp}
+.workflow/active/
 └── WFS-docs-{timestamp}/
     ├── workflow-session.json            # Session metadata
     ├── IMPL_PLAN.md
     ├── TODO_LIST.md
     ├── .process/
-    │   └── phase2-analysis.json         # All Phase 2 analysis data (replaces 7+ files)
+    │   └── doc-planning-data.json       # All Phase 2 analysis data (replaces 7+ files)
     └── .task/
         ├── IMPL-001.json                # Small: all modules | Large: group 1
         ├── IMPL-00N.json                # (Large only: groups 2-N)
@@ -474,7 +475,7 @@ api_id=$((group_count + 3))
         └── IMPL-{N+3}.json              # HTTP API (optional)
 ```
 
-**phase2-analysis.json Structure**:
+**doc-planning-data.json Structure**:
 ```json
 {
   "metadata": {

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

@@ -508,16 +508,7 @@ User triggers command
 
 ---
 
-## Benefits
 
-- **Pure Orchestrator**: No task JSON generation, delegates to /memory:docs
-- **Auto-Continue**: Autonomous 4-phase execution without user interaction
-- **Intelligent Skip**: Detects existing docs and skips regeneration for fast SKILL updates
-- **Always Fresh Index**: Phase 4 always executes to ensure SKILL.md stays synchronized
-- **Simplified**: ~70% less code than previous version
-- **Maintainable**: Changes to /memory:docs automatically apply
-- **Direct Generation**: Phase 4 directly writes SKILL.md
-- **Flexible**: Supports all /memory:docs options (tool, mode, cli-execute)
 
 ## Architecture
 

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

@@ -128,8 +128,8 @@ Generate a complete tech stack SKILL package with Exa research.
 1. **Extract Tech Stack Information**:
 
    IF MODE == 'session':
-     - Read `.workflow/{SESSION_ID}/workflow-session.json`
-     - Read `.workflow/{SESSION_ID}/.process/context-package.json`
+     - 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\"

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

@@ -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

@@ -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/task/execute.md

@@ -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": {

.claude/commands/task/replan.md

@@ -7,6 +7,14 @@ 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
@@ -274,7 +279,7 @@ 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:

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

@@ -32,26 +32,32 @@ Identify inconsistencies, duplications, ambiguities, and underspecified items be
 IF --session parameter provided:
     session_id = provided session
 ELSE:
-    CHECK: .workflow/.active-* marker files
-    IF active_session EXISTS:
-        session_id = get_active_session()
-    ELSE:
+    # Auto-detect active session
+    active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
+    IF active_sessions is empty:
         ERROR: "No active workflow session found. Use --session <session-id>"
         EXIT
+    ELSE IF active_sessions has multiple entries:
+        # Use most recently modified session
+        session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
+    ELSE:
+        session_id = basename(active_sessions[0])
 
 # Derive absolute paths
-session_dir = .workflow/WFS-{session}
+session_dir = .workflow/active/WFS-{session}
 brainstorm_dir = session_dir/.brainstorming
 task_dir = session_dir/.task
 
 # Validate required artifacts
-SYNTHESIS = brainstorm_dir/role analysis documents
+# Note: "role analysis documents" refers to [role]/analysis.md files (e.g., product-manager/analysis.md)
+SYNTHESIS_DIR = brainstorm_dir  # Contains role analysis files: */analysis.md
 IMPL_PLAN = session_dir/IMPL_PLAN.md
 TASK_FILES = Glob(task_dir/*.json)
 
 # Abort if missing
-IF NOT EXISTS(SYNTHESIS):
-    ERROR: "role analysis documents not found. Run /workflow:brainstorm:synthesis first"
+SYNTHESIS_FILES = Glob(brainstorm_dir/*/analysis.md)
+IF SYNTHESIS_FILES.count == 0:
+    ERROR: "No role analysis documents found in .brainstorming/*/analysis.md. Run /workflow:brainstorm:synthesis first"
     EXIT
 
 IF NOT EXISTS(IMPL_PLAN):
@@ -135,27 +141,27 @@ Focus on high-signal findings. Limit to 50 findings total; aggregate remainder i
 - **Unmapped Tasks**: Tasks with no clear requirement linkage
 - **NFR Coverage Gaps**: Non-functional requirements (performance, security, scalability) not reflected in tasks
 
-#### B. Consistency Validation
+#### C. Consistency Validation
 
 - **Requirement Conflicts**: Tasks contradicting synthesis requirements
 - **Architecture Drift**: IMPL_PLAN architecture not matching synthesis ADRs
 - **Terminology Drift**: Same concept named differently across IMPL_PLAN and tasks
 - **Data Model Inconsistency**: Tasks referencing entities/fields not in synthesis data model
 
-#### C. Dependency Integrity
+#### D. Dependency Integrity
 
 - **Circular Dependencies**: Task A depends on B, B depends on C, C depends on A
 - **Missing Dependencies**: Task requires outputs from another task but no explicit dependency
 - **Broken Dependencies**: Task depends on non-existent task ID
 - **Logical Ordering Issues**: Implementation tasks before foundational setup without dependency note
 
-#### D. Synthesis Alignment
+#### E. Synthesis Alignment
 
 - **Priority Conflicts**: High-priority synthesis requirements mapped to low-priority tasks
 - **Success Criteria Mismatch**: IMPL_PLAN success criteria not covering synthesis acceptance criteria
 - **Risk Mitigation Gaps**: Critical risks in synthesis without corresponding mitigation tasks
 
-#### E. Task Specification Quality
+#### F. Task Specification Quality
 
 - **Ambiguous Focus Paths**: Tasks with vague or missing focus_paths
 - **Underspecified Acceptance**: Tasks without clear acceptance criteria
@@ -163,12 +169,12 @@ Focus on high-signal findings. Limit to 50 findings total; aggregate remainder i
 - **Weak Flow Control**: Tasks without clear implementation_approach or pre_analysis steps
 - **Missing Target Files**: Tasks without flow_control.target_files specification
 
-#### F. Duplication Detection
+#### G. Duplication Detection
 
 - **Overlapping Task Scope**: Multiple tasks with nearly identical descriptions
 - **Redundant Requirements Coverage**: Same requirement covered by multiple tasks without clear partitioning
 
-#### G. Feasibility Assessment
+#### H. Feasibility Assessment
 
 - **Complexity Misalignment**: Task marked "simple" but requires multiple file modifications
 - **Resource Conflicts**: Parallel tasks requiring same resources/files
@@ -203,7 +209,9 @@ Use this heuristic to prioritize findings:
 
 ### 6. Produce Compact Analysis Report
 
-Output a Markdown report (no file writes) with the following structure:
+**Report Generation**: Generate report content and save to file.
+
+Output a Markdown report with the following structure:
 
 ```markdown
 ## Action Plan Verification Report
@@ -217,7 +225,11 @@ Output a Markdown report (no file writes) with the following structure:
 ### Executive Summary
 
 - **Overall Risk Level**: CRITICAL | HIGH | MEDIUM | LOW
-- **Recommendation**: BLOCK_EXECUTION | PROCEED_WITH_FIXES | PROCEED_WITH_CAUTION | PROCEED
+- **Recommendation**: (See decision matrix below)
+  - BLOCK_EXECUTION: Critical issues exist (must fix before proceeding)
+  - PROCEED_WITH_FIXES: High issues exist, no critical (fix recommended before execution)
+  - PROCEED_WITH_CAUTION: Medium issues only (proceed with awareness)
+  - PROCEED: Low issues only or no issues (safe to execute)
 - **Critical Issues**: {count}
 - **High Issues**: {count}
 - **Medium Issues**: {count}
@@ -322,18 +334,31 @@ Output a Markdown report (no file writes) with the following structure:
 
 #### Action Recommendations
 
-**If CRITICAL Issues Exist**:
-- **BLOCK EXECUTION** - Resolve critical issues before proceeding
-- Use TodoWrite to track all required fixes
-- Fix broken dependencies and circular references
+**Recommendation Decision Matrix**:
 
-**If Only HIGH/MEDIUM/LOW Issues**:
-- **PROCEED WITH CAUTION** - Fix high-priority issues first
-- Use TodoWrite to systematically track and complete all improvements
+| Condition | Recommendation | Action |
+|-----------|----------------|--------|
+| Critical > 0 | BLOCK_EXECUTION | Must resolve all critical issues before proceeding |
+| Critical = 0, High > 0 | PROCEED_WITH_FIXES | Fix high-priority issues before execution |
+| Critical = 0, High = 0, Medium > 0 | PROCEED_WITH_CAUTION | Proceed with awareness of medium issues |
+| Only Low or None | PROCEED | Safe to execute workflow |
+
+**If CRITICAL Issues Exist** (BLOCK_EXECUTION):
+- Resolve all critical issues before proceeding
+- Use TodoWrite to track required fixes
+- Fix broken dependencies and circular references first
+
+**If HIGH Issues Exist** (PROCEED_WITH_FIXES):
+- Fix high-priority issues before execution
+- Use TodoWrite to systematically track and complete improvements
+
+**If Only MEDIUM/LOW Issues** (PROCEED_WITH_CAUTION / PROCEED):
+- Can proceed with execution
+- Address issues during or after implementation
 
 #### 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
@@ -359,13 +384,18 @@ Priority Order:
 
 ### 7. Save Report and Execute TodoWrite-Based Remediation
 
-**Save Analysis Report**:
+**Step 7.1: 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)
 ```
 
-**After Report Generation**:
+**Step 7.2: Display Report Summary to User**:
+- Show executive summary with counts
+- Display recommendation (BLOCK/PROCEED_WITH_FIXES/PROCEED_WITH_CAUTION/PROCEED)
+- List critical and high issues if any
+
+**Step 7.3: After Report Generation**:
 
 1. **Extract Findings**: Parse all issues by severity
 2. **Create TodoWrite Task List**: Convert findings to actionable todos
@@ -404,12 +434,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

@@ -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

@@ -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

@@ -85,19 +85,20 @@ 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 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"}
+  {"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1: Interactive Framework Generation", "status": "in_progress", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "  → Topic analysis and question generation", "status": "in_progress", "activeForm": "Analyzing topic"},
+  {"content": "  → Role selection and user confirmation", "status": "pending", "activeForm": "Selecting roles"},
+  {"content": "  → Role questions and user decisions", "status": "pending", "activeForm": "Collecting role questions"},
+  {"content": "  → Conflict detection and resolution", "status": "pending", "activeForm": "Resolving conflicts"},
+  {"content": "  → Guidance specification generation", "status": "pending", "activeForm": "Generating guidance"},
+  {"content": "Phase 2: Parallel Role Analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis integration"}
 ]
 ```
 
@@ -108,10 +109,10 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
 **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"}
+  {"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1: Interactive Framework Generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2: Parallel Role Analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis integration"}
 ]
 ```
 
@@ -132,13 +133,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**
@@ -148,7 +149,7 @@ 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)
@@ -194,7 +195,7 @@ 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
@@ -203,12 +204,13 @@ TOPIC: {user-provided-topic}
 **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"}
+  {"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1: Interactive Framework Generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2: Parallel Role Analysis", "status": "in_progress", "activeForm": "Executing parallel role analysis"},
+  {"content": "  → Execute system-architect analysis", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
+  {"content": "  → Execute ui-designer analysis", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "  → Execute product-manager analysis", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
+  {"content": "Phase 3: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis integration"}
 ]
 ```
 
@@ -219,10 +221,10 @@ TOPIC: {user-provided-topic}
 **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"}
+  {"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1: Interactive Framework Generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2: Parallel Role Analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis integration"}
 ]
 ```
 
@@ -245,18 +247,19 @@ 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 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"}
+  {"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1: Interactive Framework Generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2: Parallel Role Analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3: Synthesis Integration", "status": "in_progress", "activeForm": "Executing synthesis integration"},
+  {"content": "  → Load role analysis files", "status": "in_progress", "activeForm": "Loading role analyses"},
+  {"content": "  → Integrate insights across roles", "status": "pending", "activeForm": "Integrating insights"},
+  {"content": "  → Generate synthesis specification", "status": "pending", "activeForm": "Generating synthesis"}
 ]
 ```
 
@@ -267,10 +270,10 @@ TOPIC: {user-provided-topic}
 **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"}
+  {"content": "Phase 0: Parameter Parsing", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1: Interactive Framework Generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2: Parallel Role Analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3: Synthesis Integration", "status": "completed", "activeForm": "Executing synthesis integration"}
 ]
 ```
 
@@ -280,7 +283,7 @@ TOPIC: {user-provided-topic}
 ```
 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
@@ -324,14 +327,6 @@ Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
 - **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
 
-**Benefits**:
-- Real-time visibility into attached tasks during execution
-- Clean orchestrator-level summary after tasks complete
-- Clear mental model: SlashCommand/Task = attach tasks, not delegate work
-- Parallel execution support for concurrent role analysis
-- Dynamic attachment/collapse maintains clarity
-
-**Note**: See individual Phase descriptions (Phase 1, 2, 3) for detailed TodoWrite Update examples with full JSON structures.
 
 ## Input Processing
 
@@ -392,31 +387,31 @@ CONTEXT_VARS:
 
 ## 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, style_skill_package)
+- `.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}/`
@@ -446,8 +441,7 @@ CONTEXT_VARS:
 
 **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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -15,22 +15,16 @@ 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)
+- **TODO_LIST.md**: Read in Phase 3 (task metadata, status, dependencies for TodoWrite generation)
+- **IMPL_PLAN.md**: Check existence in Phase 2 (normal mode), parse execution strategy in Phase 4A
+- **Task JSONs**: Lazy loading - read only when task is about to execute (Phase 4B)
 
 ## Core Rules
 **Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
 **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
@@ -42,40 +36,143 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 - **Session Auto-Complete**: Call `/workflow:session:complete` when all workflow tasks finished
 
 ## Execution Philosophy
-- **IMPL_PLAN-driven**: Follow execution strategy from IMPL_PLAN.md Section 4
-- **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
 - **Autonomous completion**: Execute all tasks without user interruption until workflow complete
 
+## Execution Process
+
+```
+Normal Mode:
+Phase 1: Discovery
+   ├─ Count active sessions
+   └─ Decision:
+      ├─ count=0 → ERROR: No active sessions
+      ├─ count=1 → Auto-select session → Phase 2
+      └─ count>1 → AskUserQuestion (max 4 options) → Phase 2
+
+Phase 2: Planning Document Validation
+   ├─ Check IMPL_PLAN.md exists
+   ├─ Check TODO_LIST.md exists
+   └─ Validate .task/ contains IMPL-*.json files
+
+Phase 3: TodoWrite Generation
+   ├─ Parse TODO_LIST.md for task statuses
+   ├─ Generate TodoWrite for entire workflow
+   └─ Prepare session context paths
+
+Phase 4: Execution Strategy & Task Execution
+   ├─ Step 4A: Parse execution strategy from IMPL_PLAN.md
+   └─ Step 4B: Execute tasks with lazy loading
+      └─ Loop:
+         ├─ Get next in_progress task from TodoWrite
+         ├─ Lazy load task JSON
+         ├─ Launch agent with task context
+         ├─ Mark task completed
+         └─ Advance to next task
+
+Phase 5: Completion
+   ├─ Update task statuses in JSON files
+   ├─ Generate summaries
+   └─ Auto-call /workflow:session:complete
+
+Resume Mode (--resume-session):
+   ├─ Skip Phase 1 & Phase 2
+   └─ Entry Point: Phase 3 (TodoWrite Generation)
+      └─ Continue: Phase 4 → Phase 5
+```
+
 ## Execution Lifecycle
 
 ### Phase 1: Discovery
 **Applies to**: Normal mode only (skipped in resume mode)
 
+**Purpose**: Find and select active workflow session with user confirmation when multiple sessions exist
+
 **Process**:
-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
 
-**Resume Mode**: This phase is completely skipped when `--resume-session="session-id"` flag is provided.
+#### Step 1.1: Count Active Sessions
+```bash
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
+```
 
-### Phase 2: Planning Document Analysis
+#### 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 (max 4 options shown):
+```javascript
+// If more than 4 sessions, show most recent 4 with "Other" option for manual input
+const sessions = getActiveSessions()  // sorted by last modified
+const displaySessions = sessions.slice(0, 4)
+
+AskUserQuestion({
+  questions: [{
+    question: "Multiple active sessions detected. Select one:",
+    header: "Session",
+    multiSelect: false,
+    options: displaySessions.map(s => ({
+      label: s.id,
+      description: `${s.project} | ${s.progress}`
+    }))
+    // Note: User can select "Other" to manually enter session ID
+  }]
+})
+```
+
+**Input Validation**:
+- If user selects from options: Use selected session ID
+- If user selects "Other" and provides input: Validate session exists
+- If validation fails: Show error and re-prompt or suggest available sessions
+
+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 Validation
 **Applies to**: Normal mode only (skipped in resume mode)
 
-**Optimized to avoid reading all task JSONs upfront**
+**Purpose**: Validate planning artifacts exist before execution
 
 **Process**:
-1. **Read IMPL_PLAN.md**: Check existence, understand overall strategy
-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
+1. **Check IMPL_PLAN.md**: Verify file exists (defer detailed parsing to Phase 4A)
+2. **Check TODO_LIST.md**: Verify file exists (defer reading to Phase 3)
+3. **Validate Task Directory**: Ensure `.task/` contains at least one IMPL-*.json file
 
-**Key Optimization**: Use IMPL_PLAN.md (existence check only) and TODO_LIST.md as primary sources instead of reading all task JSONs
+**Key Optimization**: Only existence checks here. Actual file reading happens in later phases.
 
-**Resume Mode**: This phase is skipped when `--resume-session` flag is provided (session already known).
+**Resume Mode**: This phase is skipped when `--resume-session` flag is provided. Resume mode entry point is Phase 3.
 
 ### Phase 3: TodoWrite Generation
 **Applies to**: Both normal and resume modes (resume mode entry point)
@@ -85,14 +182,11 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
    - 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(s) as `in_progress` in TodoWrite
-   - **Sequential execution**: Mark ONE task as `in_progress`
-   - **Parallel batch**: Mark ALL tasks in current batch as `in_progress`
-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)
@@ -118,7 +212,7 @@ If IMPL_PLAN.md lacks execution strategy, use intelligent fallback (analyze task
 ```
 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/active/{session}/.task/{next_task_id}.json)  // Lazy load
   executeTaskWithAgent(task_json)
   updateTodoListMarkCompleted(next_task_id)
   advanceTodoWriteToNextTask()
@@ -132,14 +226,10 @@ while (TODO_LIST.md has pending tasks) {
 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. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
-8. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat
+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.
 
-**Benefits**:
-- Reduces initial context loading by ~90%
-- Only reads task JSON when actually executing
-- Scales better for workflows with many tasks
-- Faster startup time for workflow execution
 
 ### Phase 5: Completion
 **Applies to**: Both normal and resume modes
@@ -186,8 +276,9 @@ while (TODO_LIST.md has pending tasks) {
 
 #### 2. Parallel Execution
 **When**: IMPL_PLAN specifies "Parallel" with clear parallelization opportunities
-**Pattern**: Execute independent task groups concurrently
+**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
@@ -275,232 +366,47 @@ TodoWrite({
 });
 ```
 
-### TODO_LIST.md Update Timing
-**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
-
-- **Before Agent Launch**: Mark task as `in_progress`
-- **After Task Complete**: Mark as `completed`, advance to next
-- **On Error**: Keep as `in_progress`, add error note
-- **Workflow Complete**: Call `/workflow:session:complete`
-
-## Agent Context Management
-
-### Context Sources (Priority Order)
-1. **Complete Task JSON**: Full task definition including all fields and artifacts
-2. **Artifacts Context**: Brainstorming outputs and role analyses 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
-
 ## Agent Execution Pattern
 
 ### 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.**
+**Note**: Orchestrator does NOT execute flow control steps - Agent interprets and executes them autonomously.
 
 ### Agent Prompt Template
+**Dynamic Generation**: Before agent invocation, read task JSON and extract key requirements.
+
 ```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
 ```
 meta.agent specified → Use specified agent
@@ -514,10 +420,10 @@ meta.agent missing → Infer from meta.type:
 
 ## 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
@@ -536,8 +442,8 @@ meta.agent missing → Infer from meta.type:
 | Error Type | Cause | Recovery Strategy | Max Attempts |
 |-----------|-------|------------------|--------------|
 | **Discovery Errors** |
-| No active session | No `.active-*` markers found | Create or resume session: `/workflow:plan "project"` | N/A |
-| Multiple sessions | Multiple `.active-*` markers | Prompt user selection | N/A |
+| 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 |
@@ -552,31 +458,3 @@ meta.agent missing → Infer from meta.type:
 - **Dependency Validation**: Check all depends_on references exist
 - **Context Verification**: Ensure all required context is available
 
-### Recovery Procedures
-
-**Session Recovery**:
-```bash
-# Check session integrity
-find .workflow -name ".active-*" | while read marker; do
-  session=$(basename "$marker" | sed 's/^\.active-//')
-  [ ! -d ".workflow/$session" ] && rm "$marker"
-done
-
-# Recreate corrupted session files
-[ ! -f ".workflow/$session/workflow-session.json" ] && \
-  echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
-```
-
-**Task Recovery**:
-```bash
-# Validate task JSON integrity
-for task_file in .workflow/$session/.task/*.json; do
-  jq empty "$task_file" 2>/dev/null || echo "Corrupted: $task_file"
-done
-
-# Fix missing dependencies
-missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
-for dep in $missing_deps; do
-  [ ! -f ".workflow/$session/.task/$dep.json" ] && echo "Missing dependency: $dep"
-done
-```

.claude/commands/workflow/init.md

@@ -0,0 +1,192 @@
+---
+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
+```
+
+## Execution Process
+
+```
+Input Parsing:
+   └─ Parse --regenerate flag → regenerate = true | false
+
+Decision:
+   ├─ EXISTS + no --regenerate → Exit: "Already initialized"
+   ├─ EXISTS + --regenerate → Backup existing → Continue analysis
+   └─ NOT_FOUND → Continue analysis
+
+Analysis Flow:
+   ├─ Get project metadata (name, root)
+   ├─ Invoke cli-explore-agent
+   │   ├─ Structural scan (get_modules_by_depth.sh, find, wc)
+   │   ├─ Semantic analysis (Gemini CLI)
+   │   ├─ Synthesis and merge
+   │   └─ Write .workflow/project.json
+   └─ Display summary
+
+Output:
+   └─ .workflow/project.json (+ .backup if regenerate)
+```
+
+## Implementation
+
+### Step 1: Parse Input and Check Existing State
+
+**Parse --regenerate flag**:
+```javascript
+const regenerate = $ARGUMENTS.includes('--regenerate')
+```
+
+**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.
+
+## MANDATORY FIRST STEPS
+1. Execute: cat ~/.claude/workflows/cli-templates/schemas/project-json-schema.json (get schema reference)
+2. Execute: ~/.claude/scripts/get_modules_by_depth.sh (get project structure)
+
+## 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,611 @@
+---
+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 plan.json
+
+**Step 1: Read and Detect Format**
+
+```javascript
+fileContent = Read(filePath)
+
+// Attempt JSON parsing
+try {
+  jsonData = JSON.parse(fileContent)
+
+  // Check if plan.json from lite-plan session
+  if (jsonData.summary && jsonData.approach && jsonData.tasks) {
+    planObject = jsonData
+    originalUserInput = jsonData.summary
+    isPlanJson = true
+  } else {
+    // Valid JSON but not plan.json - treat as plain text
+    originalUserInput = fileContent
+    isPlanJson = false
+  }
+} catch {
+  // Not valid JSON - treat as plain text prompt
+  originalUserInput = fileContent
+  isPlanJson = false
+}
+```
+
+**Step 2: Create Execution Plan**
+
+If `isPlanJson === true`:
+- Use `planObject` directly
+- User selects execution method and code review
+
+If `isPlanJson === 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
+
+```
+Input Parsing:
+   └─ Decision (mode detection):
+      ├─ --in-memory flag → Mode 1: Load executionContext → Skip user selection
+      ├─ Ends with .md/.json/.txt → Mode 3: Read file → Detect format
+      │   ├─ Valid plan.json → Use planObject → User selects method + review
+      │   └─ Not plan.json → Treat as prompt → User selects method + review
+      └─ Other → Mode 2: Prompt description → User selects method + review
+
+Execution:
+   ├─ Step 1: Initialize result tracking (previousExecutionResults = [])
+   ├─ Step 2: Task grouping & batch creation
+   │   ├─ Infer dependencies (same file → sequential, keywords → sequential)
+   │   ├─ Group into batches (parallel: independent, sequential: dependent)
+   │   └─ Create TodoWrite list for batches
+   ├─ Step 3: Launch execution
+   │   ├─ Phase 1: All parallel batches (⚡ concurrent via multiple tool calls)
+   │   └─ Phase 2: Sequential batches (→ one by one)
+   ├─ Step 4: Track progress (TodoWrite updates per batch)
+   └─ Step 5: Code review (if codeReviewTool ≠ "Skip")
+
+Output:
+   └─ Execution complete with results in previousExecutionResults[]
+```
+
+## 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')}` : ''}
+
+  ## Multi-Angle Code Context
+
+  ${explorationsContext && Object.keys(explorationsContext).length > 0 ?
+    explorationAngles.map(angle => {
+      const exp = explorationsContext[angle]
+      return `### Exploration Angle: ${angle}
+
+**Project Structure**: ${exp.project_structure || 'N/A'}
+**Relevant Files**: ${exp.relevant_files?.join(', ') || 'None'}
+**Patterns**: ${exp.patterns || 'N/A'}
+**Dependencies**: ${exp.dependencies || 'N/A'}
+**Integration Points**: ${exp.integration_points || 'N/A'}
+**Constraints**: ${exp.constraints || 'N/A'}`
+    }).join('\n\n---\n\n')
+    : "No exploration performed"
+  }
+
+  ${clarificationContext ? `\n## Clarifications\n${JSON.stringify(clarificationContext, null, 2)}` : ''}
+
+  ${executionContext?.session?.artifacts ? `\n## Exploration Artifact Files
+
+  Detailed exploration context available in:
+  ${executionContext.session.artifacts.explorations?.map(exp =>
+    `- Angle: ${exp.angle} → ${exp.path}`
+  ).join('\n') || ''}
+  ${executionContext.session.artifacts.explorations_manifest ? `- Manifest: ${executionContext.session.artifacts.explorations_manifest}` : ''}
+  - Plan: ${executionContext.session.artifacts.plan}
+
+  Read exploration files for comprehensive context from multiple angles.` : ''}
+
+  ## 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.
+` : ''}
+
+### Multi-Angle Code Context
+
+${explorationsContext && Object.keys(explorationsContext).length > 0 ?
+  `Exploration conducted from ${explorationAngles.length} angles:
+
+${explorationAngles.map(angle => {
+  const exp = explorationsContext[angle]
+  return `Angle: ${angle}
+- Structure: ${exp.project_structure || 'Standard structure'}
+- Files: ${exp.relevant_files?.slice(0, 5).join(', ') || 'TBD'}${exp.relevant_files?.length > 5 ? ` (+${exp.relevant_files.length - 5} more)` : ''}
+- Patterns: ${exp.patterns?.substring(0, 100) || 'Follow existing'}${exp.patterns?.length > 100 ? '...' : ''}
+- Constraints: ${exp.constraints || 'None'}`
+}).join('\n\n')}
+`
+  : '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### Exploration Artifact Files
+Detailed context from multiple exploration angles available in:
+${executionContext.session.artifacts.explorations?.map(exp =>
+  `- Angle: ${exp.angle} → ${exp.path}`
+).join('\n') || ''}
+${executionContext.session.artifacts.explorations_manifest ? `- Manifest: ${executionContext.session.artifacts.explorations_manifest}` : ''}
+- Plan: ${executionContext.session.artifacts.plan}
+
+Read exploration files for comprehensive architectural, pattern, and constraint details from multiple angles.
+` : ''}
+
+## 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)
+// Timeout based on complexity: Low=40min, Medium=60min, High=100min
+const timeoutByComplexity = {
+  "Low": 2400000,    // 40 minutes
+  "Medium": 3600000, // 60 minutes
+  "High": 6000000    // 100 minutes
+}
+
+bash_result = Bash(
+  command=cli_command,
+  timeout=timeoutByComplexity[planObject.complexity] || 3600000
+)
+
+// 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 plan acceptance criteria
+- Read plan.json for task 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
+- Gemini Review: Execute gemini CLI with review prompt
+- Custom tool: Execute specified CLI tool (qwen, codex, etc.)
+
+**Unified Review Template** (All tools use same standard):
+
+**Review Criteria**:
+- **Acceptance Criteria**: Verify each criterion from plan.tasks[].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 plan acceptance criteria
+TASK: • Verify plan acceptance criteria fulfillment • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence
+MODE: analysis
+CONTEXT: @**/* @{plan.json} [@{exploration.json}] | Memory: Review lite-execute changes against plan requirements
+EXPECTED: Quality assessment with acceptance criteria verification, issue identification, and recommendations. Explicitly check each acceptance criterion from plan.json tasks.
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on plan acceptance criteria and plan adherence | analysis=READ-ONLY
+```
+
+**Tool-Specific Execution** (Apply shared prompt template above):
+
+```bash
+# Method 1: Agent Review (current agent)
+# - Read plan.json: ${executionContext.session.artifacts.plan}
+# - 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: @**/* @${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 plan acceptance criteria at ${plan.json}]" --skip-git-repo-check -s danger-full-access
+```
+
+**Implementation Note**: Replace `[Shared Prompt Template with artifacts]` placeholder with actual template content, substituting:
+- `@{plan.json}` → `@${executionContext.session.artifacts.plan}`
+- `[@{exploration.json}]` → exploration files from artifacts (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
+  },
+  explorationsContext: {...} | null,       // Multi-angle explorations
+  explorationAngles: string[],             // List of exploration angles
+  explorationManifest: {...} | null,       // Exploration manifest
+  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: {
+      explorations: [{angle, path}],   // exploration-{angle}.json paths
+      explorations_manifest: string,   // explorations-manifest.json path
+      plan: string                     // plan.json path (always present)
+    }
+  }
+}
+```
+
+**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,795 @@
+---
+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
+
+```
+Input Parsing:
+   └─ Parse flags: --hotfix → hotfixMode = true | false
+
+Phase 1: Diagnosis & Root Cause Analysis
+   └─ Decision (confidence-based):
+      ├─ High confidence (specific error) → Direct grep search (5min)
+      ├─ Medium confidence → cli-explore-agent focused search (10-15min)
+      └─ Low confidence (vague) → cli-explore-agent broad search (20min)
+   └─ Hotfix mode: Minimal search (Read suspected file + git blame)
+
+Phase 2: Impact Assessment & Severity Auto-Detection
+   └─ Calculate risk_score → Auto-determine severity
+      ├─ ≥8.0 → critical
+      ├─ ≥5.0 → high
+      ├─ ≥3.0 → medium
+      └─ <3.0 → low
+   └─ Hotfix mode: Skip, assume critical
+
+Phase 3: Fix Planning & Strategy Selection
+   └─ Decision (by risk score):
+      ├─ risk_score ≥5.0 or hotfix → Single best strategy (fastest)
+      └─ risk_score <5.0 → Multiple strategy options for user selection
+
+Phase 4: Verification Strategy
+   └─ Select test scope by risk score
+   └─ Define branch strategy (feature vs hotfix)
+
+Phase 5: User Confirmation
+   └─ Default mode: 3 dimensions (approach, execution, verification)
+   └─ Hotfix mode: 2 dimensions (deploy confirmation, monitoring)
+
+Phase 6: Execution Dispatch
+   ├─ Export Enhanced Task JSON
+   ├─ Dispatch to lite-execute --in-memory
+   └─ Hotfix mode: Generate follow-up tasks
+```
+
+### 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
+
+### Input Parsing
+
+**Parse --hotfix flag**:
+```javascript
+const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h')
+const bugDescription = $ARGUMENTS.replace(/--hotfix|-h/g, '').trim()
+```
+
+### 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/plan.md

@@ -46,6 +46,36 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
 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
 
+## Execution Process
+
+```
+Input Parsing:
+   └─ Convert user input to structured format (GOAL/SCOPE/CONTEXT)
+
+Phase 1: Session Discovery
+   └─ /workflow:session:start --auto "structured-description"
+      └─ Output: sessionId (WFS-xxx)
+
+Phase 2: Context Gathering
+   └─ /workflow:tools:context-gather --session sessionId "structured-description"
+      ├─ Tasks attached: Analyze structure → Identify integration → Generate package
+      └─ Output: contextPath + conflict_risk
+
+Phase 3: Conflict Resolution (conditional)
+   └─ Decision (conflict_risk check):
+      ├─ conflict_risk ≥ medium → Execute /workflow:tools:conflict-resolution
+      │   ├─ Tasks attached: Detect conflicts → Present to user → Apply strategies
+      │   └─ Output: Modified brainstorm artifacts
+      └─ conflict_risk < medium → Skip to Phase 4
+
+Phase 4: Task Generation
+   └─ /workflow:tools:task-generate-agent --session sessionId [--cli-execute]
+      └─ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
+
+Return:
+   └─ Summary with recommended next steps
+```
+
 ## 5-Phase Execution
 
 ### Phase 1: Session Discovery
@@ -70,7 +100,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
 
@@ -87,7 +119,7 @@ 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
@@ -98,11 +130,12 @@ CONTEXT: Existing user database schema, REST API endpoints
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
+  {"content": "  → Analyze codebase structure", "status": "in_progress", "activeForm": "Analyzing codebase structure"},
+  {"content": "  → Identify integration points", "status": "pending", "activeForm": "Identifying integration points"},
+  {"content": "  → Generate context package", "status": "pending", "activeForm": "Generating context package"},
+  {"content": "Phase 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"}
 ]
 ```
 
@@ -113,9 +146,9 @@ CONTEXT: Existing user database schema, REST API endpoints
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"}
 ]
 ```
 
@@ -141,7 +174,7 @@ 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
@@ -152,12 +185,13 @@ CONTEXT: Existing user database schema, REST API endpoints
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Conflict Resolution", "status": "in_progress", "activeForm": "Resolving conflicts"},
+  {"content": "  → Detect conflicts with CLI analysis", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "  → Present conflicts to user", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "  → Apply resolution strategies", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Phase 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"}
 ]
 ```
 
@@ -168,10 +202,10 @@ CONTEXT: Existing user database schema, REST API endpoints
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Conflict Resolution", "status": "completed", "activeForm": "Resolving conflicts"},
+  {"content": "Phase 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"}
 ]
 ```
 
@@ -232,18 +266,18 @@ SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]
 **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: 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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 4: Task Generation", "status": "in_progress", "activeForm": "Executing task generation"}
 ]
 ```
 
@@ -254,9 +288,9 @@ SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 4: Task Generation", "status": "completed", "activeForm": "Executing task generation"}
 ]
 ```
 
@@ -266,7 +300,7 @@ SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]
 ```
 Planning complete for session: [sessionId]
 Tasks generated: [count]
-Plan: .workflow/[sessionId]/IMPL_PLAN.md
+Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
 
 Recommended Next Steps:
 1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
@@ -303,12 +337,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
 
 **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.
 
-### Benefits
 
-- ✓ Real-time visibility into sub-task execution
-- ✓ Clear mental model: SlashCommand = attach → execute → collapse (Phase 2/3) or complete (Phase 4)
-- ✓ Clean summary after completion
-- ✓ Easy to track workflow progress
 
 **Note**: See individual Phase descriptions for detailed TodoWrite Update examples:
 - **Phase 2, 3**: Multiple sub-tasks with attach/collapse pattern
@@ -387,11 +416,6 @@ 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
 
@@ -404,29 +428,28 @@ 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
+  → ATTACH 3 sub-tasks: ← ATTACHED
+    - → Analyze codebase structure
+    - → Identify integration points
+    - → Generate context package
+  → Execute sub-tasks sequentially
   → 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
+  │     → ATTACH 3 sub-tasks: ← ATTACHED
+  │       - → Detect conflicts with CLI analysis
+  │       - → Present conflicts to user
+  │       - → Apply resolution strategies
+  │     → Execute sub-tasks sequentially
   │     → 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
+  → Single agent task (no sub-tasks)
   → Agent autonomously completes internally:
     (discovery → planning → output)
   → Outputs: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md

.claude/commands/workflow/replan.md

@@ -0,0 +1,515 @@
+---
+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 Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session, --interactive
+   └─ Detect mode: task-id present → Task mode | Otherwise → Session mode
+
+Phase 1: Mode Detection & Session Discovery
+   ├─ Detect operation mode (Task vs Session)
+   ├─ Discover/validate session (--session flag or auto-detect)
+   └─ Load session context (workflow-session.json, IMPL_PLAN.md, TODO_LIST.md)
+
+Phase 2: Interactive Requirement Clarification
+   └─ Decision (by mode):
+      ├─ Session mode → 3-4 questions (scope, modules, changes, dependencies)
+      └─ Task mode → 2 questions (update type, ripple effect)
+
+Phase 3: Impact Analysis & Planning
+   ├─ Analyze required changes
+   ├─ Generate modification plan
+   └─ User confirmation (Execute / Adjust / Cancel)
+
+Phase 4: Backup Creation
+   └─ Backup all affected files with manifest
+
+Phase 5: Apply Modifications
+   ├─ Update IMPL_PLAN.md (if needed)
+   ├─ Update TODO_LIST.md (if needed)
+   ├─ Update/Create/Delete task JSONs
+   └─ Update session metadata
+
+Phase 6: Verification & Summary
+   ├─ Validate consistency (JSON validity, task limits, acyclic dependencies)
+   └─ Generate change summary
+```
+
+## Execution Lifecycle
+
+### Input Parsing
+
+**Parse flags**:
+```javascript
+const sessionFlag = $ARGUMENTS.match(/--session\s+(\S+)/)?.[1]
+const interactive = $ARGUMENTS.includes('--interactive')
+const taskIdMatch = $ARGUMENTS.match(/\b(IMPL-\d+(?:\.\d+)?)\b/)
+const taskId = taskIdMatch?.[1]
+```
+
+### 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:
+- 添加/删除任务 (add_remove)
+- 合并/拆分任务 (merge_split)
+- 仅更新内容 (update_only)
+// Note: Max 4 options for AskUserQuestion
+```
+
+**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/review-fix.md

@@ -0,0 +1,646 @@
+---
+name: review-fix
+description: Automated fixing of code review findings with AI-powered planning and coordinated execution. Uses intelligent grouping, multi-stage timeline coordination, and test-driven verification.
+argument-hint: "<export-file|review-dir> [--resume] [--max-iterations=N]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*), Edit(*), Write(*)
+---
+
+# Workflow Review-Fix Command
+
+## Quick Start
+
+```bash
+# Fix from exported findings file (session-based path)
+/workflow:review-fix .workflow/active/WFS-123/.review/fix-export-1706184622000.json
+
+# Fix from review directory (auto-discovers latest export)
+/workflow:review-fix .workflow/active/WFS-123/.review/
+
+# Resume interrupted fix session
+/workflow:review-fix --resume
+
+# Custom max retry attempts per finding
+/workflow:review-fix .workflow/active/WFS-123/.review/ --max-iterations=5
+```
+
+**Fix Source**: Exported findings from review cycle dashboard
+**Output Directory**: `{review-dir}/fixes/{fix-session-id}/` (within session .review/)
+**Default Max Iterations**: 3 (per finding, adjustable)
+**CLI Tools**: @cli-planning-agent (planning), @cli-execute-agent (fixing)
+
+## What & Why
+
+### Core Concept
+Automated fix orchestrator with **two-phase architecture**: AI-powered planning followed by coordinated parallel/serial execution. Generates fix timeline with intelligent grouping and dependency analysis, then executes fixes with conservative test verification.
+
+**Fix Process**:
+- **Planning Phase**: AI analyzes findings, generates fix plan with grouping and execution strategy
+- **Execution Phase**: Main orchestrator coordinates agents per timeline stages
+- **No rigid structure**: Adapts to task requirements, not bound to fixed JSON format
+
+**vs Manual Fixing**:
+- **Manual**: Developer reviews findings one-by-one, fixes sequentially
+- **Automated**: AI groups related issues, executes in optimal parallel/serial order with automatic test verification
+
+### Value Proposition
+1. **Intelligent Planning**: AI-powered analysis identifies optimal grouping and execution strategy
+2. **Multi-stage Coordination**: Supports complex parallel + serial execution with dependency management
+3. **Conservative Safety**: Mandatory test verification with automatic rollback on failure
+4. **Real-time Visibility**: Dashboard shows planning progress, stage timeline, and active agents
+5. **Resume Support**: Checkpoint-based recovery for interrupted sessions
+
+### Orchestrator Boundary (CRITICAL)
+- **ONLY command** for automated review finding fixes
+- Manages: Planning phase coordination, stage-based execution, agent scheduling, progress tracking
+- Delegates: Fix planning to @cli-planning-agent, fix execution to @cli-execute-agent
+
+
+### Execution Flow
+
+```
+Phase 1: Discovery & Initialization
+   └─ Validate export file, create fix session structure, initialize state files → Generate fix-dashboard.html
+
+Phase 2: Planning Coordination (@cli-planning-agent)
+   ├─ Analyze findings for patterns and dependencies
+   ├─ Group by file + dimension + root cause similarity
+   ├─ Determine execution strategy (parallel/serial/hybrid)
+   ├─ Generate fix timeline with stages
+   └─ Output: fix-plan.json (dashboard auto-polls for status)
+
+Phase 3: Execution Orchestration (Stage-based)
+   For each timeline stage:
+   ├─ Load groups for this stage
+   ├─ If parallel: Launch all group agents simultaneously
+   ├─ If serial: Execute groups sequentially
+   ├─ Each agent:
+   │  ├─ Analyze code context
+   │  ├─ Apply fix per strategy
+   │  ├─ Run affected tests
+   │  ├─ On test failure: Rollback, retry up to max_iterations
+   │  └─ On success: Commit, update fix-progress-{N}.json
+   └─ Advance to next stage
+
+Phase 4: Completion & Aggregation
+   └─ Aggregate results → Generate fix-summary.md → Update history → Output summary
+
+Phase 5: Session Completion (Optional)
+   └─ If all fixes successful → Prompt to complete workflow session
+```
+
+### Agent Roles
+
+| Agent | Responsibility |
+|-------|---------------|
+| **Orchestrator** | Input validation, session management, planning coordination, stage-based execution scheduling, progress tracking, aggregation |
+| **@cli-planning-agent** | Findings analysis, intelligent grouping (file+dimension+root cause), execution strategy determination (parallel/serial/hybrid), timeline generation with dependency mapping |
+| **@cli-execute-agent** | Fix execution per group, code context analysis, Edit tool operations, test verification, git rollback on failure, completion JSON generation |
+
+## Enhanced Features
+
+### 1. Two-Phase Architecture
+
+**Phase Separation**:
+
+| Phase | Agent | Output | Purpose |
+|-------|-------|--------|---------|
+| **Planning** | @cli-planning-agent | fix-plan.json | Analyze findings, group intelligently, determine optimal execution strategy |
+| **Execution** | @cli-execute-agent | completions/*.json | Execute fixes per plan with test verification and rollback |
+
+**Benefits**:
+- Clear separation of concerns (analysis vs execution)
+- Reusable plans (can re-execute without re-planning)
+- Better error isolation (planning failures vs execution failures)
+
+### 2. Intelligent Grouping Strategy
+
+**Three-Level Grouping**:
+
+```javascript
+// Level 1: Primary grouping by file + dimension
+{file: "auth.ts", dimension: "security"} → Group A
+{file: "auth.ts", dimension: "quality"} → Group B
+{file: "query-builder.ts", dimension: "security"} → Group C
+
+// Level 2: Secondary grouping by root cause similarity
+Group A findings → Semantic similarity analysis (threshold 0.7)
+  → Sub-group A1: "missing-input-validation" (findings 1, 2)
+  → Sub-group A2: "insecure-crypto" (finding 3)
+
+// Level 3: Dependency analysis
+Sub-group A1 creates validation utilities
+Sub-group C4 depends on those utilities
+→ A1 must execute before C4 (serial stage dependency)
+```
+
+**Similarity Computation**:
+- Combine: `description + recommendation + category`
+- Vectorize: TF-IDF or LLM embedding
+- Cluster: Greedy algorithm with cosine similarity > 0.7
+
+### 3. Execution Strategy Determination
+
+**Strategy Types**:
+
+| Strategy | When to Use | Stage Structure |
+|----------|-------------|-----------------|
+| **Parallel** | All groups independent, different files | Single stage, all groups in parallel |
+| **Serial** | Strong dependencies, shared resources | Multiple stages, one group per stage |
+| **Hybrid** | Mixed dependencies | Multiple stages, parallel within stages |
+
+**Dependency Detection**:
+- Shared file modifications
+- Utility creation + usage patterns
+- Test dependency chains
+- Risk level clustering (high-risk groups isolated)
+
+### 4. Conservative Test Verification
+
+**Test Strategy** (per fix):
+
+```javascript
+// 1. Identify affected tests
+const testPattern = identifyTestPattern(finding.file);
+// e.g., "tests/auth/**/*.test.*" for src/auth/service.ts
+
+// 2. Run tests
+const result = await runTests(testPattern);
+
+// 3. Evaluate
+if (result.passRate < 100%) {
+  // Rollback
+  await gitCheckout(finding.file);
+
+  // Retry with failure context
+  if (attempts < maxIterations) {
+    const fixContext = analyzeFailure(result.stderr);
+    regenerateFix(finding, fixContext);
+    retry();
+  } else {
+    markFailed(finding.id);
+  }
+} else {
+  // Commit
+  await gitCommit(`Fix: ${finding.title} [${finding.id}]`);
+  markFixed(finding.id);
+}
+```
+
+**Pass Criteria**: 100% test pass rate (no partial fixes)
+
+## Core Responsibilities
+
+### Orchestrator
+
+**Phase 1: Discovery & Initialization**
+- Input validation: Check export file exists and is valid JSON
+- Auto-discovery: If review-dir provided, find latest `*-fix-export.json`
+- Session creation: Generate fix-session-id (`fix-{timestamp}`)
+- Directory structure: Create `{review-dir}/fixes/{fix-session-id}/` with subdirectories
+- State files: Initialize active-fix-session.json (session marker)
+- Dashboard generation: Create fix-dashboard.html from template (see Dashboard Generation below)
+- TodoWrite initialization: Set up 4-phase tracking
+
+**Phase 2: Planning Coordination**
+- Launch @cli-planning-agent with findings data and project context
+- Monitor planning progress (dashboard shows "Planning fixes..." indicator)
+- Validate fix-plan.json output (schema conformance, includes metadata with session status)
+- Load plan into memory for execution phase
+- TodoWrite update: Mark planning complete, start execution
+
+**Phase 3: Execution Orchestration**
+- Load fix-plan.json timeline stages
+- For each stage:
+  - If parallel mode: Launch all group agents via `Promise.all()`
+  - If serial mode: Execute groups sequentially with `await`
+  - Assign agent IDs (agents update their fix-progress-{N}.json)
+- Handle agent failures gracefully (mark group as failed, continue)
+- Advance to next stage only when current stage complete
+- Dashboard polls and aggregates fix-progress-{N}.json files for display
+
+**Phase 4: Completion & Aggregation**
+- Collect final status from all fix-progress-{N}.json files
+- Generate fix-summary.md with timeline and results
+- Update fix-history.json with new session entry
+- Remove active-fix-session.json
+- TodoWrite completion: Mark all phases done
+- Output summary to user with dashboard link
+
+**Phase 5: Session Completion (Optional)**
+- If all findings fixed successfully (no failures):
+  - Prompt user: "All fixes complete. Complete workflow session? [Y/n]"
+  - If confirmed: Execute `/workflow:session:complete` to archive session with lessons learned
+- If partial success (some failures):
+  - Output: "Some findings failed. Review fix-summary.md before completing session."
+  - Do NOT auto-complete session
+
+### Dashboard Generation
+
+**MANDATORY**: Dashboard MUST be generated from template during Phase 1 initialization
+
+**Template Location**: `~/.claude/templates/fix-dashboard.html`
+
+**⚠️ POST-GENERATION**: Orchestrator and agents MUST NOT read/write/modify fix-dashboard.html after creation
+
+**Generation Steps**:
+
+```bash
+# 1. Copy template to fix session directory
+cp ~/.claude/templates/fix-dashboard.html ${sessionDir}/fixes/${fixSessionId}/fix-dashboard.html
+
+# 2. Replace SESSION_ID placeholder
+sed -i "s|{{SESSION_ID}}|${sessionId}|g" ${sessionDir}/fixes/${fixSessionId}/fix-dashboard.html
+
+# 3. Replace REVIEW_DIR placeholder
+sed -i "s|{{REVIEW_DIR}}|${reviewDir}|g" ${sessionDir}/fixes/${fixSessionId}/fix-dashboard.html
+
+# 4. Start local server and output dashboard URL
+cd ${sessionDir}/fixes/${fixSessionId} && python -m http.server 8766 --bind 127.0.0.1 &
+echo "🔧 Fix Dashboard: http://127.0.0.1:8766/fix-dashboard.html"
+echo "   (Press Ctrl+C to stop server when done)"
+```
+
+**Dashboard Features**:
+- Real-time progress tracking via JSON polling (3-second interval)
+- Stage timeline visualization with parallel/serial execution modes
+- Active groups and agents monitoring
+- Flow control steps tracking for each agent
+- Fix history drawer with session summaries
+- Consumes new JSON structure (fix-plan.json with metadata + fix-progress-{N}.json)
+
+**JSON Consumption**:
+- `fix-plan.json`: Reads metadata field for session info, timeline stages, groups configuration
+- `fix-progress-{N}.json`: Polls all progress files to aggregate real-time status
+- `active-fix-session.json`: Detects active session on load
+- `fix-history.json`: Loads historical fix sessions
+
+### Output File Structure
+
+```
+.workflow/active/WFS-{session-id}/.review/
+├── fix-export-{timestamp}.json     # Exported findings (input)
+└── fixes/{fix-session-id}/
+    ├── fix-dashboard.html          # Interactive dashboard (generated once, auto-polls JSON)
+    ├── fix-plan.json               # Planning agent output (execution plan with metadata)
+    ├── fix-progress-1.json         # Group 1 progress (planning agent init → agent updates)
+    ├── fix-progress-2.json         # Group 2 progress (planning agent init → agent updates)
+    ├── fix-progress-3.json         # Group 3 progress (planning agent init → agent updates)
+    ├── fix-summary.md              # Final report (orchestrator generates)
+    ├── active-fix-session.json     # Active session marker
+    └── fix-history.json            # All sessions history
+```
+
+**File Producers**:
+- **Orchestrator**: `fix-dashboard.html` (generated once from template during Phase 1)
+- **Planning Agent**: `fix-plan.json` (with metadata), all `fix-progress-*.json` (initial state)
+- **Execution Agents**: Update assigned `fix-progress-{N}.json` in real-time
+- **Dashboard (Browser)**: Reads `fix-plan.json` + all `fix-progress-*.json`, aggregates in-memory every 3 seconds via JavaScript polling
+
+
+### Agent Invocation Template
+
+**Planning Agent**:
+```javascript
+Task({
+  subagent_type: "cli-planning-agent",
+  description: `Generate fix plan and initialize progress files for ${findings.length} findings`,
+  prompt: `
+## Task Objective
+Analyze ${findings.length} code review findings and generate execution plan with intelligent grouping and timeline coordination.
+
+## Input Data
+Review Session: ${reviewId}
+Fix Session ID: ${fixSessionId}
+Total Findings: ${findings.length}
+
+Findings:
+${JSON.stringify(findings, null, 2)}
+
+Project Context:
+- Structure: ${projectStructure}
+- Test Framework: ${testFramework}
+- Git Status: ${gitStatus}
+
+## Output Requirements
+
+### 1. fix-plan.json
+Execute: cat ~/.claude/workflows/cli-templates/fix-plan-template.json
+
+Generate execution plan following template structure:
+
+**Key Generation Rules**:
+- **Metadata**: Populate fix_session_id, review_session_id, status ("planning"), created_at, started_at timestamps
+- **Execution Strategy**: Choose approach (parallel/serial/hybrid) based on dependency analysis, set parallel_limit and stages count
+- **Groups**: Create groups (G1, G2, ...) with intelligent grouping (see Analysis Requirements below), assign progress files (fix-progress-1.json, ...), populate fix_strategy with approach/complexity/test_pattern, assess risks, identify dependencies
+- **Timeline**: Define stages respecting dependencies, set execution_mode per stage, map groups to stages, calculate critical path
+
+### 2. fix-progress-{N}.json (one per group)
+Execute: cat ~/.claude/workflows/cli-templates/fix-progress-template.json
+
+For each group (G1, G2, G3, ...), generate fix-progress-{N}.json following template structure:
+
+**Initial State Requirements**:
+- Status: "pending", phase: "waiting"
+- Timestamps: Set last_update to now, others null
+- Findings: Populate from review findings with status "pending", all operation fields null
+- Summary: Initialize all counters to zero
+- Flow control: Empty implementation_approach array
+- Errors: Empty array
+
+**CRITICAL**: Ensure complete template structure for Dashboard consumption - all fields must be present.
+
+## Analysis Requirements
+
+### Intelligent Grouping Strategy
+Group findings using these criteria (in priority order):
+
+1. **File Proximity**: Findings in same file or related files
+2. **Dimension Affinity**: Same dimension (security, performance, etc.)
+3. **Root Cause Similarity**: Similar underlying issues
+4. **Fix Approach Commonality**: Can be fixed with similar approach
+
+**Grouping Guidelines**:
+- Optimal group size: 2-5 findings per group
+- Avoid cross-cutting concerns in same group
+- Consider test isolation (different test suites → different groups)
+- Balance workload across groups for parallel execution
+
+### Execution Strategy Determination
+
+**Parallel Mode**: Use when groups are independent, no shared files
+**Serial Mode**: Use when groups have dependencies or shared resources
+**Hybrid Mode**: Use for mixed dependency graphs (recommended for most cases)
+
+**Dependency Analysis**:
+- Identify shared files between groups
+- Detect test dependency chains
+- Evaluate risk of concurrent modifications
+
+### Risk Assessment
+
+For each group, evaluate:
+- **Complexity**: Based on code structure, file size, existing tests
+- **Impact Scope**: Number of files affected, API surface changes
+- **Rollback Feasibility**: Ease of reverting changes if tests fail
+
+### Test Strategy
+
+For each group, determine:
+- **Test Pattern**: Glob pattern matching affected tests
+- **Pass Criteria**: All tests must pass (100% pass rate)
+- **Test Command**: Infer from project (package.json, pytest.ini, etc.)
+
+## Output Files
+
+Write to ${sessionDir}:
+- ./fix-plan.json
+- ./fix-progress-1.json
+- ./fix-progress-2.json
+- ./fix-progress-{N}.json (as many as groups created)
+
+## Quality Checklist
+
+Before finalizing outputs:
+- ✅ All findings assigned to exactly one group
+- ✅ Group dependencies correctly identified
+- ✅ Timeline stages respect dependencies
+- ✅ All progress files have complete initial structure
+- ✅ Test patterns are valid and specific
+- ✅ Risk assessments are realistic
+- ✅ Estimated times are reasonable
+  `
+})
+```
+
+**Execution Agent** (per group):
+```javascript
+Task({
+  subagent_type: "cli-execute-agent",
+  description: `Fix ${group.findings.length} issues: ${group.group_name}`,
+  prompt: `
+## Task Objective
+Execute fixes for code review findings in group ${group.group_id}. Update progress file in real-time with flow control tracking for dashboard visibility.
+
+## Assignment
+- Group ID: ${group.group_id}
+- Group Name: ${group.group_name}
+- Progress File: ${sessionDir}/${group.progress_file}
+- Findings Count: ${group.findings.length}
+- Max Iterations: ${maxIterations} (per finding)
+
+## Fix Strategy
+${JSON.stringify(group.fix_strategy, null, 2)}
+
+## Risk Assessment
+${JSON.stringify(group.risk_assessment, null, 2)}
+
+## Execution Flow
+
+### Initialization (Before Starting)
+
+1. Read ${group.progress_file} to load initial state
+2. Update progress file:
+   - assigned_agent: "${agentId}"
+   - status: "in-progress"
+   - started_at: Current ISO 8601 timestamp
+   - last_update: Current ISO 8601 timestamp
+3. Write updated state back to ${group.progress_file}
+
+### Main Execution Loop
+
+For EACH finding in ${group.progress_file}.findings:
+
+#### Step 1: Analyze Context
+
+**Before Step**:
+- Update finding: status→"in-progress", started_at→now()
+- Update current_finding: Populate with finding details, status→"analyzing", action→"Reading file and understanding code structure"
+- Update phase→"analyzing"
+- Update flow_control: Add "analyze_context" step to implementation_approach (status→"in-progress"), set current_step→"analyze_context"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Read file: finding.file
+- Understand code structure around line: finding.line
+- Analyze surrounding context (imports, dependencies, related functions)
+- Review recommendations: finding.recommendations
+
+**After Step**:
+- Update flow_control: Mark "analyze_context" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+
+#### Step 2: Apply Fix
+
+**Before Step**:
+- Update current_finding: status→"fixing", action→"Applying code changes per recommendations"
+- Update phase→"fixing"
+- Update flow_control: Add "apply_fix" step to implementation_approach (status→"in-progress"), set current_step→"apply_fix"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Use Edit tool to implement code changes per finding.recommendations
+- Follow fix_strategy.approach
+- Maintain code style and existing patterns
+
+**After Step**:
+- Update flow_control: Mark "apply_fix" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+
+#### Step 3: Test Verification
+
+**Before Step**:
+- Update current_finding: status→"testing", action→"Running test suite to verify fix"
+- Update phase→"testing"
+- Update flow_control: Add "run_tests" step to implementation_approach (status→"in-progress"), set current_step→"run_tests"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Run tests using fix_strategy.test_pattern
+- Require 100% pass rate
+- Capture test output
+
+**On Test Failure**:
+- Git rollback: \`git checkout -- \${finding.file}\`
+- Increment finding.attempts
+- Update flow_control: Mark "run_tests" step as "failed" with completed_at→now()
+- Update errors: Add entry (finding_id, error_type→"test_failure", message, timestamp)
+- If finding.attempts < ${maxIterations}:
+  - Reset flow_control: implementation_approach→[], current_step→null
+  - Retry from Step 1
+- Else:
+  - Update finding: status→"completed", result→"failed", error_message→"Max iterations reached", completed_at→now()
+  - Update summary counts, move to next finding
+
+**On Test Success**:
+- Update flow_control: Mark "run_tests" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+- Proceed to Step 4
+
+#### Step 4: Commit Changes
+
+**Before Step**:
+- Update current_finding: status→"committing", action→"Creating git commit for successful fix"
+- Update phase→"committing"
+- Update flow_control: Add "commit_changes" step to implementation_approach (status→"in-progress"), set current_step→"commit_changes"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Git commit: \`git commit -m "fix(${finding.dimension}): ${finding.title} [${finding.id}]"\`
+- Capture commit hash
+
+**After Step**:
+- Update finding: status→"completed", result→"fixed", commit_hash→<captured>, test_passed→true, completed_at→now()
+- Update flow_control: Mark "commit_changes" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+
+#### After Each Finding
+
+- Update summary: Recalculate counts (pending/in_progress/fixed/failed) and percent_complete
+- If all findings completed: Clear current_finding, reset flow_control
+- Update last_update→now(), write to ${group.progress_file}
+
+### Final Completion
+
+When all findings processed:
+- Update status→"completed", phase→"done", summary.percent_complete→100.0
+- Update last_update→now(), write final state to ${group.progress_file}
+
+## Critical Requirements
+
+### Progress File Updates
+- **MUST update after every significant action** (before/after each step)
+- **Dashboard polls every 3 seconds** - ensure writes are atomic
+- **Always maintain complete structure** - never write partial updates
+- **Use ISO 8601 timestamps** - e.g., "2025-01-25T14:36:00Z"
+
+### Flow Control Format
+Follow action-planning-agent flow_control.implementation_approach format:
+- step: Identifier (e.g., "analyze_context", "apply_fix")
+- action: Human-readable description
+- status: "pending" | "in-progress" | "completed" | "failed"
+- started_at: ISO 8601 timestamp or null
+- completed_at: ISO 8601 timestamp or null
+
+### Error Handling
+- Capture all errors in errors[] array
+- Never leave progress file in invalid state
+- Always write complete updates, never partial
+- On unrecoverable error: Mark group as failed, preserve state
+
+## Test Patterns
+Use fix_strategy.test_pattern to run affected tests:
+- Pattern: ${group.fix_strategy.test_pattern}
+- Command: Infer from project (npm test, pytest, etc.)
+- Pass Criteria: 100% pass rate required
+  `
+})
+```
+
+
+
+### Error Handling
+
+**Planning Failures**:
+- Invalid template → Abort with error message
+- Insufficient findings data → Request complete export
+- Planning timeout → Retry once, then fail gracefully
+
+**Execution Failures**:
+- Agent crash → Mark group as failed, continue with other groups
+- Test command not found → Skip test verification, warn user
+- Git operations fail → Abort with error, preserve state
+
+**Rollback Scenarios**:
+- Test failure after fix → Automatic `git checkout` rollback
+- Max iterations reached → Leave file unchanged, mark as failed
+- Unrecoverable error → Rollback entire group, save checkpoint
+
+### TodoWrite Structure
+
+**Initialization**:
+```javascript
+TodoWrite({
+  todos: [
+    {content: "Phase 1: Discovery & Initialization", status: "completed"},
+    {content: "Phase 2: Planning", status: "in_progress"},
+    {content: "Phase 3: Execution", status: "pending"},
+    {content: "Phase 4: Completion", status: "pending"}
+  ]
+});
+```
+
+**During Execution**:
+```javascript
+TodoWrite({
+  todos: [
+    {content: "Phase 1: Discovery & Initialization", status: "completed"},
+    {content: "Phase 2: Planning", status: "completed"},
+    {content: "Phase 3: Execution", status: "in_progress"},
+    {content: "  → Stage 1: Parallel execution (3 groups)", status: "completed"},
+    {content: "    • Group G1: Auth validation (2 findings)", status: "completed"},
+    {content: "    • Group G2: Query security (3 findings)", status: "completed"},
+    {content: "    • Group G3: Config quality (1 finding)", status: "completed"},
+    {content: "  → Stage 2: Serial execution (1 group)", status: "in_progress"},
+    {content: "    • Group G4: Dependent fixes (2 findings)", status: "in_progress"},
+    {content: "Phase 4: Completion", status: "pending"}
+  ]
+});
+```
+
+**Update Rules**:
+- Add stage items dynamically based on fix-plan.json timeline
+- Add group items per stage
+- Mark completed immediately after each group finishes
+- Update parent phase status when all child items complete
+
+## Best Practices
+
+1. **Trust AI Planning**: Planning agent's grouping and execution strategy are based on dependency analysis
+2. **Conservative Approach**: Test verification is mandatory - no fixes kept without passing tests
+3. **Parallel Efficiency**: Default 3 concurrent agents balances speed and resource usage
+4. **Monitor Dashboard**: Real-time stage timeline and agent status provide execution visibility
+5. **Resume Support**: Fix sessions can resume from checkpoints after interruption
+6. **Manual Review**: Always review failed fixes manually - may require architectural changes
+7. **Incremental Fixing**: Start with small batches (5-10 findings) before large-scale fixes
+
+

.claude/commands/workflow/review-module-cycle.md

@@ -0,0 +1,795 @@
+---
+name: review-module-cycle
+description: Independent multi-dimensional code review for specified modules/files. Analyzes specific code paths across 7 dimensions with hybrid parallel-iterative execution, independent of workflow sessions.
+argument-hint: "<path-pattern> [--dimensions=security,architecture,...] [--max-iterations=N]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
+---
+
+# Workflow Review-Module-Cycle Command
+
+## Quick Start
+
+```bash
+# Review specific module (all 7 dimensions)
+/workflow:review-module-cycle src/auth/**
+
+# Review multiple modules
+/workflow:review-module-cycle src/auth/**,src/payment/**
+
+# Review with custom dimensions
+/workflow:review-module-cycle src/payment/** --dimensions=security,architecture,quality
+
+# Review specific files
+/workflow:review-module-cycle src/payment/processor.ts,src/payment/validator.ts
+```
+
+**Review Scope**: Specified modules/files only (independent of git history)
+**Session Requirement**: Auto-creates workflow session via `/workflow:session:start`
+**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based)
+**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
+**Max Iterations**: 3 (adjustable via --max-iterations)
+**Default Iterations**: 1 (deep-dive runs once; use --max-iterations=0 to skip)
+**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
+
+## What & Why
+
+### Core Concept
+Independent multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **specific modules or files**.
+
+**Review Scope**:
+- **Module-based**: Reviews specified file patterns (e.g., `src/auth/**`, `*.ts`)
+- **Session-integrated**: Runs within workflow session context for unified tracking
+- **Output location**: `.review/` subdirectory within active session
+
+**vs Session Review**:
+- **Session Review** (`review-session-cycle`): Reviews git changes within a workflow session
+- **Module Review** (`review-module-cycle`): Reviews any specified code paths, regardless of git history
+- **Common output**: Both use same `.review/` directory structure within session
+
+### Value Proposition
+1. **Module-Focused Review**: Target specific code areas independent of git history
+2. **Session-Integrated**: Review results tracked within workflow session for unified management
+3. **Comprehensive Coverage**: Same 7 specialized dimensions as session review
+4. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns
+5. **Real-time Visibility**: JSON-based progress tracking with interactive HTML dashboard
+6. **Unified Archive**: Review results archived with session for historical reference
+
+### Orchestrator Boundary (CRITICAL)
+- **ONLY command** for independent multi-dimensional module review
+- Manages: dimension coordination, aggregation, iteration control, progress tracking
+- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode
+- **⚠️ DASHBOARD CONSTRAINT**: Dashboard is generated ONCE during Phase 1 initialization. After initialization, orchestrator and agents MUST NOT read, write, or modify dashboard.html - it remains static for user interaction only.
+
+## How It Works
+
+### Execution Flow
+
+```
+Phase 1: Discovery & Initialization
+   └─ Resolve file patterns, validate paths, initialize state, create output structure → Generate dashboard.html
+
+Phase 2: Parallel Reviews (for each dimension)
+   ├─ Launch 7 review agents simultaneously
+   ├─ Each executes CLI analysis via Gemini/Qwen on specified files
+   ├─ Generate dimension JSON + markdown reports
+   └─ Update review-progress.json
+
+Phase 3: Aggregation
+   ├─ Load all dimension JSON files
+   ├─ Calculate severity distribution (critical/high/medium/low)
+   ├─ Identify cross-cutting concerns (files in 3+ dimensions)
+   └─ Decision:
+      ├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate)
+      └─ Else → Phase 5 (Complete)
+
+Phase 4: Iterative Deep-Dive (optional)
+   ├─ Select critical findings (max 5 per iteration)
+   ├─ Launch deep-dive agents for root cause analysis
+   ├─ Generate remediation plans with impact assessment
+   ├─ Re-assess severity based on analysis
+   └─ Loop until no critical findings OR max iterations
+
+Phase 5: Completion
+   └─ Finalize review-progress.json → Output dashboard path
+```
+
+### Agent Roles
+
+| Agent | Responsibility |
+|-------|---------------|
+| **Orchestrator** | Phase control, path resolution, state management, aggregation logic, iteration control |
+| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports |
+| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment |
+
+## Enhanced Features
+
+### 1. Review Dimensions Configuration
+
+**7 Specialized Dimensions** with priority-based allocation:
+
+| Dimension | Template | Priority | Timeout |
+|-----------|----------|----------|---------|
+| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min |
+| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min |
+| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min |
+| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min |
+| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min |
+| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min |
+| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min |
+
+*Custom focus: "Assess technical debt and maintainability"
+
+**Category Definitions by Dimension**:
+
+```javascript
+const CATEGORIES = {
+  security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'],
+  architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'],
+  quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'],
+  'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'],
+  performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'],
+  maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'],
+  'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style']
+};
+```
+
+### 2. Path Pattern Resolution
+
+**Syntax Rules**:
+- All paths are **relative** from project root (e.g., `src/auth/**` not `/src/auth/**`)
+- Multiple patterns: comma-separated, **no spaces** (e.g., `src/auth/**,src/payment/**`)
+- Glob and specific files can be mixed (e.g., `src/auth/**,src/config.ts`)
+
+**Supported Patterns**:
+| Pattern Type | Example | Description |
+|--------------|---------|-------------|
+| Glob directory | `src/auth/**` | All files under src/auth/ |
+| Glob with extension | `src/**/*.ts` | All .ts files under src/ |
+| Specific file | `src/payment/processor.ts` | Single file |
+| Multiple patterns | `src/auth/**,src/payment/**` | Comma-separated (no spaces) |
+
+**Resolution Process**:
+1. Parse input pattern (split by comma, trim whitespace)
+2. Expand glob patterns to file list via `find` command
+3. Validate all files exist and are readable
+4. Error if pattern matches 0 files
+5. Store resolved file list in review-state.json
+
+### 3. Aggregation Logic
+
+**Cross-Cutting Concern Detection**:
+1. Files appearing in 3+ dimensions = **Critical Files**
+2. Same issue pattern across dimensions = **Systemic Issue**
+3. Severity clustering in specific files = **Hotspots**
+
+**Deep-Dive Selection Criteria**:
+- All critical severity findings (priority 1)
+- Top 3 high-severity findings in critical files (priority 2)
+- Max 5 findings per iteration (prevent overwhelm)
+
+### 4. Severity Assessment
+
+**Severity Levels**:
+- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass
+- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt
+- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns
+- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues
+
+**Iteration Trigger**:
+- Critical findings > 0 OR
+- High findings > 5 OR
+- Critical files count > 0
+
+## Core Responsibilities
+
+### Orchestrator
+
+**Phase 1: Discovery & Initialization**
+
+**Step 1: Session Creation**
+```javascript
+// Create workflow session for this review
+SlashCommand(command="/workflow:session:start \"Code review for [target_pattern]\"")
+
+// Parse output
+const sessionId = output.match(/SESSION_ID: (WFS-[^\s]+)/)[1];
+```
+
+**Step 2: Path Resolution & Validation**
+```bash
+# Expand glob pattern to file list (relative paths from project root)
+find . -path "./src/auth/**" -type f | sed 's|^\./||'
+
+# Validate files exist and are readable
+for file in ${resolvedFiles[@]}; do
+  test -r "$file" || error "File not readable: $file"
+done
+```
+- Parse and expand file patterns (glob support): `src/auth/**` → actual file list
+- Validation: Ensure all specified files exist and are readable
+- Store as **relative paths** from project root (e.g., `src/auth/service.ts`)
+- Agents construct absolute paths dynamically during execution
+
+**Step 3: Output Directory Setup**
+- Output directory: `.workflow/active/${sessionId}/.review/`
+- Create directory structure:
+  ```bash
+  mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
+  ```
+
+**Step 4: Initialize Review State**
+- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations, resolved_files (merged metadata + state)
+- Progress tracking: Create `review-progress.json` for dashboard polling
+
+**Step 5: Dashboard Generation**
+
+**Constraints**:
+- **MANDATORY**: Dashboard MUST be generated from template: `~/.claude/templates/review-cycle-dashboard.html`
+- **PROHIBITED**: Direct creation or custom generation without template
+- **POST-GENERATION**: Orchestrator and agents MUST NOT read/write/modify dashboard.html after creation
+
+**Generation Commands** (3 independent steps):
+```bash
+# Step 1: Copy template to output location
+cp ~/.claude/templates/review-cycle-dashboard.html ${sessionDir}/.review/dashboard.html
+
+# Step 2: Replace SESSION_ID placeholder
+sed -i "s|{{SESSION_ID}}|${sessionId}|g" ${sessionDir}/.review/dashboard.html
+
+# Step 3: Replace REVIEW_TYPE placeholder
+sed -i "s|{{REVIEW_TYPE}}|module|g" ${sessionDir}/.review/dashboard.html
+
+# Step 4: Replace REVIEW_DIR placeholder
+sed -i "s|{{REVIEW_DIR}}|${reviewDir}|g" ${sessionDir}/.review/dashboard.html
+
+# Output: Start local server and output dashboard URL
+# Use Python HTTP server (available on most systems)
+cd ${sessionDir}/.review && python -m http.server 8765 --bind 127.0.0.1 &
+echo "📊 Dashboard: http://127.0.0.1:8765/dashboard.html"
+echo "   (Press Ctrl+C to stop server when done)"
+```
+
+**Step 6: TodoWrite Initialization**
+- Set up progress tracking with hierarchical structure
+- Mark Phase 1 completed, Phase 2 in_progress
+
+**Phase 2: Parallel Review Coordination**
+- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode)
+- Pass dimension-specific context (template, timeout, custom focus, **target files**)
+- Monitor completion via review-progress.json updates
+- TodoWrite updates: Mark dimensions as completed
+- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout)
+
+**Phase 3: Aggregation**
+- Load all dimension JSON files from dimensions/
+- Calculate severity distribution: Count by critical/high/medium/low
+- Identify cross-cutting concerns: Files in 3+ dimensions
+- Select deep-dive findings: Critical + high in critical files (max 5)
+- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist
+- Update review-state.json with aggregation results
+
+**Phase 4: Iteration Control**
+- Check iteration count < max_iterations (default 3)
+- Launch deep-dive agents for selected findings
+- Collect remediation plans and re-assessed severities
+- Update severity distribution based on re-assessments
+- Record iteration in review-state.json
+- Loop back to aggregation if still have critical/high findings
+
+**Phase 5: Completion**
+- Finalize review-progress.json with completion statistics
+- Update review-state.json with completion_time and phase=complete
+- TodoWrite completion: Mark all tasks done
+- Output: Dashboard path to user
+
+
+
+### Output File Structure
+
+```
+.workflow/active/WFS-{session-id}/.review/
+├── review-state.json                    # Orchestrator state machine (includes metadata)
+├── review-progress.json                 # Real-time progress for dashboard
+├── dimensions/                          # Per-dimension results
+│   ├── security.json
+│   ├── architecture.json
+│   ├── quality.json
+│   ├── action-items.json
+│   ├── performance.json
+│   ├── maintainability.json
+│   └── best-practices.json
+├── iterations/                          # Deep-dive results
+│   ├── iteration-1-finding-{uuid}.json
+│   └── iteration-2-finding-{uuid}.json
+├── reports/                             # Human-readable reports
+│   ├── security-analysis.md
+│   ├── security-cli-output.txt
+│   ├── deep-dive-1-{uuid}.md
+│   └── ...
+└── dashboard.html                       # Interactive dashboard (primary output)
+```
+
+**Session Context**:
+```
+.workflow/active/WFS-{session-id}/
+├── workflow-session.json
+├── IMPL_PLAN.md
+├── TODO_LIST.md
+├── .task/
+├── .summaries/
+└── .review/                             # Review results (this command)
+    └── (structure above)
+```
+
+### Review State JSON
+
+**Purpose**: Unified state machine and metadata (merged from metadata + state)
+
+```json
+{
+  "review_id": "review-20250125-143022",
+  "review_type": "module",
+  "session_id": "WFS-auth-system",
+  "metadata": {
+    "created_at": "2025-01-25T14:30:22Z",
+    "target_pattern": "src/auth/**",
+    "resolved_files": [
+      "src/auth/service.ts",
+      "src/auth/validator.ts",
+      "src/auth/middleware.ts"
+    ],
+    "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
+    "max_iterations": 3
+  },
+  "phase": "parallel|aggregate|iterate|complete",
+  "current_iteration": 1,
+  "dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
+  "selected_strategy": "comprehensive",
+  "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete",
+  "severity_distribution": {
+    "critical": 2,
+    "high": 5,
+    "medium": 12,
+    "low": 8
+  },
+  "critical_files": [...],
+  "iterations": [...],
+  "completion_criteria": {...}
+}
+```
+
+### Review Progress JSON
+
+**Purpose**: Real-time dashboard updates via polling
+
+```json
+{
+  "review_id": "review-20250125-143022",
+  "last_update": "2025-01-25T14:35:10Z",
+  "phase": "parallel|aggregate|iterate|complete",
+  "current_iteration": 1,
+  "progress": {
+    "parallel_review": {
+      "total_dimensions": 7,
+      "completed": 5,
+      "in_progress": 2,
+      "percent_complete": 71
+    },
+    "deep_dive": {
+      "total_findings": 6,
+      "analyzed": 2,
+      "in_progress": 1,
+      "percent_complete": 33
+    }
+  },
+  "agent_status": [
+    {
+      "agent_type": "review-agent",
+      "dimension": "security",
+      "status": "completed",
+      "started_at": "2025-01-25T14:30:00Z",
+      "completed_at": "2025-01-25T15:15:00Z",
+      "duration_ms": 2700000
+    },
+    {
+      "agent_type": "deep-dive-agent",
+      "finding_id": "sec-001-uuid",
+      "status": "in_progress",
+      "started_at": "2025-01-25T14:32:00Z"
+    }
+  ],
+  "estimated_completion": "2025-01-25T16:00:00Z"
+}
+```
+
+### Agent Output Schemas
+
+**Agent-produced JSON files follow standardized schemas**:
+
+1. **Dimension Results** (cli-explore-agent output from parallel reviews)
+   - Schema: `~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json`
+   - Output: `{output-dir}/dimensions/{dimension}.json`
+   - Contains: findings array, summary statistics, cross_references
+
+2. **Deep-Dive Results** (cli-explore-agent output from iterations)
+   - Schema: `~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json`
+   - Output: `{output-dir}/iterations/iteration-{N}-finding-{uuid}.json`
+   - Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity
+
+### Agent Invocation Template
+
+**Review Agent** (parallel execution, 7 instances):
+
+```javascript
+Task(
+  subagent_type="cli-explore-agent",
+  description=`Execute ${dimension} review analysis via Deep Scan`,
+  prompt=`
+    ## Task Objective
+    Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for specified module files
+
+    ## Analysis Mode Selection
+    Use **Deep Scan mode** for this review:
+    - Phase 1: Bash structural scan for standard patterns (classes, functions, imports)
+    - Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns
+    - Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings)
+
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
+    1. Read review state: ${reviewStateJsonPath}
+    2. Get target files: Read resolved_files from review-state.json
+    3. Validate file access: bash(ls -la ${targetFiles.join(' ')})
+    4. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
+
+    ## Review Context
+    - Review Type: module (independent)
+    - Review Dimension: ${dimension}
+    - Review ID: ${reviewId}
+    - Target Pattern: ${targetPattern}
+    - Resolved Files: ${resolvedFiles.length} files
+    - Output Directory: ${outputDir}
+
+    ## CLI Configuration
+    - Tool Priority: gemini → qwen → codex (fallback chain)
+    - Custom Focus: ${customFocus || 'Standard dimension analysis'}
+    - Mode: analysis (READ-ONLY)
+    - Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')}
+
+    ## Expected Deliverables
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 4, follow schema exactly
+
+    1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
+
+       **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
+
+       Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
+
+       Required top-level fields:
+       - dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at)
+       - cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms
+       - summary (FLAT structure), findings, cross_references
+
+       Summary MUST be FLAT (NOT nested by_severity):
+       \`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\`
+
+       Finding required fields:
+       - id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase)
+       - severity: lowercase only (critical|high|medium|low)
+       - snippet (NOT code_snippet), impact (NOT exploit_scenario)
+       - metadata, iteration (0), status (pending_remediation), cross_references
+
+    2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md
+       - Human-readable summary with recommendations
+       - Grouped by severity: critical → high → medium → low
+       - Include file:line references for all findings
+
+    3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt
+       - Raw CLI tool output for debugging
+       - Include full analysis text
+
+    ## Dimension-Specific Guidance
+    ${getDimensionGuidance(dimension)}
+
+    ## Success Criteria
+    - [ ] Schema obtained via cat review-dimension-results-schema.json
+    - [ ] All target files analyzed for ${dimension} concerns
+    - [ ] All findings include file:line references with code snippets
+    - [ ] Severity assessment follows established criteria (see reference)
+    - [ ] Recommendations are actionable with code examples
+    - [ ] JSON output follows schema exactly
+    - [ ] Report is comprehensive and well-organized
+  `
+)
+```
+
+**Deep-Dive Agent** (iteration execution):
+
+```javascript
+Task(
+  subagent_type="cli-explore-agent",
+  description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`,
+  prompt=`
+    ## Task Objective
+    Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue
+
+    ## Analysis Mode Selection
+    Use **Dependency Map mode** first to understand dependencies:
+    - Build dependency graph around ${file} to identify affected components
+    - Detect circular dependencies or tight coupling related to this finding
+    - Calculate change risk scores for remediation impact
+
+    Then apply **Deep Scan mode** for semantic analysis:
+    - Understand design intent and architectural context
+    - Identify non-standard patterns or implicit dependencies
+    - Extract remediation insights from code structure
+
+    ## Finding Context
+    - Finding ID: ${findingId}
+    - Original Dimension: ${dimension}
+    - Title: ${findingTitle}
+    - File: ${file}:${line}
+    - Severity: ${severity}
+    - Category: ${category}
+    - Original Description: ${description}
+    - Iteration: ${iteration}
+
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
+    1. Read original finding: ${dimensionJsonPath}
+    2. Read affected file: ${file}
+    3. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
+    4. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
+    5. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
+
+    ## CLI Configuration
+    - Tool Priority: gemini → qwen → codex
+    - Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
+    - Mode: analysis (READ-ONLY)
+
+    ## Expected Deliverables
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
+
+    1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
+
+       **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
+
+       Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
+
+       Required top-level fields:
+       - finding_id, dimension, iteration, analysis_timestamp
+       - cli_tool_used, model, analysis_duration_ms
+       - original_finding, root_cause, remediation_plan
+       - impact_assessment, reassessed_severity, confidence_score, cross_references
+
+       All nested objects must follow schema exactly - read schema for field names
+
+    2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md
+       - Detailed root cause analysis
+       - Step-by-step remediation plan
+       - Impact assessment and rollback strategy
+
+    ## Success Criteria
+    - [ ] Schema obtained via cat review-deep-dive-results-schema.json
+    - [ ] Root cause clearly identified with supporting evidence
+    - [ ] Remediation plan is step-by-step actionable with exact file:line references
+    - [ ] Each step includes specific commands and validation tests
+    - [ ] Impact fully assessed (files, tests, breaking changes, dependencies)
+    - [ ] Severity re-evaluation justified with evidence
+    - [ ] Confidence score accurately reflects certainty of analysis
+    - [ ] JSON output follows schema exactly
+    - [ ] References include project-specific and external documentation
+  `
+)
+```
+
+### Dimension Guidance Reference
+
+```javascript
+function getDimensionGuidance(dimension) {
+  const guidance = {
+    security: `
+      Focus Areas:
+      - Input validation and sanitization
+      - Authentication and authorization mechanisms
+      - Data encryption (at-rest and in-transit)
+      - SQL/NoSQL injection vulnerabilities
+      - XSS, CSRF, and other web vulnerabilities
+      - Sensitive data exposure
+      - Access control and privilege escalation
+
+      Severity Criteria:
+      - Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure
+      - High: Missing authorization checks, weak encryption, exposed secrets
+      - Medium: Missing input validation, insecure defaults, weak password policies
+      - Low: Security headers missing, verbose error messages, outdated dependencies
+    `,
+    architecture: `
+      Focus Areas:
+      - Layering and separation of concerns
+      - Coupling and cohesion
+      - Design pattern adherence
+      - Dependency management
+      - Scalability and extensibility
+      - Module boundaries
+      - API design consistency
+
+      Severity Criteria:
+      - Critical: Circular dependencies, god objects, tight coupling across layers
+      - High: Violated architectural principles, scalability bottlenecks
+      - Medium: Missing abstractions, inconsistent patterns, suboptimal design
+      - Low: Minor coupling issues, documentation gaps, naming inconsistencies
+    `,
+    quality: `
+      Focus Areas:
+      - Code duplication
+      - Complexity (cyclomatic, cognitive)
+      - Naming conventions
+      - Error handling patterns
+      - Code readability
+      - Comment quality
+      - Dead code
+
+      Severity Criteria:
+      - Critical: Severe complexity (CC > 20), massive duplication (>50 lines)
+      - High: High complexity (CC > 10), significant duplication, poor error handling
+      - Medium: Moderate complexity (CC > 5), naming issues, code smells
+      - Low: Minor duplication, documentation gaps, cosmetic issues
+    `,
+    'action-items': `
+      Focus Areas:
+      - Requirements coverage verification
+      - Acceptance criteria met
+      - Documentation completeness
+      - Deployment readiness
+      - Missing functionality
+      - Test coverage gaps
+      - Configuration management
+
+      Severity Criteria:
+      - Critical: Core requirements not met, deployment blockers
+      - High: Significant functionality missing, acceptance criteria not met
+      - Medium: Minor requirements gaps, documentation incomplete
+      - Low: Nice-to-have features missing, minor documentation gaps
+    `,
+    performance: `
+      Focus Areas:
+      - N+1 query problems
+      - Inefficient algorithms (O(n²) where O(n log n) possible)
+      - Memory leaks
+      - Blocking operations on main thread
+      - Missing caching opportunities
+      - Resource usage (CPU, memory, network)
+      - Database query optimization
+
+      Severity Criteria:
+      - Critical: Memory leaks, O(n²) in hot path, blocking main thread
+      - High: N+1 queries, missing indexes, inefficient algorithms
+      - Medium: Suboptimal caching, unnecessary computations, lazy loading issues
+      - Low: Minor optimization opportunities, redundant operations
+    `,
+    maintainability: `
+      Focus Areas:
+      - Technical debt indicators
+      - Magic numbers and hardcoded values
+      - Long methods (>50 lines)
+      - Large classes (>500 lines)
+      - Dead code and commented code
+      - Code documentation
+      - Test coverage
+
+      Severity Criteria:
+      - Critical: Massive methods (>200 lines), severe technical debt blocking changes
+      - High: Large methods (>100 lines), significant dead code, undocumented complex logic
+      - Medium: Magic numbers, moderate technical debt, missing tests
+      - Low: Minor refactoring opportunities, cosmetic improvements
+    `,
+    'best-practices': `
+      Focus Areas:
+      - Framework conventions adherence
+      - Language idioms
+      - Anti-patterns
+      - Deprecated API usage
+      - Coding standards compliance
+      - Error handling patterns
+      - Logging and monitoring
+
+      Severity Criteria:
+      - Critical: Severe anti-patterns, deprecated APIs with security risks
+      - High: Major convention violations, poor error handling, missing logging
+      - Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns
+      - Low: Cosmetic style issues, minor convention deviations
+    `
+  };
+
+  return guidance[dimension] || 'Standard code review analysis';
+}
+```
+
+### Completion Conditions
+
+**Full Success**:
+- All dimensions reviewed
+- Critical findings = 0
+- High findings ≤ 5
+- Action: Generate final report, mark phase=complete
+
+**Partial Success**:
+- All dimensions reviewed
+- Max iterations reached
+- Still have critical/high findings
+- Action: Generate report with warnings, recommend follow-up
+
+### Error Handling
+
+**Phase-Level Error Matrix**:
+
+| Phase | Error | Blocking? | Action |
+|-------|-------|-----------|--------|
+| Phase 1 | Invalid path pattern | Yes | Error and exit |
+| Phase 1 | No files matched | Yes | Error and exit |
+| Phase 1 | Files not readable | Yes | Error and exit |
+| Phase 2 | Single dimension fails | No | Log warning, continue other dimensions |
+| Phase 2 | All dimensions fail | Yes | Error and exit |
+| Phase 3 | Missing dimension JSON | No | Skip in aggregation, log warning |
+| Phase 4 | Deep-dive agent fails | No | Skip finding, continue others |
+| Phase 4 | Max iterations reached | No | Generate partial report |
+
+**CLI Fallback Chain**: Gemini → Qwen → Codex → degraded mode
+
+**Fallback Triggers**:
+1. HTTP 429, 5xx errors, connection timeout
+2. Invalid JSON output (parse error, missing required fields)
+3. Low confidence score < 0.4
+4. Analysis too brief (< 100 words in report)
+
+**Fallback Behavior**:
+- On trigger: Retry with next tool in chain
+- After Codex fails: Enter degraded mode (skip analysis, log error)
+- Degraded mode: Continue workflow with available results
+
+### TodoWrite Structure
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Initializing" },
+    { content: "Phase 2: Parallel Reviews (7 dimensions)", status: "in_progress", activeForm: "Reviewing" },
+    { content: "  → Security review", status: "in_progress", activeForm: "Analyzing security" },
+    // ... other dimensions as sub-items
+    { content: "Phase 3: Aggregation", status: "pending", activeForm: "Aggregating" },
+    { content: "Phase 4: Deep-dive", status: "pending", activeForm: "Deep-diving" },
+    { content: "Phase 5: Completion", status: "pending", activeForm: "Completing" }
+  ]
+});
+```
+
+## Best Practices
+
+1. **Start Specific**: Begin with focused module patterns for faster results
+2. **Expand Gradually**: Add more modules based on initial findings
+3. **Use Glob Wisely**: `src/auth/**` is more efficient than `src/**` with lots of irrelevant files
+4. **Trust Aggregation Logic**: Auto-selection based on proven heuristics
+5. **Monitor Logs**: Check reports/ directory for CLI analysis insights
+6. **Dashboard Polling**: Refresh every 5 seconds for real-time updates
+7. **Export Results**: Use dashboard export for external tracking tools
+
+## Related Commands
+
+### Automated Fix Workflow
+After completing a module review, use the dashboard to select findings and export them for automated fixing:
+
+```bash
+# Step 1: Complete review (this command)
+/workflow:review-module-cycle src/auth/**
+
+# Step 2: Open dashboard, select findings, and export
+# Dashboard generates: fix-export-{timestamp}.json
+
+# Step 3: Run automated fixes
+/workflow:review-fix .workflow/active/WFS-{session-id}/.review/fix-export-{timestamp}.json
+```
+
+See `/workflow:review-fix` for automated fixing with smart grouping, parallel execution, and test verification.
+

.claude/commands/workflow/review-session-cycle.md

@@ -0,0 +1,805 @@
+---
+name: review-session-cycle
+description: Session-based comprehensive multi-dimensional code review. Analyzes git changes from workflow session across 7 dimensions with hybrid parallel-iterative execution, aggregates findings, and performs focused deep-dives on critical issues until quality gates met.
+argument-hint: "[session-id] [--dimensions=security,architecture,...] [--max-iterations=N]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
+---
+
+# Workflow Review-Session-Cycle Command
+
+## Quick Start
+
+```bash
+# Execute comprehensive session review (all 7 dimensions)
+/workflow:review-session-cycle
+
+# Review specific session with custom dimensions
+/workflow:review-session-cycle WFS-payment-integration --dimensions=security,architecture,quality
+
+# Specify session and iteration limit
+/workflow:review-session-cycle WFS-payment-integration --max-iterations=5
+```
+
+**Review Scope**: Git changes from session creation to present (via `git log --since`)
+**Session Requirement**: Requires active or completed workflow session
+**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based)
+**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
+**Max Iterations**: 3 (adjustable via --max-iterations)
+**Default Iterations**: 1 (deep-dive runs once; use --max-iterations=0 to skip)
+**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
+
+## What & Why
+
+### Core Concept
+Session-based multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **git changes within a workflow session**.
+
+**Review Scope**:
+- **Session-based**: Reviews only files changed during the workflow session (via `git log --since="${sessionCreatedAt}"`)
+- **For independent module review**: Use `/workflow:review-module-cycle` command instead
+
+**vs Standard Review**:
+- **Standard**: Sequential manual reviews → Inconsistent coverage → Missed cross-cutting concerns
+- **Review-Session-Cycle**: **Parallel automated analysis → Aggregate findings → Deep-dive critical issues** → Comprehensive coverage
+
+### Value Proposition
+1. **Comprehensive Coverage**: 7 specialized dimensions analyze all quality aspects simultaneously
+2. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns
+3. **Actionable Insights**: Deep-dive iterations provide step-by-step remediation plans
+4. **Real-time Visibility**: JSON-based progress tracking with interactive HTML dashboard
+
+### Orchestrator Boundary (CRITICAL)
+- **ONLY command** for comprehensive multi-dimensional review
+- Manages: dimension coordination, aggregation, iteration control, progress tracking
+- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode
+- **⚠️ DASHBOARD CONSTRAINT**: Dashboard is generated ONCE during Phase 1 initialization. After initialization, orchestrator and agents MUST NOT read, write, or modify dashboard.html - it remains static for user interaction only.
+
+## How It Works
+
+### Execution Flow (Simplified)
+
+```
+Phase 1: Discovery & Initialization
+   └─ Validate session, initialize state, create output structure → Generate dashboard.html
+
+Phase 2: Parallel Reviews (for each dimension)
+   ├─ Launch 7 review agents simultaneously
+   ├─ Each executes CLI analysis via Gemini/Qwen
+   ├─ Generate dimension JSON + markdown reports
+   └─ Update review-progress.json
+
+Phase 3: Aggregation
+   ├─ Load all dimension JSON files
+   ├─ Calculate severity distribution (critical/high/medium/low)
+   ├─ Identify cross-cutting concerns (files in 3+ dimensions)
+   └─ Decision:
+      ├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate)
+      └─ Else → Phase 5 (Complete)
+
+Phase 4: Iterative Deep-Dive (optional)
+   ├─ Select critical findings (max 5 per iteration)
+   ├─ Launch deep-dive agents for root cause analysis
+   ├─ Generate remediation plans with impact assessment
+   ├─ Re-assess severity based on analysis
+   └─ Loop until no critical findings OR max iterations
+
+Phase 5: Completion
+   └─ Finalize review-progress.json → Output dashboard path
+```
+
+### Agent Roles
+
+| Agent | Responsibility |
+|-------|---------------|
+| **Orchestrator** | Phase control, session discovery, state management, aggregation logic, iteration control |
+| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports |
+| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment |
+
+## Enhanced Features
+
+### 1. Review Dimensions Configuration
+
+**7 Specialized Dimensions** with priority-based allocation:
+
+| Dimension | Template | Priority | Timeout |
+|-----------|----------|----------|---------|
+| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min |
+| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min |
+| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min |
+| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min |
+| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min |
+| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min |
+| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min |
+
+*Custom focus: "Assess technical debt and maintainability"
+
+**Category Definitions by Dimension**:
+
+```javascript
+const CATEGORIES = {
+  security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'],
+  architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'],
+  quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'],
+  'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'],
+  performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'],
+  maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'],
+  'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style']
+};
+```
+
+### 2. Aggregation Logic
+
+**Cross-Cutting Concern Detection**:
+1. Files appearing in 3+ dimensions = **Critical Files**
+2. Same issue pattern across dimensions = **Systemic Issue**
+3. Severity clustering in specific files = **Hotspots**
+
+**Deep-Dive Selection Criteria**:
+- All critical severity findings (priority 1)
+- Top 3 high-severity findings in critical files (priority 2)
+- Max 5 findings per iteration (prevent overwhelm)
+
+### 3. Severity Assessment
+
+**Severity Levels**:
+- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass
+- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt
+- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns
+- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues
+
+**Iteration Trigger**:
+- Critical findings > 0 OR
+- High findings > 5 OR
+- Critical files count > 0
+
+## Core Responsibilities
+
+### Orchestrator
+
+**Phase 1: Discovery & Initialization**
+
+**Step 1: Session Discovery**
+```javascript
+// If session ID not provided, auto-detect
+if (!providedSessionId) {
+  // Check for active sessions
+  const activeSessions = Glob('.workflow/active/WFS-*');
+  if (activeSessions.length === 1) {
+    sessionId = activeSessions[0].match(/WFS-[^/]+/)[0];
+  } else if (activeSessions.length > 1) {
+    // List sessions and prompt user
+    error("Multiple active sessions found. Please specify session ID.");
+  } else {
+    error("No active session found. Create session first with /workflow:session:start");
+  }
+} else {
+  sessionId = providedSessionId;
+}
+
+// Validate session exists
+Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`);
+```
+
+**Step 2: Session Validation**
+- Ensure session has implementation artifacts (check `.summaries/` or `.task/` directory)
+- Extract session creation timestamp from `workflow-session.json`
+- Use timestamp for git log filtering: `git log --since="${sessionCreatedAt}"`
+
+**Step 3: Changed Files Detection**
+```bash
+# Get files changed since session creation
+git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u
+```
+
+**Step 4: Output Directory Setup**
+- Output directory: `.workflow/active/${sessionId}/.review/`
+- Create directory structure:
+  ```bash
+  mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
+  ```
+
+**Step 5: Initialize Review State**
+- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations (merged metadata + state)
+- Progress tracking: Create `review-progress.json` for dashboard polling
+
+**Step 6: Dashboard Generation**
+
+**Constraints**:
+- **MANDATORY**: Dashboard MUST be generated from template: `~/.claude/templates/review-cycle-dashboard.html`
+- **PROHIBITED**: Direct creation or custom generation without template
+- **POST-GENERATION**: Orchestrator and agents MUST NOT read/write/modify dashboard.html after creation
+
+**Generation Commands** (3 independent steps):
+```bash
+# Step 1: Copy template to output location
+cp ~/.claude/templates/review-cycle-dashboard.html ${sessionDir}/.review/dashboard.html
+
+# Step 2: Replace SESSION_ID placeholder
+sed -i "s|{{SESSION_ID}}|${sessionId}|g" ${sessionDir}/.review/dashboard.html
+
+# Step 3: Replace REVIEW_TYPE placeholder
+sed -i "s|{{REVIEW_TYPE}}|session|g" ${sessionDir}/.review/dashboard.html
+
+# Step 4: Replace REVIEW_DIR placeholder
+sed -i "s|{{REVIEW_DIR}}|${reviewDir}|g" ${sessionDir}/.review/dashboard.html
+
+# Output: Start local server and output dashboard URL
+cd ${sessionDir}/.review && python -m http.server 8765 --bind 127.0.0.1 &
+echo "📊 Dashboard: http://127.0.0.1:8765/dashboard.html"
+echo "   (Press Ctrl+C to stop server when done)"
+```
+
+**Step 7: TodoWrite Initialization**
+- Set up progress tracking with hierarchical structure
+- Mark Phase 1 completed, Phase 2 in_progress
+
+**Phase 2: Parallel Review Coordination**
+- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode)
+- Pass dimension-specific context (template, timeout, custom focus)
+- Monitor completion via review-progress.json updates
+- TodoWrite updates: Mark dimensions as completed
+- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout)
+
+**Phase 3: Aggregation**
+- Load all dimension JSON files from dimensions/
+- Calculate severity distribution: Count by critical/high/medium/low
+- Identify cross-cutting concerns: Files in 3+ dimensions
+- Select deep-dive findings: Critical + high in critical files (max 5)
+- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist
+- Update review-state.json with aggregation results
+
+**Phase 4: Iteration Control**
+- Check iteration count < max_iterations (default 3)
+- Launch deep-dive agents for selected findings
+- Collect remediation plans and re-assessed severities
+- Update severity distribution based on re-assessments
+- Record iteration in review-state.json
+- Loop back to aggregation if still have critical/high findings
+
+**Phase 5: Completion**
+- Finalize review-progress.json with completion statistics
+- Update review-state.json with completion_time and phase=complete
+- TodoWrite completion: Mark all tasks done
+- Output: Dashboard path to user
+
+
+
+### Session File Structure
+
+```
+.workflow/active/WFS-{session-id}/.review/
+├── review-state.json                    # Orchestrator state machine (includes metadata)
+├── review-progress.json                 # Real-time progress for dashboard
+├── dimensions/                          # Per-dimension results
+│   ├── security.json
+│   ├── architecture.json
+│   ├── quality.json
+│   ├── action-items.json
+│   ├── performance.json
+│   ├── maintainability.json
+│   └── best-practices.json
+├── iterations/                          # Deep-dive results
+│   ├── iteration-1-finding-{uuid}.json
+│   └── iteration-2-finding-{uuid}.json
+├── reports/                             # Human-readable reports
+│   ├── security-analysis.md
+│   ├── security-cli-output.txt
+│   ├── deep-dive-1-{uuid}.md
+│   └── ...
+└── dashboard.html                       # Interactive dashboard (primary output)
+```
+
+**Session Context**:
+```
+.workflow/active/WFS-{session-id}/
+├── workflow-session.json
+├── IMPL_PLAN.md
+├── TODO_LIST.md
+├── .task/
+├── .summaries/
+└── .review/                             # Review results (this command)
+    └── (structure above)
+```
+
+### Review State JSON
+
+**Purpose**: Unified state machine and metadata (merged from metadata + state)
+
+```json
+{
+  "session_id": "WFS-payment-integration",
+  "review_id": "review-20250125-143022",
+  "review_type": "session",
+  "metadata": {
+    "created_at": "2025-01-25T14:30:22Z",
+    "git_changes": {
+      "commit_range": "abc123..def456",
+      "files_changed": 15,
+      "insertions": 342,
+      "deletions": 128
+    },
+    "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
+    "max_iterations": 3
+  },
+  "phase": "parallel|aggregate|iterate|complete",
+  "current_iteration": 1,
+  "dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
+  "selected_strategy": "comprehensive",
+  "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete",
+  "severity_distribution": {
+    "critical": 2,
+    "high": 5,
+    "medium": 12,
+    "low": 8
+  },
+  "critical_files": [
+    {
+      "file": "src/payment/processor.ts",
+      "finding_count": 5,
+      "dimensions": ["security", "architecture", "quality"]
+    }
+  ],
+  "iterations": [
+    {
+      "iteration": 1,
+      "findings_analyzed": ["uuid-1", "uuid-2"],
+      "findings_resolved": 1,
+      "findings_escalated": 1,
+      "severity_change": {
+        "before": {"critical": 2, "high": 5, "medium": 12, "low": 8},
+        "after": {"critical": 1, "high": 6, "medium": 12, "low": 8}
+      },
+      "timestamp": "2025-01-25T14:30:00Z"
+    }
+  ],
+  "completion_criteria": {
+    "target": "no_critical_findings_and_high_under_5",
+    "current_status": "in_progress",
+    "estimated_completion": "2 iterations remaining"
+  }
+}
+```
+
+**Field Descriptions**:
+- `phase`: Current execution phase (state machine pointer)
+- `current_iteration`: Iteration counter (used for max check)
+- `next_action`: Next step orchestrator should execute
+- `severity_distribution`: Aggregated counts across all dimensions
+- `critical_files`: Files appearing in 3+ dimensions with metadata
+- `iterations[]`: Historical log for trend analysis
+
+### Review Progress JSON
+
+**Purpose**: Real-time dashboard updates via polling
+
+```json
+{
+  "review_id": "review-20250125-143022",
+  "last_update": "2025-01-25T14:35:10Z",
+  "phase": "parallel|aggregate|iterate|complete",
+  "current_iteration": 1,
+  "progress": {
+    "parallel_review": {
+      "total_dimensions": 7,
+      "completed": 5,
+      "in_progress": 2,
+      "percent_complete": 71
+    },
+    "deep_dive": {
+      "total_findings": 6,
+      "analyzed": 2,
+      "in_progress": 1,
+      "percent_complete": 33
+    }
+  },
+  "agent_status": [
+    {
+      "agent_type": "review-agent",
+      "dimension": "security",
+      "status": "completed",
+      "started_at": "2025-01-25T14:30:00Z",
+      "completed_at": "2025-01-25T15:15:00Z",
+      "duration_ms": 2700000
+    },
+    {
+      "agent_type": "deep-dive-agent",
+      "finding_id": "sec-001-uuid",
+      "status": "in_progress",
+      "started_at": "2025-01-25T14:32:00Z"
+    }
+  ],
+  "estimated_completion": "2025-01-25T16:00:00Z"
+}
+```
+
+### Agent Output Schemas
+
+**Agent-produced JSON files follow standardized schemas**:
+
+1. **Dimension Results** (cli-explore-agent output from parallel reviews)
+   - Schema: `~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json`
+   - Output: `.review-cycle/dimensions/{dimension}.json`
+   - Contains: findings array, summary statistics, cross_references
+
+2. **Deep-Dive Results** (cli-explore-agent output from iterations)
+   - Schema: `~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json`
+   - Output: `.review-cycle/iterations/iteration-{N}-finding-{uuid}.json`
+   - Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity
+
+### Agent Invocation Template
+
+**Review Agent** (parallel execution, 7 instances):
+
+```javascript
+Task(
+  subagent_type="cli-explore-agent",
+  description=`Execute ${dimension} review analysis via Deep Scan`,
+  prompt=`
+    ## Task Objective
+    Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for completed implementation in session ${sessionId}
+
+    ## Analysis Mode Selection
+    Use **Deep Scan mode** for this review:
+    - Phase 1: Bash structural scan for standard patterns (classes, functions, imports)
+    - Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns
+    - Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings)
+
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
+    1. Read session metadata: ${sessionMetadataPath}
+    2. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f)
+    3. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
+    4. Read review state: ${reviewStateJsonPath}
+    5. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
+
+    ## Session Context
+    - Session ID: ${sessionId}
+    - Review Dimension: ${dimension}
+    - Review ID: ${reviewId}
+    - Implementation Phase: Complete (all tests passing)
+    - Output Directory: ${outputDir}
+
+    ## CLI Configuration
+    - Tool Priority: gemini → qwen → codex (fallback chain)
+    - Template: ~/.claude/workflows/cli-templates/prompts/analysis/${dimensionTemplate}
+    - Custom Focus: ${customFocus || 'Standard dimension analysis'}
+    - Timeout: ${timeout}ms
+    - Mode: analysis (READ-ONLY)
+
+    ## Expected Deliverables
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
+
+    1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
+
+       **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
+
+       Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
+
+       Required top-level fields:
+       - dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at)
+       - cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms
+       - summary (FLAT structure), findings, cross_references
+
+       Summary MUST be FLAT (NOT nested by_severity):
+       \`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\`
+
+       Finding required fields:
+       - id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase)
+       - severity: lowercase only (critical|high|medium|low)
+       - snippet (NOT code_snippet), impact (NOT exploit_scenario)
+       - metadata, iteration (0), status (pending_remediation), cross_references
+
+    2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md
+       - Human-readable summary with recommendations
+       - Grouped by severity: critical → high → medium → low
+       - Include file:line references for all findings
+
+    3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt
+       - Raw CLI tool output for debugging
+       - Include full analysis text
+
+    ## Dimension-Specific Guidance
+    ${getDimensionGuidance(dimension)}
+
+    ## Success Criteria
+    - [ ] Schema obtained via cat review-dimension-results-schema.json
+    - [ ] All changed files analyzed for ${dimension} concerns
+    - [ ] All findings include file:line references with code snippets
+    - [ ] Severity assessment follows established criteria (see reference)
+    - [ ] Recommendations are actionable with code examples
+    - [ ] JSON output follows schema exactly
+    - [ ] Report is comprehensive and well-organized
+  `
+)
+```
+
+**Deep-Dive Agent** (iteration execution):
+
+```javascript
+Task(
+  subagent_type="cli-explore-agent",
+  description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`,
+  prompt=`
+    ## Task Objective
+    Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue
+
+    ## Analysis Mode Selection
+    Use **Dependency Map mode** first to understand dependencies:
+    - Build dependency graph around ${file} to identify affected components
+    - Detect circular dependencies or tight coupling related to this finding
+    - Calculate change risk scores for remediation impact
+
+    Then apply **Deep Scan mode** for semantic analysis:
+    - Understand design intent and architectural context
+    - Identify non-standard patterns or implicit dependencies
+    - Extract remediation insights from code structure
+
+    ## Finding Context
+    - Finding ID: ${findingId}
+    - Original Dimension: ${dimension}
+    - Title: ${findingTitle}
+    - File: ${file}:${line}
+    - Severity: ${severity}
+    - Category: ${category}
+    - Original Description: ${description}
+    - Iteration: ${iteration}
+
+    ## MANDATORY FIRST STEPS (Execute by Agent)
+    **You (cli-explore-agent) MUST execute these steps in order:**
+    1. Read original finding: ${dimensionJsonPath}
+    2. Read affected file: ${file}
+    3. Identify related code: bash(grep -r "import.*${basename(file)}" ${workflowDir}/src --include="*.ts")
+    4. Read test files: bash(find ${workflowDir}/tests -name "*${basename(file, '.ts')}*" -type f)
+    5. Execute: cat ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
+
+    ## CLI Configuration
+    - Tool Priority: gemini → qwen → codex
+    - Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
+    - Timeout: 2400000ms (40 minutes)
+    - Mode: analysis (READ-ONLY)
+
+    ## Expected Deliverables
+
+    **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
+
+    1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
+
+       **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
+
+       Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
+
+       Required top-level fields:
+       - finding_id, dimension, iteration, analysis_timestamp
+       - cli_tool_used, model, analysis_duration_ms
+       - original_finding, root_cause, remediation_plan
+       - impact_assessment, reassessed_severity, confidence_score, cross_references
+
+       All nested objects must follow schema exactly - read schema for field names
+
+    2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md
+       - Detailed root cause analysis
+       - Step-by-step remediation plan
+       - Impact assessment and rollback strategy
+
+    ## Success Criteria
+    - [ ] Schema obtained via cat review-deep-dive-results-schema.json
+    - [ ] Root cause clearly identified with supporting evidence
+    - [ ] Remediation plan is step-by-step actionable with exact file:line references
+    - [ ] Each step includes specific commands and validation tests
+    - [ ] Impact fully assessed (files, tests, breaking changes, dependencies)
+    - [ ] Severity re-evaluation justified with evidence
+    - [ ] Confidence score accurately reflects certainty of analysis
+    - [ ] JSON output follows schema exactly
+    - [ ] References include project-specific and external documentation
+  `
+)
+```
+
+### Dimension Guidance Reference
+
+```javascript
+function getDimensionGuidance(dimension) {
+  const guidance = {
+    security: `
+      Focus Areas:
+      - Input validation and sanitization
+      - Authentication and authorization mechanisms
+      - Data encryption (at-rest and in-transit)
+      - SQL/NoSQL injection vulnerabilities
+      - XSS, CSRF, and other web vulnerabilities
+      - Sensitive data exposure
+      - Access control and privilege escalation
+
+      Severity Criteria:
+      - Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure
+      - High: Missing authorization checks, weak encryption, exposed secrets
+      - Medium: Missing input validation, insecure defaults, weak password policies
+      - Low: Security headers missing, verbose error messages, outdated dependencies
+    `,
+    architecture: `
+      Focus Areas:
+      - Layering and separation of concerns
+      - Coupling and cohesion
+      - Design pattern adherence
+      - Dependency management
+      - Scalability and extensibility
+      - Module boundaries
+      - API design consistency
+
+      Severity Criteria:
+      - Critical: Circular dependencies, god objects, tight coupling across layers
+      - High: Violated architectural principles, scalability bottlenecks
+      - Medium: Missing abstractions, inconsistent patterns, suboptimal design
+      - Low: Minor coupling issues, documentation gaps, naming inconsistencies
+    `,
+    quality: `
+      Focus Areas:
+      - Code duplication
+      - Complexity (cyclomatic, cognitive)
+      - Naming conventions
+      - Error handling patterns
+      - Code readability
+      - Comment quality
+      - Dead code
+
+      Severity Criteria:
+      - Critical: Severe complexity (CC > 20), massive duplication (>50 lines)
+      - High: High complexity (CC > 10), significant duplication, poor error handling
+      - Medium: Moderate complexity (CC > 5), naming issues, code smells
+      - Low: Minor duplication, documentation gaps, cosmetic issues
+    `,
+    'action-items': `
+      Focus Areas:
+      - Requirements coverage verification
+      - Acceptance criteria met
+      - Documentation completeness
+      - Deployment readiness
+      - Missing functionality
+      - Test coverage gaps
+      - Configuration management
+
+      Severity Criteria:
+      - Critical: Core requirements not met, deployment blockers
+      - High: Significant functionality missing, acceptance criteria not met
+      - Medium: Minor requirements gaps, documentation incomplete
+      - Low: Nice-to-have features missing, minor documentation gaps
+    `,
+    performance: `
+      Focus Areas:
+      - N+1 query problems
+      - Inefficient algorithms (O(n²) where O(n log n) possible)
+      - Memory leaks
+      - Blocking operations on main thread
+      - Missing caching opportunities
+      - Resource usage (CPU, memory, network)
+      - Database query optimization
+
+      Severity Criteria:
+      - Critical: Memory leaks, O(n²) in hot path, blocking main thread
+      - High: N+1 queries, missing indexes, inefficient algorithms
+      - Medium: Suboptimal caching, unnecessary computations, lazy loading issues
+      - Low: Minor optimization opportunities, redundant operations
+    `,
+    maintainability: `
+      Focus Areas:
+      - Technical debt indicators
+      - Magic numbers and hardcoded values
+      - Long methods (>50 lines)
+      - Large classes (>500 lines)
+      - Dead code and commented code
+      - Code documentation
+      - Test coverage
+
+      Severity Criteria:
+      - Critical: Massive methods (>200 lines), severe technical debt blocking changes
+      - High: Large methods (>100 lines), significant dead code, undocumented complex logic
+      - Medium: Magic numbers, moderate technical debt, missing tests
+      - Low: Minor refactoring opportunities, cosmetic improvements
+    `,
+    'best-practices': `
+      Focus Areas:
+      - Framework conventions adherence
+      - Language idioms
+      - Anti-patterns
+      - Deprecated API usage
+      - Coding standards compliance
+      - Error handling patterns
+      - Logging and monitoring
+
+      Severity Criteria:
+      - Critical: Severe anti-patterns, deprecated APIs with security risks
+      - High: Major convention violations, poor error handling, missing logging
+      - Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns
+      - Low: Cosmetic style issues, minor convention deviations
+    `
+  };
+
+  return guidance[dimension] || 'Standard code review analysis';
+}
+```
+
+### Completion Conditions
+
+**Full Success**:
+- All dimensions reviewed
+- Critical findings = 0
+- High findings ≤ 5
+- Action: Generate final report, mark phase=complete
+
+**Partial Success**:
+- All dimensions reviewed
+- Max iterations reached
+- Still have critical/high findings
+- Action: Generate report with warnings, recommend follow-up
+
+### Error Handling
+
+**Phase-Level Error Matrix**:
+
+| Phase | Error | Blocking? | Action |
+|-------|-------|-----------|--------|
+| Phase 1 | Session not found | Yes | Error and exit |
+| Phase 1 | No completed tasks | Yes | Error and exit |
+| Phase 1 | No changed files | Yes | Error and exit |
+| Phase 2 | Single dimension fails | No | Log warning, continue other dimensions |
+| Phase 2 | All dimensions fail | Yes | Error and exit |
+| Phase 3 | Missing dimension JSON | No | Skip in aggregation, log warning |
+| Phase 4 | Deep-dive agent fails | No | Skip finding, continue others |
+| Phase 4 | Max iterations reached | No | Generate partial report |
+
+**CLI Fallback Chain**: Gemini → Qwen → Codex → degraded mode
+
+**Fallback Triggers**:
+1. HTTP 429, 5xx errors, connection timeout
+2. Invalid JSON output (parse error, missing required fields)
+3. Low confidence score < 0.4
+4. Analysis too brief (< 100 words in report)
+
+**Fallback Behavior**:
+- On trigger: Retry with next tool in chain
+- After Codex fails: Enter degraded mode (skip analysis, log error)
+- Degraded mode: Continue workflow with available results
+
+### TodoWrite Structure
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Initializing" },
+    { content: "Phase 2: Parallel Reviews (7 dimensions)", status: "in_progress", activeForm: "Reviewing" },
+    { content: "  → Security review", status: "in_progress", activeForm: "Analyzing security" },
+    // ... other dimensions as sub-items
+    { content: "Phase 3: Aggregation", status: "pending", activeForm: "Aggregating" },
+    { content: "Phase 4: Deep-dive", status: "pending", activeForm: "Deep-diving" },
+    { content: "Phase 5: Completion", status: "pending", activeForm: "Completing" }
+  ]
+});
+```
+
+## Best Practices
+
+1. **Default Settings Work**: 7 dimensions + 3 iterations sufficient for most cases
+2. **Parallel Execution**: ~60 minutes for full initial review (7 dimensions)
+3. **Trust Aggregation Logic**: Auto-selection based on proven heuristics
+4. **Monitor Logs**: Check reports/ directory for CLI analysis insights
+5. **Dashboard Polling**: Refresh every 5 seconds for real-time updates
+6. **Export Results**: Use dashboard export for external tracking tools
+
+## Related Commands
+
+### Automated Fix Workflow
+After completing a review, use the dashboard to select findings and export them for automated fixing:
+
+```bash
+# Step 1: Complete review (this command)
+/workflow:review-session-cycle
+
+# Step 2: Open dashboard, select findings, and export
+# Dashboard generates: fix-export-{timestamp}.json
+
+# Step 3: Run automated fixes
+/workflow:review-fix .workflow/active/WFS-{session-id}/.review/fix-export-{timestamp}.json
+```
+
+See `/workflow:review-fix` for automated fixing with smart grouping, parallel execution, and test verification.
+

.claude/commands/workflow/review.md

@@ -29,6 +29,39 @@ argument-hint: "[--type=security|architecture|action-items|quality] [optional: s
 - For documentation generation, use `/workflow:tools:docs`
 - For CLAUDE.md updates, use `/update-memory-related`
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse --type flag (default: quality)
+   └─ Parse session-id argument (optional)
+
+Step 1: Session Resolution
+   └─ Decision:
+      ├─ session-id provided → Use provided session
+      └─ Not provided → Auto-detect from .workflow/active/
+
+Step 2: Validation
+   ├─ Check session directory exists
+   └─ Check for completed implementation (.summaries/IMPL-*.md exists)
+
+Step 3: Type Check
+   └─ Decision:
+      ├─ type=docs → Redirect to /workflow:tools:docs
+      └─ Other types → Continue to analysis
+
+Step 4: Model Analysis Phase
+   ├─ Load context (summaries, test results, changed files)
+   └─ Perform specialized review by type:
+      ├─ security → Security patterns + Gemini analysis
+      ├─ architecture → Qwen architecture analysis
+      ├─ quality → Gemini code quality analysis
+      └─ action-items → Requirements verification
+
+Step 5: Generate Report
+   └─ Output: REVIEW-{type}.md
+```
+
 ## Execution Template
 
 ```bash
@@ -39,17 +72,17 @@ 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
+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
+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
@@ -80,13 +113,13 @@ 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 +132,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 +144,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 +156,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 +169,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 +228,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

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

@@ -19,129 +19,482 @@ Mark the currently active workflow session as complete, analyze it for lessons l
 
 ## Implementation Flow
 
-### Phase 1: Prepare for Archival (Minimal Manual Operations)
+### Phase 1: Pre-Archival Preparation (Transactional Setup)
 
-**Purpose**: Find active session, move to archive location, pass control to agent. Minimal operations.
+**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
-# Find active marker
-bash(find .workflow/ -name ".active-*" -type f | head -1)
+# Find active session directory
+bash(find .workflow/active/ -name "WFS-*" -type d | head -1)
 
-# Extract session name from marker path
-bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+# Extract session name from directory path
+bash(basename .workflow/active/WFS-session-name)
 ```
 **Output**: Session name `WFS-session-name`
 
-#### Step 1.2: Move Session to Archive
+#### Step 1.2: Check for Existing Archiving Marker (Resume Detection)
 ```bash
-# Create archive directory if needed
-bash(mkdir -p .workflow/.archives/)
-
-# Move session to archive location
-bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+# Check if session is already being archived
+bash(test -f .workflow/active/WFS-session-name/.archiving && echo "RESUMING" || echo "NEW")
 ```
-**Result**: Session now at `.workflow/.archives/WFS-session-name/`
 
-### Phase 2: Agent-Orchestrated Completion (All Data Processing)
+**If RESUMING**:
+- Previous archival attempt was interrupted
+- Skip to Phase 2 to resume agent analysis
 
-**Purpose**: Agent analyzes archived session, generates metadata, updates manifest, and removes active marker.
+**If NEW**:
+- Continue to Step 1.3
+
+#### Step 1.3: Create Archiving Marker
+```bash
+# 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 complete the archival process.
+Invoke `universal-executor` agent to analyze session and prepare archive metadata.
 
 **Agent Task**:
 ```
 Task(
   subagent_type="universal-executor",
-  description="Complete session archival",
+  description="Analyze session for archival",
   prompt=`
-Complete workflow session archival. Session already moved to archive location.
+Analyze workflow session for archival preparation. Session is STILL in active location.
 
 ## Context
-- Session: .workflow/.archives/WFS-session-name/
-- Active marker: .workflow/.active-WFS-session-name
+- 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/timestamp, completed_at, status)
+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 (fallback: analyze files directly)
+3. **Extract review data** (if .review/ exists):
+   - Count dimension results: .review/dimensions/*.json
+   - Count deep-dive results: .review/iterations/*.json
+   - Extract findings summary from dimension JSONs (total, critical, high, medium, low)
+   - Check fix results if .review/fixes/ exists (fixed_count, failed_count)
+   - Build review_metrics: {dimensions_analyzed, total_findings, severity_distribution, fix_success_rate}
+
+4. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt
    - Return: {successes, challenges, watch_patterns}
+   - If review data exists, include review-specific lessons (common issue patterns, effective fixes)
 
-4. **Build archive entry**:
+5. **Build archive entry**:
    - Calculate: duration_hours, success_rate, tags (3-5 keywords)
-   - Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons
+   - Construct complete JSON with session_id, description, archived_at, metrics, tags, lessons
+   - Include archive_path: ".workflow/archives/WFS-session-name" (future location)
+   - If review data exists, include review_metrics in metrics object
 
-5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
+6. **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. **Remove active marker**
+7. **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": {
+         "duration_hours": 2.5,
+         "tasks_completed": 5,
+         "summaries_generated": 3,
+         "review_metrics": {                    // Optional, only if .review/ exists
+           "dimensions_analyzed": 4,
+           "total_findings": 15,
+           "severity_distribution": {"critical": 1, "high": 3, "medium": 8, "low": 3},
+           "fix_success_rate": 0.87             // Optional, only if .review/fixes/ exists
+         }
+       },
+       "tags": [...],
+       "lessons": {...}
+     },
+     "feature_metadata": {
+       "title": "...",
+       "description": "...",
+       "tags": [...]
+     }
+   }
 
-7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
+## 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 remove marker if failed
+- Do NOT modify any files on error
   `
 )
 ```
 
 **Expected Output**:
-- Agent returns JSON result confirming successful archival
-- Display completion summary to user based on agent response
+- 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
+bash(mkdir -p .workflow/archives/)
+```
+
+#### Step 3.2: Move Session to Archive
+```bash
+bash(mv .workflow/active/WFS-session-name .workflow/archives/WFS-session-name)
+```
+**Result**: Session now at `.workflow/archives/WFS-session-name/`
+
+#### Step 3.3: Update Manifest
+```bash
+# Read current manifest (or create empty array if not exists)
+bash(test -f .workflow/archives/manifest.json && cat .workflow/archives/manifest.json || echo "[]")
+```
+
+**JSON Update Logic**:
+```javascript
+// Read agent result from Phase 2
+const agentResult = JSON.parse(agentOutput);
+const archiveEntry = agentResult.archive_entry;
+
+// Read existing manifest
+let manifest = [];
+try {
+  const manifestContent = Read('.workflow/archives/manifest.json');
+  manifest = JSON.parse(manifestContent);
+} catch {
+  manifest = []; // Initialize if not exists
+}
+
+// Append new entry
+manifest.push(archiveEntry);
+
+// Write back
+Write('.workflow/archives/manifest.json', JSON.stringify(manifest, null, 2));
+```
+
+#### Step 3.4: Remove Archiving Marker
+```bash
+bash(rm .workflow/archives/WFS-session-name/.archiving)
+```
+**Result**: Clean archived session without temporary markers
+
+**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
+  ${reviewMetrics ? `Review: ${reviewMetrics.total_findings} findings across ${reviewMetrics.dimensions_analyzed} dimensions, ${Math.round(reviewMetrics.fix_success_rate * 100)}% fixed` : ''}
+```
+
+### 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
 
-### Two-Phase Approach (Optimized)
+### Transactional Four-Phase Approach
 
-**Phase 1: Minimal Manual Setup** (2 simple operations)
+**Phase 1: Pre-Archival Preparation** (Marker creation)
 - Find active session and extract name
-- Move session to archive location
-- **No data extraction** - agent handles all data processing
-- **No counting** - agent does this from archive location
-- **Total**: 2 bash commands (find + move)
+- 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-Driven Completion** (1 agent invocation)
-- Extract all session data from archived location
+**Phase 2: Agent Analysis** (Read-only data processing)
+- Extract all session data from active location
 - Count tasks and summaries
-- Generate lessons learned analysis
-- Build complete archive metadata
-- Update manifest
-- Remove active marker
-- Return success/error result
+- Extract review data if .review/ exists (dimension results, findings, fix results)
+- Generate lessons learned analysis (including review-specific lessons if applicable)
+- Extract feature metadata from IMPL_PLAN.md
+- Build complete archive + feature metadata package (with review_metrics if applicable)
+- **No file modifications** - pure analysis
+- **Total**: 1 agent invocation
 
-## Quick Commands
+**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
 
-```bash
-# Phase 1: Find and move
-bash(find .workflow/ -name ".active-*" -type f | head -1)
-bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
-bash(mkdir -p .workflow/.archives/)
-bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+**Phase 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
 
-# Phase 2: Agent completes archival
-Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`)
-```
+### Transactional Guarantees
 
-## Archive Query Commands
+**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
 
-After archival, you can query the manifest:
+**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
 
-```bash
-# List all archived sessions
-jq '.archives[].session_id' .workflow/.archives/manifest.json
+**Resume Capability**:
+- Detect interrupted archival via `.archiving` marker
+- Resume from Phase 2 (skip marker creation)
+- Idempotent operations (safe to retry)
 
-# Find sessions by keyword
-jq '.archives[] | select(.description | test("auth"; "i"))' .workflow/.archives/manifest.json
-
-# Get specific session details
-jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/manifest.json
-
-# List all watch patterns across sessions
-jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json
-```
 

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

@@ -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`
@@ -89,11 +89,8 @@ Total: 3 sessions (1 active, 1 paused, 1 completed)
 ### 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
+ls -t .workflow/active/WFS-*/workflow-session.json | head -3
 ```

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

@@ -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
 ```

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

@@ -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,29 +131,27 @@ 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`
 
+## Execution Guideline
+
+- **Non-interrupting**: When called from other commands, this command completes and returns control to the caller without interrupting subsequent tasks.
+
 ## Output Format Specification
 
 ### Success
@@ -153,60 +172,6 @@ DECISION: Reusing existing session
 SESSION_ID: WFS-promptmaster-platform
 ```
 
-## Command Integration
-
-### For /workflow:plan (Use Auto Mode)
-```bash
-SlashCommand(command="/workflow:session:start --auto \"implement OAuth2 authentication\"")
-
-# Parse session ID from output
-grep "^SESSION_ID:" | awk '{print $2}'
-```
-
-### For Interactive Workflows (Use Discovery Mode)
-```bash
-SlashCommand(command="/workflow:session:start")
-```
-
-### For New Isolated Work (Use Force New Mode)
-```bash
-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]`

.claude/commands/workflow/status.md

@@ -1,47 +1,214 @@
 ---
 name: workflow:status
-description: Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view
-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
+```
+
+## Execution Process
+
+```
+Input Parsing:
+   └─ Decision (mode detection):
+      ├─ --project flag → Project Overview Mode
+      ├─ --dashboard flag → Dashboard Mode
+      ├─ task-id argument → Task Details Mode
+      └─ No flags → Workflow Session Mode (default)
+
+Project Overview Mode:
+   ├─ Check project.json exists
+   ├─ Read project data
+   ├─ Parse and display overview + features
+   └─ Show recent archived sessions
+
+Workflow Session Mode (default):
+   ├─ Find active session
+   ├─ Load session data
+   ├─ Scan task files
+   └─ Display task progress
+
+Dashboard Mode:
+   ├─ Collect active sessions
+   ├─ Collect archived sessions
+   ├─ Generate HTML from template
+   └─ Write dashboard.html
 ```
 
 ## 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
@@ -58,62 +225,133 @@ find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 - [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
+### 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
+  });
 ```
-Session file valid
-8 task files found
-3 summaries found
-5 tasks pending completion
+
+### 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

@@ -70,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
@@ -91,26 +91,23 @@ 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: 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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "in_progress", "activeForm": "Executing test coverage analysis"},
+  {"content": "  → Detect test framework and conventions", "status": "in_progress", "activeForm": "Detecting test framework"},
+  {"content": "  → Analyze existing test coverage", "status": "pending", "activeForm": "Analyzing test coverage"},
+  {"content": "  → Identify coverage gaps", "status": "pending", "activeForm": "Identifying coverage gaps"},
+  {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
 ]
 ```
 
@@ -123,11 +120,11 @@ TEST_FOCUS: [Test scenarios]
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
 ]
 ```
 
@@ -153,7 +150,7 @@ 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
@@ -164,14 +161,15 @@ TEST_FOCUS: [Test scenarios]
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 4: Conflict Resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
+  {"content": "  → Detect conflicts with CLI analysis", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "  → Present conflicts to user", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "  → Apply resolution strategies", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
 ]
 ```
 
@@ -184,12 +182,12 @@ TEST_FOCUS: [Test scenarios]
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 4: Conflict Resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
 ]
 ```
 
@@ -230,13 +228,14 @@ TEST_FOCUS: [Test scenarios]
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 5: TDD Task Generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
+  {"content": "  → Discovery - analyze TDD requirements", "status": "in_progress", "activeForm": "Analyzing TDD requirements"},
+  {"content": "  → Planning - design Red-Green-Refactor cycles", "status": "pending", "activeForm": "Designing TDD cycles"},
+  {"content": "  → Output - generate IMPL tasks with internal TDD phases", "status": "pending", "activeForm": "Generating TDD tasks"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
 ]
 ```
 
@@ -249,11 +248,11 @@ TEST_FOCUS: [Test scenarios]
 **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"}
+  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 5: TDD Task Generation", "status": "completed", "activeForm": "Executing TDD task generation"},
+  {"content": "Phase 6: TDD Structure Validation", "status": "in_progress", "activeForm": "Validating TDD structure"}
 ]
 ```
 
@@ -296,9 +295,9 @@ Structure:
 [...]
 
 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:
@@ -345,12 +344,7 @@ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task
 - **Phase 5**: Generated IMPL tasks contain internal Red-Green-Refactor cycles
 - **Conditional Phase 4**: Conflict resolution only if conflict_risk ≥ medium
 
-### Benefits
 
-- ✓ Real-time visibility into TDD workflow execution
-- ✓ Clear mental model: SlashCommand = attach → execute → collapse
-- ✓ Test-aware planning with coverage analysis
-- ✓ Self-contained TDD cycles within each IMPL task
 
 **Note**: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures.
 
@@ -417,110 +411,6 @@ Convert user input to TDD-structured format:
 - **Command failure**: Keep phase in_progress, report error
 - **TDD validation failure**: Report incomplete chains or wrong dependencies
 
-## TDD Workflow Enhancements
-
-### Overview
-The TDD workflow has been significantly enhanced by integrating best practices from both traditional `plan --agent` and `test-gen` workflows, creating a hybrid approach that bridges the gap between idealized TDD and real-world development complexity.
-
-### Key Improvements
-
-#### 1. Test Coverage Analysis (Phase 3)
-**Adopted from test-gen workflow**
-
-Before planning TDD tasks, the workflow now analyzes the existing codebase:
-- Detects existing test patterns and conventions
-- Identifies current test coverage
-- Discovers related components and integration points
-- Detects test framework automatically
-
-**Benefits**:
-- Context-aware TDD planning
-- Avoids duplicate test creation
-- Enables integration with existing tests
-- No longer assumes greenfield scenarios
-
-#### 2. Iterative Green Phase with Test-Fix Cycle
-**Adopted from test-gen workflow**
-
-IMPL (Green phase) tasks now include automatic test-fix cycle for resilient implementation:
-
-**Enhanced IMPL Task Flow**:
-```
-1. Write minimal implementation code
-2. Execute test suite
-3. IF tests pass → Complete task
-4. IF tests fail → Enter fix cycle:
-   a. Gemini diagnoses with bug-fix template
-   b. Apply fix (manual or Codex)
-   c. Retest
-   d. Repeat (max 3 iterations)
-5. IF max iterations → Auto-revert changes 🔄
-```
-
-**Benefits**:
-- Faster feedback within Green phase
-- Autonomous recovery from implementation errors
-- Systematic debugging with Gemini
-- Safe rollback prevents broken state
-
-#### 3. Agent-Driven Planning
-**From plan --agent workflow**
-
-Supports action-planning-agent for more autonomous TDD planning with:
-- MCP tool integration (code-index, exa)
-- Memory-first principles
-- Brainstorming artifact integration
-- Task merging over decomposition
-
-### Workflow Comparison
-
-| Aspect | Previous | Current (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)
-
 ## Related Commands
 
 **Prerequisite Commands**:

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

@@ -18,6 +18,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
 - Validate TDD cycle execution
 - Generate compliance report
 
+## Execution Process
+
+```
+Input Parsing:
+   └─ Decision (session argument):
+      ├─ session-id provided → Use provided session
+      └─ No session-id → Auto-detect active session
+
+Phase 1: Session Discovery
+   ├─ Validate session directory exists
+   └─ TodoWrite: Mark phase 1 completed
+
+Phase 2: Task Chain Validation
+   ├─ Load all task JSONs from .task/
+   ├─ Extract task IDs and group by feature
+   ├─ Validate TDD structure:
+   │  ├─ TEST-N.M → IMPL-N.M → REFACTOR-N.M chain
+   │  ├─ Dependency verification
+   │  └─ Meta field validation (tdd_phase, agent)
+   └─ TodoWrite: Mark phase 2 completed
+
+Phase 3: Test Execution Analysis
+   └─ /workflow:tools:tdd-coverage-analysis
+      ├─ Coverage metrics extraction
+      ├─ TDD cycle verification
+      └─ Compliance score calculation
+
+Phase 4: Compliance Report Generation
+   ├─ Gemini analysis for comprehensive report
+   ├─ Generate TDD_COMPLIANCE_REPORT.md
+   └─ Return summary to user
+```
+
 ## 4-Phase Execution
 
 ### Phase 1: Session Discovery
@@ -28,7 +61,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 +77,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 +115,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 +130,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 +139,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
@@ -134,7 +167,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 +201,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 +235,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 +248,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

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

@@ -343,19 +343,49 @@ CRITICAL - Next Steps:
 
 **Core Concept**: Dynamic task attachment and collapse for test-fix-gen workflow with dual-mode support (Session Mode and Prompt Mode).
 
+#### Initial TodoWrite Structure
+
+```json
+[
+  {"content": "Phase 1: Create Test Session", "status": "in_progress", "activeForm": "Creating test session"},
+  {"content": "Phase 2: Gather Test Context", "status": "pending", "activeForm": "Gathering test context"},
+  {"content": "Phase 3: Test Generation Analysis", "status": "pending", "activeForm": "Analyzing test generation"},
+  {"content": "Phase 4: Generate Test Tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Phase 5: Return Summary", "status": "pending", "activeForm": "Completing"}
+]
+```
+
 #### 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
+   - Example - Phase 2 with sub-tasks:
+   ```json
+   [
+     {"content": "Phase 1: Create Test Session", "status": "completed", "activeForm": "Creating test session"},
+     {"content": "Phase 2: Gather Test Context", "status": "in_progress", "activeForm": "Gathering test context"},
+     {"content": "  → Load context and analyze coverage", "status": "in_progress", "activeForm": "Loading context"},
+     {"content": "  → Detect test framework and conventions", "status": "pending", "activeForm": "Detecting framework"},
+     {"content": "  → Generate context package", "status": "pending", "activeForm": "Generating context"},
+     {"content": "Phase 3: Test Generation Analysis", "status": "pending", "activeForm": "Analyzing test generation"},
+     {"content": "Phase 4: Generate Test Tasks", "status": "pending", "activeForm": "Generating test tasks"},
+     {"content": "Phase 5: Return Summary", "status": "pending", "activeForm": "Completing"}
+   ]
+   ```
 
 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
+   - Example - Phase 2 completed:
+   ```json
+   [
+     {"content": "Phase 1: Create Test Session", "status": "completed", "activeForm": "Creating test session"},
+     {"content": "Phase 2: Gather Test Context", "status": "completed", "activeForm": "Gathering test context"},
+     {"content": "Phase 3: Test Generation Analysis", "status": "in_progress", "activeForm": "Analyzing test generation"},
+     {"content": "Phase 4: Generate Test Tasks", "status": "pending", "activeForm": "Generating test tasks"},
+     {"content": "Phase 5: Return Summary", "status": "pending", "activeForm": "Completing"}
+   ]
+   ```
 
 3. **Continuous Execution**:
    - After collapse, automatically proceed to next pending phase
@@ -374,14 +404,6 @@ CRITICAL - Next Steps:
 - **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)
 
-**Benefits**:
-- Real-time visibility into attached tasks during execution
-- Clean orchestrator-level summary after tasks complete
-- Clear mental model: SlashCommand = attach tasks, not delegate work
-- Dual-mode support: Both Session Mode and Prompt Mode use same attachment pattern
-- Dynamic attachment/collapse maintains clarity
-
-**Note**: Unlike other workflow orchestrators, this file consolidates TodoWrite examples in this section rather than distributing them across Phase descriptions for better dual-mode clarity.
 
 ---
 
@@ -513,7 +535,7 @@ If quality gate fails:
 
 ### Output Files Structure
 
-Created in `.workflow/WFS-test-[session]/`:
+Created in `.workflow/active/WFS-test-[session]/`:
 
 ```
 WFS-test-[session]/
@@ -579,7 +601,7 @@ Test-Fix-Gen Workflow Orchestrator (Dual-Mode Support)
    └─ 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

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

@@ -355,11 +355,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
 - **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)
 
-**Benefits**:
-- Real-time visibility into attached tasks during execution
-- Clean orchestrator-level summary after tasks complete
-- Clear mental model: SlashCommand = attach tasks, not delegate work
-- Dynamic attachment/collapse maintains clarity
+
 
 **Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
 
@@ -397,7 +393,7 @@ Test-Gen Workflow Orchestrator
    └─ 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
@@ -444,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

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

@@ -3,14 +3,14 @@ name: conflict-resolution
 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,11 +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 |
+| **User Decision** | Present options ONE BY ONE, never auto-apply |
 | **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
-| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
+| **Structured Data** | JSON output for programmatic processing, NO file generation |
 
 ## Conflict Categories
 
@@ -49,6 +52,48 @@ 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 Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session, --context
+   └─ Validation: Both REQUIRED, conflict_risk >= medium
+
+Phase 1: Validation
+   ├─ Step 1: Verify session directory exists
+   ├─ Step 2: Load context-package.json
+   ├─ Step 3: Check conflict_risk (skip if none/low)
+   └─ Step 4: Prepare agent task prompt
+
+Phase 2: CLI-Powered Analysis (Agent)
+   ├─ Execute Gemini analysis (Qwen fallback)
+   ├─ Detect conflicts including ModuleOverlap category
+   └─ Generate 2-4 strategies per conflict with modifications
+
+Phase 3: Iterative User Interaction
+   └─ FOR each conflict (one by one):
+      ├─ Display conflict with overlap_analysis (if ModuleOverlap)
+      ├─ Display strategies (2-4 + custom option)
+      ├─ User selects strategy
+      └─ IF clarification_needed:
+         ├─ Collect answers
+         ├─ Agent re-analysis
+         └─ Loop until uniqueness_confirmed (max 10 rounds)
+
+Phase 4: Apply Modifications
+   ├─ Step 1: Extract modifications from resolved strategies
+   ├─ Step 2: Apply using Edit tool
+   ├─ Step 3: Update context-package.json (mark resolved)
+   └─ Step 4: Output custom conflict summary (if any)
+```
+
 ## Execution Flow
 
 ### Phase 1: Validation
@@ -73,23 +118,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)
@@ -98,9 +151,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
@@ -116,10 +171,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": {
@@ -128,6 +183,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": "策略名称（中文）",
@@ -137,9 +209,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": "原始内容片段（用于定位）",
@@ -147,7 +225,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": "原始内容片段",
@@ -204,155 +282,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}`);
     });
@@ -360,25 +534,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
@@ -435,31 +627,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)
 ```
 

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

@@ -22,7 +22,39 @@ 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 Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session
+   └─ Parse: task_description (required)
+
+Step 1: Context-Package Detection
+   └─ Decision (existing package):
+      ├─ Valid package exists → Return existing (skip execution)
+      └─ No valid package → Continue to Step 2
+
+Step 2: Invoke Context-Search Agent
+   ├─ Phase 1: Initialization & Pre-Analysis
+   │  ├─ Load project.json as primary context
+   │  ├─ Initialize code-index
+   │  └─ Classify complexity
+   ├─ Phase 2: Multi-Source Discovery
+   │  ├─ Track 1: Historical archive analysis
+   │  ├─ Track 2: Reference documentation
+   │  ├─ Track 3: Web examples (Exa MCP)
+   │  └─ Track 4: Codebase analysis (5-layer)
+   └─ Phase 3: Synthesis & Packaging
+      ├─ Apply relevance scoring
+      ├─ Integrate brainstorm artifacts
+      ├─ Perform conflict detection
+      └─ Generate context-package.json
+
+Step 3: Output Verification
+   └─ Verify context-package.json created
+```
 
 ## Execution Flow
 
@@ -57,8 +89,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,9 +101,10 @@ 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 4 discovery tracks:
@@ -84,16 +115,17 @@ Execute all 4 discovery tracks:
 
 ### Phase 3: Synthesis, Assessment & Packaging
 1. Apply relevance scoring and build dependency graph
-2. Synthesize 4-source data (archive > docs > code > web)
-3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
-4. Perform conflict detection with risk assessment
-5. **Inject historical conflicts** from archive analysis into conflict_detection
-6. Generate and validate context-package.json
+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
@@ -139,7 +171,7 @@ 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)
@@ -154,7 +186,7 @@ The context-search-agent MUST perform historical archive analysis as Track 1 in
 **Step 1: Check for Archive Manifest**
 ```bash
 # Check if archive manifest exists
-if [[ -f .workflow/.archives/manifest.json ]]; then
+if [[ -f .workflow/archives/manifest.json ]]; then
   # Manifest available for querying
 fi
 ```
@@ -233,7 +265,7 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
 ### Archive Query Algorithm
 
 ```markdown
-1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
+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)
@@ -250,33 +282,10 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
 3. Continue to Track 2 (reference documentation)
 ```
 
-## Usage Examples
-
-### Basic Usage
-```bash
-/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
-```
-## Success Criteria
-
-- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
-- ✅ Contains >80% relevant files based on task keywords
-- ✅ Execution completes within 2 minutes
-- ✅ All required schema fields present and valid
-- ✅ Conflict risk accurately assessed
-- ✅ Agent reports completion with statistics
-
-## Error Handling
-
-| 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 |
-
 ## 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,258 +1,138 @@
 ---
 name: task-generate-agent
-description: Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning
+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
+## Execution Process
 
-### Phase 1: Discovery & Context Loading
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+```
+Input Parsing:
+   ├─ Parse flags: --session, --cli-execute
+   └─ Validation: session_id REQUIRED
 
-**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
-  }
-}
+Phase 1: Context Preparation (Command)
+   ├─ Assemble session paths (metadata, context package, output dirs)
+   └─ Provide metadata (session_id, execution_mode, mcp_capabilities)
+
+Phase 2: Planning Document Generation (Agent)
+   ├─ Load context package (progressive loading strategy)
+   ├─ Generate Task JSON Files (.task/IMPL-*.json)
+   ├─ Create IMPL_PLAN.md
+   └─ Generate TODO_LIST.md
 ```
 
-**Discovery Actions**:
-1. **Load Session Context** (if not in memory)
-   ```javascript
-   if (!memory.has("workflow-session.json")) {
-     Read(.workflow/{session-id}/workflow-session.json)
-   }
-   ```
+## Document Generation Lifecycle
 
-2. **Load Context Package** (if not in memory)
-   ```javascript
-   if (!memory.has("context-package.json")) {
-     Read(.workflow/{session-id}/.process/context-package.json)
-   }
-   ```
+### Phase 1: Context Preparation (Command Responsibility)
 
-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));
+**Command prepares session paths and metadata for planning document generation.**
 
-   // 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";
+**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
+```
+
+**Command Preparation**:
+1. **Assemble Session Paths** for agent prompt:
+   - `session_metadata_path`
+   - `context_package_path`
+   - Output directory paths
+
+2. **Provide Metadata** (simple values):
+   - `session_id`
+   - `execution_mode` (agent-mode | cli-execute-mode)
+   - `mcp_capabilities` (available MCP tools)
+
+### Phase 2: Planning Document Generation (Agent Responsibility)
+
+**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
 
-**Agent Configuration Reference**: All task generation rules, quantification requirements, quality standards, and execution details are defined in action-planning-agent.
-
-Refer to: @.claude/agents/action-planning-agent.md for:
-- Task Decomposition Standards
-- Quantification Requirements (MANDATORY)
-- 5-Field Task JSON Schema
-- IMPL_PLAN.md Structure
-- TODO_LIST.md Format
-- Execution Flow & Quality Validation
-
-### Required Outputs Summary
-
-#### 1. Task JSON Files (.task/IMPL-*.json)
-- **Location**: `.workflow/{session-id}/.task/`
-- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
-- **Schema**: 5-field structure (id, title, status, meta, context, flow_control) with artifacts integration
-- **Details**: See action-planning-agent.md § Task JSON Generation
-
-#### 2. IMPL_PLAN.md
-- **Location**: `.workflow/{session-id}/IMPL_PLAN.md`
-- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
-- **Details**: See action-planning-agent.md § Implementation Plan Creation
-
-#### 3. TODO_LIST.md
-- **Location**: `.workflow/{session-id}/TODO_LIST.md`
-- **Format**: Hierarchical task list with status indicators (▸, [ ], [x]) and JSON links
-- **Details**: See action-planning-agent.md § TODO List Generation
-
-### Agent Execution Summary
-
-**Key Steps** (Detailed instructions in action-planning-agent.md):
-1. Load task JSON template from provided path
-2. Extract and decompose tasks with quantification
-3. Generate task JSON files enforcing quantification requirements
-4. Create IMPL_PLAN.md using template
-5. Generate TODO_LIST.md matching task JSONs
-6. Update session state
-
-**Quality Gates** (Full checklist in action-planning-agent.md):
-- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
-- ✓ Task count ≤10 (hard limit)
-- ✓ Artifact references mapped correctly
-- ✓ MCP tool integration added
-- ✓ Documents follow template structure
-
-## 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

@@ -30,11 +30,6 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
 - **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)
@@ -58,6 +53,30 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
 - **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
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session, --cli-execute
+   └─ Validation: session_id REQUIRED
+
+Phase 1: Discovery & Context Loading (Memory-First)
+   ├─ Load session context (if not in memory)
+   ├─ Load context package (if not in memory)
+   ├─ Load test context package (if not in memory)
+   ├─ Extract & load role analyses from context package
+   ├─ Load conflict resolution (if exists)
+   └─ Optional: MCP external research
+
+Phase 2: Agent Execution (Document Generation)
+   ├─ Pre-agent template selection (agent-mode OR cli-execute-mode)
+   ├─ Invoke action-planning-agent
+   ├─ Generate TDD Task JSON Files (.task/IMPL-*.json)
+   │  └─ Each task: complete Red-Green-Refactor cycle internally
+   ├─ Create IMPL_PLAN.md (TDD variant)
+   └─ Generate TODO_LIST.md with TDD phase indicators
+```
+
 ## Execution Lifecycle
 
 ### Phase 1: Discovery & Context Loading
@@ -74,7 +93,7 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
   "workflow_type": "tdd",
   "session_metadata": {
     // If in memory: use cached content
-    // Else: Load from .workflow/{session-id}/workflow-session.json
+    // Else: Load from .workflow/active//{session-id}/workflow-session.json
   },
   "brainstorm_artifacts": {
     // Loaded from context-package.json → brainstorm_artifacts section
@@ -88,12 +107,12 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
     "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_path": ".workflow/active//{session-id}/.process/context-package.json",
   "context_package": {
     // If in memory: use cached content
-    // Else: Load from .workflow/{session-id}/.process/context-package.json
+    // Else: Load from .workflow/active//{session-id}/.process/context-package.json
   },
-  "test_context_package_path": ".workflow/{session-id}/.process/test-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
   },
@@ -109,21 +128,21 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
 1. **Load Session Context** (if not in memory)
    ```javascript
    if (!memory.has("workflow-session.json")) {
-     Read(.workflow/{session-id}/workflow-session.json)
+     Read(.workflow/active//{session-id}/workflow-session.json)
    }
    ```
 
 2. **Load Context Package** (if not in memory)
    ```javascript
    if (!memory.has("context-package.json")) {
-     Read(.workflow/{session-id}/.process/context-package.json)
+     Read(.workflow/active//{session-id}/.process/context-package.json)
    }
    ```
 
 3. **Load Test Context Package** (if not in memory)
    ```javascript
    if (!memory.has("test-context-package.json")) {
-     Read(.workflow/{session-id}/.process/test-context-package.json)
+     Read(.workflow/active//{session-id}/.process/test-context-package.json)
    }
    ```
 
@@ -245,7 +264,7 @@ Refer to: @.claude/agents/action-planning-agent.md for:
 #### Required Outputs Summary
 
 ##### 1. TDD Task JSON Files (.task/IMPL-*.json)
-- **Location**: `.workflow/{session-id}/.task/`
+- **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)
@@ -259,14 +278,14 @@ Refer to: @.claude/agents/action-planning-agent.md for:
 - **Details**: See action-planning-agent.md § TDD Task JSON Generation
 
 ##### 2. IMPL_PLAN.md (TDD Variant)
-- **Location**: `.workflow/{session-id}/IMPL_PLAN.md`
+- **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/{session-id}/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
@@ -338,19 +357,19 @@ const agentContext = {
   // 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),
+    : Read(.workflow/active/WFS-[id]/workflow-session.json),
 
-  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
+  context_package_path: ".workflow/active/WFS-[id]/.process/context-package.json",
 
   context_package: memory.has("context-package.json")
     ? memory.get("context-package.json")
-    : Read(".workflow/WFS-[id]/.process/context-package.json"),
+    : Read(".workflow/active/WFS-[id]/.process/context-package.json"),
 
-  test_context_package_path: ".workflow/WFS-[id]/.process/test-context-package.json",
+  test_context_package_path: ".workflow/active/WFS-[id]/.process/test-context-package.json",
 
   test_context_package: memory.has("test-context-package.json")
     ? memory.get("test-context-package.json")
-    : Read(".workflow/WFS-[id]/.process/test-context-package.json"),
+    : Read(".workflow/active/WFS-[id]/.process/test-context-package.json"),
 
   // Extract brainstorm artifacts from context package
   brainstorm_artifacts: extractBrainstormArtifacts(context_package),
@@ -384,7 +403,7 @@ This section provides quick reference for TDD task JSON structure. For complete
 
 ## 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/
@@ -499,11 +518,7 @@ 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)

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

@@ -1,680 +0,0 @@
---- 
-name: task-generate
-description: Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration
-argument-hint: "--session WFS-session-id [--cli-execute]"
-examples:
-  - /workflow:tools:task-generate --session WFS-auth
-  - /workflow:tools:task-generate --session WFS-auth --cli-execute
----
-
-# Task Generation Command
-
-## 1. Overview
-This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
-
-## 2. Execution Modes
-
-This command offers two distinct modes for task execution, providing flexibility for different implementation complexities.
-
-### Agent Mode (Default)
-In the default mode, each step in `implementation_approach` **omits the `command` field**. The agent interprets the step's `modification_points` and `logic_flow` to execute the task autonomously.
-- **Step Structure**: Contains `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, and `output` fields
-- **Execution**: Agent reads these fields and performs the implementation autonomously
-- **Context Loading**: Agent loads context via `pre_analysis` steps
-- **Validation**: Agent validates against acceptance criteria in `context.acceptance`
-- **Benefit**: Direct agent execution with full context awareness, no external tool overhead
-- **Use Case**: Standard implementation tasks where agent capability is sufficient
-
-### CLI Execute Mode (`--cli-execute`)
-When the `--cli-execute` flag is used, each step in `implementation_approach` **includes a `command` field** that specifies the exact execution command. This mode is designed for complex implementations requiring specialized CLI tools.
-- **Step Structure**: Includes all default fields PLUS a `command` field
-- **Execution**: The specified command executes the step directly (e.g., `bash(codex ...)`)
-- **Context Packages**: Each command receives context via the CONTEXT field in the prompt
-- **Multi-Step Support**: Complex tasks can have multiple sequential codex steps with `resume --last`
-- **Benefit**: Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning and autonomous execution
-- **Use Case**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
-
-## 3. Core Principles
-This command is built on a set of core principles to ensure efficient and reliable task generation.
-
-- **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
-- **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
-- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
-- **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`)
-- **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
-- **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
-- **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
-- **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
-- **Quantification-Enforced**: **NEW** - All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations to prevent ambiguity (e.g., "17 commands: [list]" not "implement commands")
-- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
-
-## 3.5. 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**:
-- [ ] 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
-
-## 4. Execution Flow
-The command follows a streamlined, three-step process to convert analysis into executable tasks.
-
-### Step 1: Input & Discovery
-The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
-1.  **Session Validation**: Loads and validates the session from `.workflow/{session_id}/workflow-session.json`.
-2.  **Context Package Loading** (primary source): Reads `.workflow/{session_id}/.process/context-package.json` for smart context and artifact catalog.
-3.  **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
-4.  **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
-
-### Step 2: Task Decomposition & Grouping
-Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
-
-**Phase 2.1: Quantification Extraction (NEW - CRITICAL)**
-1. **Count Extraction**: Scan analysis documents for quantifiable information:
-   - Search for numbers + nouns (e.g., "5 files", "17 commands", "3 features")
-   - Identify enumerated lists (bullet points, numbered lists, comma-separated items)
-   - Extract explicit counts from tables, diagrams, or structured data
-   - Store extracted counts with their context (what is being counted)
-
-2. **List Enumeration**: Build explicit lists for each deliverable:
-   - If analysis says "implement session commands", enumerate ALL commands: [start, resume, list, complete, archive]
-   - If analysis mentions "create categories", list ALL categories: [literature, experiment, data-analysis, visualization, context]
-   - If analysis describes "modify functions", list ALL functions with line numbers
-   - Maintain full enumerations (no "..." unless list exceeds 20 items)
-
-3. **Verification Method Assignment**: For each deliverable, determine verification approach:
-   - File count: `ls {path}/*.{ext} | wc -l = {count}`
-   - Directory existence: `ls {parent}/ | grep -E '(name1|name2|...)' | wc -l = {count}`
-   - Test coverage: `pytest --cov={module} --cov-report=term | grep TOTAL | awk '{print $4}' >= {percentage}`
-   - Function existence: `grep -E '(func1|func2|...)' {file} | wc -l = {count}`
-
-4. **Ambiguity Detection**: Flag vague language for replacement:
-   - Detect words: "complete", "comprehensive", "reorganize", "refactor", "implement", "create" without counts
-   - Require quantification: "implement" → "implement {N} {items}: [{list}]"
-   - Reject unquantified deliverables
-
-**Phase 2.2: Task Definition & Grouping**
-1.  **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies from quantified analysis
-2.  **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`
-3.  **Task Grouping**:
-    *   Tasks with the **same signature** are candidates for merging, as they operate on the same context
-    *   Tasks with **different signatures** and no dependencies are grouped for parallel execution
-    *   Tasks with `depends_on` relationships are marked for sequential execution
-4.  **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field
-
-### Step 3: Output Generation
-Finally, the command generates all the necessary output files.
-1.  **Task JSON Creation**: Creates individual `.task/IMPL-*.json` files, embedding all context, artifacts, and flow control steps. If `--cli-execute` is active, it generates the appropriate `codex exec` commands.
-2.  **IMPL_PLAN.md Generation**: Creates the main implementation plan document, summarizing the strategy, tasks, and dependencies.
-3.  **TODO_LIST.md Generation**: Creates a simple checklist for tracking task progress.
-4.  **Session State Update**: Updates `workflow-session.json` with the final task count and artifact inventory, marking the session as ready for execution.
-
-## 5. Task Decomposition Strategy
-The command employs a sophisticated strategy to group and decompose tasks, optimizing for context reuse and parallel execution.
-
-### Core Principles
-- **Primary Rule: Shared Context → Merge Tasks**: Tasks that operate on the same files, use the same artifacts, and share the same tech stack are merged. This avoids redundant context loading and recognizes inherent relationships between the tasks.
-- **Secondary Rule: Different Contexts + No Dependencies → Decompose for Parallel Execution**: Tasks that are fully independent (different files, different artifacts, no shared dependencies) are decomposed into separate parallel execution groups.
-
-### Context Analysis for Task Grouping
-The decision to merge or decompose is based on analyzing context indicators:
-
-1.  **Shared Context Indicators (→ Merge)**:
-    *   Identical `focus_paths` (working on the same modules/files).
-    *   Same tech stack and dependencies.
-    *   Identical `context.artifacts` references.
-    *   A sequential logic flow within the same feature.
-    *   Shared test fixtures or setup.
-
-2.  **Independent Context Indicators (→ Decompose)**:
-    *   Different `focus_paths` (separate modules).
-    *   Different tech stacks (e.g., frontend vs. backend).
-    *   Different `context.artifacts` (using different brainstorming outputs).
-    *   No shared dependencies.
-    *   Can be tested independently.
-
-**Decomposition is only performed when**:
-- Tasks have different contexts and no shared dependencies (enabling parallel execution).
-- A single task represents an excessive workload (e.g., >2500 lines of code or >6 files to modify).
-- A sequential dependency creates a necessary block (e.g., IMPL-1 must complete before IMPL-2 can start).
-
-### Context Signature Algorithm
-To automate grouping, a `context_signature` is computed for each task.
-
-```javascript
-// Compute context signature for task grouping
-function computeContextSignature(task) {
-  const focusPathsStr = task.context.focus_paths.sort().join('|');
-  const artifactsStr = task.context.artifacts.map(a => a.path).sort().join('|');
-  const techStack = task.context.shared_context?.tech_stack?.sort().join('|') || '';
-
-  return hash(`${focusPathsStr}:${artifactsStr}:${techStack}`);
-}
-```
-
-### Execution Group Assignment
-Tasks are assigned to execution groups based on their signatures and dependencies.
-
-```javascript
-// Group tasks by context signature
-function groupTasksByContext(tasks) {
-  const groups = {};
-
-  tasks.forEach(task => {
-    const signature = computeContextSignature(task);
-    if (!groups[signature]) {
-      groups[signature] = [];
-    }
-    groups[signature].push(task);
-  });
-
-  return groups;
-}
-
-// Assign execution groups for parallel tasks
-function assignExecutionGroups(tasks) {
-  const contextGroups = groupTasksByContext(tasks);
-
-  Object.entries(contextGroups).forEach(([signature, groupTasks]) => {
-    if (groupTasks.length === 1) {
-      const task = groupTasks[0];
-      // Single task with unique context
-      if (!task.context.depends_on || task.context.depends_on.length === 0) {
-        task.meta.execution_group = `parallel-${signature.slice(0, 8)}`;
-      } else {
-        task.meta.execution_group = null; // Sequential task
-      }
-    } else {
-      // Multiple tasks with same context → Should be merged
-      console.warn(`Tasks ${groupTasks.map(t => t.id).join(', ')} share context and should be merged`);
-      // Merge tasks into single task
-      return mergeTasks(groupTasks);
-    }
-  });
-}
-```
-**Task Limits**:
-- **Maximum 10 tasks** (hard limit).
-- **Hierarchy**: Flat (≤5 tasks) or two-level (6-10 tasks). If >10, the scope should be re-evaluated.
-- **Parallel Groups**: Tasks with the same `execution_group` ID are independent and can run concurrently.
-
-## 6. Generated Outputs
-The command produces three key documents and a directory of task files.
-
-### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
-Each task JSON embeds all necessary context, artifacts, and execution steps using this schema:
-
-**Top-Level Fields**:
-- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
-- `title`: Descriptive task name
-- `status`: Task state (`pending|active|completed|blocked|container`)
-- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`)
-- `meta`: Task metadata
-- `context`: Task-specific context and requirements
-- `flow_control`: Execution steps and workflow
-
-**Meta Object**:
-- `type`: Task category (`feature|bugfix|refactor|test-gen|test-fix|docs`)
-- `agent`: Assigned agent (`@code-developer|@test-fix-agent|@universal-executor`)
-- `execution_group`: Parallelization group ID or null
-- `context_signature`: Hash for context-based grouping
-
-**Context Object**:
-- `requirements`: Quantified implementation requirements (with counts and explicit lists)
-- `focus_paths`: Target directories/files (absolute or relative paths)
-- `acceptance`: Measurable acceptance criteria (with verification commands)
-- `parent`: Parent task ID for subtasks
-- `depends_on`: Prerequisite task IDs
-- `inherited`: Shared patterns and dependencies from parent
-- `shared_context`: Tech stack and conventions
-- `artifacts`: Referenced brainstorm artifacts with paths, priority, and usage
-
-**Flow Control Object**:
-- `pre_analysis`: Context loading and preparation steps
-  - `load_context_package`: Load smart context and artifact catalog
-  - `load_role_analysis_artifacts`: Load role analyses dynamically from context package
-  - `load_planning_context`: Load finalized decisions with resolved conflicts
-  - `codebase_exploration`: Discover existing patterns
-  - `analyze_task_patterns`: Identify modification targets
-- `implementation_approach`: Execution steps
-  - **Agent Mode**: Steps contain `modification_points` and `logic_flow` (agent executes autonomously)
-  - **CLI Mode**: Steps include `command` field with CLI tool invocation
-- `target_files`: Specific files/functions/lines to modify
-
-**Key Characteristics**:
-- **Quantification**: All requirements/acceptance use explicit counts and enumerations
-- **Mode Flexibility**: Supports both agent execution (default) and CLI tool execution (`--cli-execute`)
-- **Context Intelligence**: References context-package.json for smart context and artifact paths
-- **Artifact Integration**: Dynamically loads role analyses and brainstorm artifacts
-
-**Example Task JSON**:
-```json
-{
-  "id": "IMPL-1",
-  "title": "Implement feature X with Y components",
-  "status": "pending",
-  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
-  "meta": {
-    "type": "feature",
-    "agent": "@code-developer",
-    "execution_group": "parallel-abc123",
-    "context_signature": "hash-value"
-  },
-  "context": {
-    "requirements": [
-      "Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]",
-      "Create 3 directories: [dir1/, dir2/, dir3/]",
-      "Modify 2 functions: [funcA() in file1.ts lines 10-25, funcB() in file2.ts lines 40-60]"
-    ],
-    "focus_paths": ["D:\\project\\src\\module", "./tests/module"],
-    "acceptance": [
-      "5 command files created: verify by ls .claude/commands/*/*.md | wc -l = 5",
-      "3 directories exist: verify by ls -d dir*/ | wc -l = 3",
-      "All tests pass: pytest tests/ --cov=src/module (>=80% coverage)"
-    ],
-    "depends_on": [],
-    "artifacts": [
-      {
-        "path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md",
-        "priority": "highest",
-        "usage": "Architecture decisions and API specifications"
-      }
-    ]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "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",
-        "commands": [
-          "Read({{context_package_path}})",
-          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
-          "Read(each extracted path)"
-        ],
-        "output_to": "role_analysis_artifacts",
-        "on_error": "skip_optional"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Implement feature following role analyses",
-        "description": "Implement feature X using requirements from role analyses and context package",
-        "modification_points": [
-          "Create 5 command files: [cmd1.md, cmd2.md, cmd3.md, cmd4.md, cmd5.md]",
-          "Modify funcA() in file1.ts lines 10-25: add validation logic",
-          "Modify funcB() in file2.ts lines 40-60: integrate with new API"
-        ],
-        "logic_flow": [
-          "Load role analyses and context package",
-          "Extract requirements and design decisions",
-          "Implement commands following existing patterns",
-          "Update functions with new logic",
-          "Validate against acceptance criteria"
-        ],
-        "depends_on": [],
-        "output": "implementation"
-      }
-    ],
-    "target_files": ["file1.ts:funcA:10-25", "file2.ts:funcB:40-60"]
-  }
-}
-```
-
-**Note**: In CLI Execute Mode (`--cli-execute`), `implementation_approach` steps include a `command` field with the CLI tool invocation (e.g., `bash(codex ...)`).
-
-### 6.2. IMPL_PLAN.md Structure
-This document provides a high-level overview of the entire implementation plan.
-
-```markdown
----
-identifier: WFS-{session-id}
-source: "User requirements" | "File: path" | "Issue: ISS-001"
-role_analyses: .workflow/{session-id}/.brainstorming/[role]/analysis*.md
-artifacts: .workflow/{session-id}/.brainstorming/
-context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
-guidance_specification: .workflow/{session-id}/.brainstorming/guidance-specification.md  # Finalized decisions with resolved conflicts
-workflow_type: "standard | tdd | design"  # Indicates execution model
-verification_history:  # CCW quality gates
-  synthesis_clarify: "passed | skipped | pending"  # Brainstorm phase clarification
-  action_plan_verify: "pending"
-  conflict_resolution: "resolved | none | low"  # Status from context-package.json
-phase_progression: "brainstorm → synthesis → context → conflict_resolution (if needed) → planning"  # CCW workflow phases
----
-
-# Implementation Plan: {Project Title}
-
-## 1. Summary
-Core requirements, objectives, technical approach summary (2-3 paragraphs max).
-
-**Core Objectives**:
-- [Key objective 1]
-- [Key objective 2]
-
-**Technical Approach**:
-- [High-level approach]
-
-## 2. Context Analysis
-
-### CCW Workflow Context
-**Phase Progression**:
-- ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
-- ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
-- ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
-- ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
-- ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
-
-**Quality Gates**:
-- synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
-- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
-
-**Context Package Summary**:
-- **Focus Paths**: {list key directories from context-package.json}
-- **Key Files**: {list primary files for modification}
-- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
-- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
-
-### Project Profile
-- **Type**: Greenfield/Enhancement/Refactor
-- **Scale**: User count, data volume, complexity
-- **Tech Stack**: Primary technologies
-- **Timeline**: Duration and milestones
-
-### Module Structure
-'''
-[Directory tree showing key modules]
-'''
-
-### Dependencies
-**Primary**: [Core libraries and frameworks]
-**APIs**: [External services]
-**Development**: [Testing, linting, CI/CD tools]
-
-### Patterns & Conventions
-- **Architecture**: [Key patterns like DI, Event-Driven]
-- **Component Design**: [Design patterns]
-- **State Management**: [State strategy]
-- **Code Style**: [Naming, TypeScript coverage]
-
-## 3. Brainstorming Artifacts Reference
-
-### Artifact Usage Strategy
-**Primary Reference (Role Analyses)**:
-- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
-- **When**: Every task references relevant role analyses for requirements and design decisions
-- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
-- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
-- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
-
-**Context Intelligence (context-package.json)**:
-- **What**: Smart context gathered by CCW's context-gather phase
-- **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk status
-- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
-- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
-
-**Conflict Resolution Status**:
-- **What**: Conflict resolution applied in-place to brainstorm artifacts (if conflict_risk was >= medium)
-- **Location**: guidance-specification.md and role analyses (*.md) contain resolved conflicts
-- **Status**: Check context-package.json → conflict_detection.conflict_risk ("resolved" | "none" | "low")
-- **Usage**: Read finalized decisions from guidance-specification.md (includes applied resolutions)
-- **CCW Value**: Interactive conflict resolution with user confirmation, modifications applied automatically
-
-### Role Analysis Documents (Highest Priority)
-Role analyses provide specialized perspectives on the implementation:
-- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
-- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
-- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
-- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
-- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
-- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns
-
-### Supporting Artifacts (Reference)
-- **topic-framework.md**: Role-specific discussion points and analysis framework
-
-**Artifact Priority in Development**:
-1. {context_package_path} (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts` + conflict_risk status)
-2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis, with resolved conflicts if any)
-3. guidance-specification.md (path from context-package.json: finalized decisions with resolved conflicts if any)
-
-## 4. Implementation Strategy
-
-### Execution Strategy
-**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
-
-**Rationale**: [Why this execution model fits the project]
-
-**Parallelization Opportunities**:
-- [List independent workstreams]
-
-**Serialization Requirements**:
-- [List critical dependencies]
-
-### Architectural Approach
-**Key Architecture Decisions**:
-- [ADR references from role analyses]
-- [Justification for architecture patterns]
-
-**Integration Strategy**:
-- [How modules communicate]
-- [State management approach]
-
-### Key Dependencies
-**Task Dependency Graph**:
-'''
-[High-level dependency visualization]
-'''
-
-**Critical Path**: [Identify bottleneck tasks]
-
-### Testing Strategy
-**Testing Approach**:
-- Unit testing: [Tools, scope]
-- Integration testing: [Key integration points]
-- E2E testing: [Critical user flows]
-
-**Coverage Targets**:
-- Lines: ≥70%
-- Functions: ≥70%
-- Branches: ≥65%
-
-**Quality Gates**:
-- [CI/CD gates]
-- [Performance budgets]
-
-## 5. Task Breakdown Summary
-
-### Task Count
-**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
-
-### Task Structure
-- **IMPL-1**: [Main task title]
-- **IMPL-2**: [Main task title]
-...
-
-### Complexity Assessment
-- **High**: [List with rationale]
-- **Medium**: [List]
-- **Low**: [List]
-
-### Dependencies
-[Reference Section 4.3 for dependency graph]
-
-**Parallelization Opportunities**:
-- [Specific task groups that can run in parallel]
-
-## 6. Implementation Plan (Detailed Phased Breakdown)
-
-### Execution Strategy
-
-**Phase 1 (Weeks 1-2): [Phase Name]**
-- **Tasks**: IMPL-1, IMPL-2
-- **Deliverables**:
-  - [Specific deliverable 1]
-  - [Specific deliverable 2]
-- **Success Criteria**:
-  - [Measurable criterion]
-
-**Phase 2 (Weeks 3-N): [Phase Name]**
-...
-
-### Resource Requirements
-
-**Development Team**:
-- [Team composition and skills]
-
-**External Dependencies**:
-- [Third-party services, APIs]
-
-**Infrastructure**:
-- [Development, staging, production environments]
-
-## 7. Risk Assessment & Mitigation
-
-| Risk | Impact | Probability | Mitigation Strategy | Owner |
-|------|--------|-------------|---------------------|-------|
-| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
-
-**Critical Risks** (High impact + High probability):
-- [Risk 1]: [Detailed mitigation plan]
-
-**Monitoring Strategy**:
-- [How risks will be monitored]
-
-## 8. Success Criteria
-
-**Functional Completeness**:
-- [ ] All requirements from role analysis documents implemented
-- [ ] All acceptance criteria from task.json files met
-
-**Technical Quality**:
-- [ ] Test coverage ≥70%
-- [ ] Bundle size within budget
-- [ ] Performance targets met
-
-**Operational Readiness**:
-- [ ] CI/CD pipeline operational
-- [ ] Monitoring and logging configured
-- [ ] Documentation complete
-
-**Business Metrics**:
-- [ ] [Key business metrics from role analyses]
-```
-
-### 6.3. TODO_LIST.md Structure
-A simple Markdown file for tracking the status of each task.
-
-```markdown
-# Tasks: [Session Topic]
-
-## Task Progress
-▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
-  - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
-  - [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md)
-
-- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)
-
-## Status Legend
-- `▸` = Container task (has subtasks)
-- `- [ ]` = Pending leaf task
-- `- [x]` = Completed leaf task
-- Maximum 2 levels: Main tasks and subtasks only
-```
-
-### 6.4. Output Files Diagram
-The command organizes outputs into a standard directory structure.
-```
-.workflow/{session-id}/
-├── IMPL_PLAN.md                     # Implementation plan
-├── TODO_LIST.md                     # Progress tracking
-├── .task/
-│   ├── IMPL-1.json                  # Container task
-│   ├── IMPL-1.1.json                # Leaf task with flow_control
-│   └── IMPL-1.2.json                # Leaf task with flow_control
-├── .brainstorming              # Input artifacts from brainstorm + synthesis
-│   ├── guidance-specification.md    # Finalized decisions (with resolved conflicts if any)
-│   └── {role}/analysis*.md          # Role analyses (enhanced by synthesis, with resolved conflicts if any)
-└── .process/
-    └── context-package.json         # Input from context-gather (smart context + conflict_risk status)
-```
-
-## 7. Artifact Integration
-The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
-
-#### Artifact Priority
-1.  **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section + conflict_risk status
-2.  **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis, with resolved conflicts applied in-place
-3.  **guidance-specification.md** (high): Path from context-package.json → finalized decisions with resolved conflicts (if conflict_risk was >= medium)
-
-#### Artifact-Task Mapping
-Artifacts are mapped to tasks based on their relevance to the task's domain.
-- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
-- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
-- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
-- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
-- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
-- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories
-
-This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
-
-## 8. Error Handling
-
-### Input Validation Errors
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Session not found | Invalid session ID | Verify session exists |
-| Context missing | Incomplete planning | Run context-gather first |
-| Invalid format | Corrupted results | Regenerate analysis |
-
-### Task Generation Errors
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Count exceeds limit | >10 tasks | Re-scope requirements |
-| Invalid structure | Missing fields | Fix analysis results |
-| Dependency cycle | Circular refs | Adjust dependencies |
-
-### Artifact Integration Errors
-| Error | Cause | Recovery |
-|-------|-------|----------|
-| Artifact not found | Missing output | Continue without artifacts |
-| Invalid format | Corrupted file | Skip artifact loading |
-| Path invalid | Moved/deleted | Update references |
-
-## 10. Usage & Related Commands
-
-**Basic Usage**:
-```bash
-/workflow:tools:task-generate --session WFS-auth [--cli-execute]
-```
-
-**Workflow Integration**:
-- Called by: `/workflow:plan` (task generation phase)
-- Followed by: `/workflow:execute`, `/workflow:status`
-
-**Related Commands**:
-- `/workflow:plan` - Orchestrates entire planning workflow
-- `/workflow:tools:context-gather` - Provides context package input
-- `/workflow:tools:conflict-resolution` - Provides conflict resolution (if needed)
-- `/workflow:execute` - Executes generated tasks

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

@@ -17,11 +17,43 @@ Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD work
 - Verify TDD cycle execution (Red -> Green -> Refactor)
 - Generate coverage and cycle reports
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session
+   └─ Validation: session_id REQUIRED
+
+Phase 1: Extract Test Tasks
+   └─ Find TEST-*.json files and extract focus_paths
+
+Phase 2: Run Test Suite
+   └─ Decision (test framework):
+      ├─ Node.js → npm test --coverage --json
+      ├─ Python → pytest --cov --json-report
+      └─ Other → [test_command] --coverage --json
+
+Phase 3: Parse Coverage Data
+   ├─ Extract line coverage percentage
+   ├─ Extract branch coverage percentage
+   ├─ Extract function coverage percentage
+   └─ Identify uncovered lines/branches
+
+Phase 4: Verify TDD Cycle
+   └─ FOR each TDD chain (TEST-N.M → IMPL-N.M → REFACTOR-N.M):
+      ├─ Red Phase: Verify tests created and failed initially
+      ├─ Green Phase: Verify tests now pass
+      └─ Refactor Phase: Verify code quality improved
+
+Phase 5: Generate Analysis Report
+   └─ Create tdd-cycle-report.md with coverage metrics and cycle verification
+```
+
 ## Execution Lifecycle
 
 ### 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 +61,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 +90,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 +101,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 +112,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 +122,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 +178,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,6 +304,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
 ```
 

.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 with test-context package
+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,42 @@ 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 Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session, --context
+   └─ Validation: Both REQUIRED
+
+Phase 1: Context Preparation (Command)
+   ├─ Load workflow-session.json
+   ├─ Verify test session type is "test-gen"
+   ├─ Validate test-context-package.json
+   └─ Determine strategy (Simple: 1-3 files | Medium: 4-6 | Complex: >6)
+
+Phase 2: Test Analysis Execution (Agent)
+   ├─ Execute Gemini analysis via cli-execution-agent
+   └─ Generate TEST_ANALYSIS_RESULTS.md
+
+Phase 3: Output Validation (Command)
+   ├─ Verify gemini-test-analysis.md exists
+   ├─ Validate TEST_ANALYSIS_RESULTS.md
+   └─ Confirm test requirements are actionable
+```
 
 ## 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,423 +64,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)
-
-### 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
+### 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
 

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

@@ -22,7 +22,37 @@ Orchestrator command that invokes `test-context-search-agent` to gather comprehe
 - **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
-- **Standardized Output**: Generate `.workflow/{test_session_id}/.process/test-context-package.json`
+- **Standardized Output**: Generate `.workflow/active/{test_session_id}/.process/test-context-package.json`
+
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session
+   └─ Validation: test_session_id REQUIRED
+
+Step 1: Test-Context-Package Detection
+   └─ Decision (existing package):
+      ├─ Valid package exists → Return existing (skip execution)
+      └─ No valid package → Continue to Step 2
+
+Step 2: Invoke Test-Context-Search Agent
+   ├─ Phase 1: Session Validation & Source Context Loading
+   │  ├─ Detection: Check for existing test-context-package
+   │  ├─ Test session validation
+   │  └─ Source context loading (summaries, changed files)
+   ├─ Phase 2: Test Coverage Analysis
+   │  ├─ Track 1: Existing test discovery
+   │  ├─ Track 2: Coverage gap analysis
+   │  └─ Track 3: Coverage statistics
+   └─ Phase 3: Framework Detection & Packaging
+      ├─ Framework identification
+      ├─ Convention analysis
+      └─ Generate test-context-package.json
+
+Step 3: Output Verification
+   └─ Verify test-context-package.json created
+```
 
 ## Execution Flow
 
@@ -164,7 +194,7 @@ Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-pac
 
 ## Success Criteria
 
-- ✅ Valid test-context-package.json generated in `.workflow/{test_session_id}/.process/`
+- ✅ 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

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

@@ -1,416 +1,247 @@
 ---
 name: test-task-generate
-description: Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase
+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
 ---
 
-# Autonomous Test Task Generation Command
+# Generate Test Planning Documents Command
 
 ## Overview
-Autonomous test-fix task JSON 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 specialized test-fix tasks with comprehensive test-fix-retest cycle specification.
+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
-- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
-- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
+- **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 advanced code analysis and test research
-- **Pre-Selected Templates**: Command selects correct test template based on `--cli-execute` flag **before** invoking agent
-- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **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
-- **Test-First**: Generate comprehensive test coverage before execution
-- **Iterative Refinement**: Test-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
+- **Leverage Existing Test Infrastructure**: Prioritize using established testing frameworks and tools present in the project
 
-## Execution Modes
+## Test-Specific 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
+- **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
+### 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
 
-## Execution Lifecycle
+## Execution Process
 
-### Phase 1: Discovery & Context Loading
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+```
+Input Parsing:
+   ├─ Parse flags: --session, --use-codex, --cli-execute
+   └─ Validation: session_id REQUIRED
 
-**Agent Context Package**:
-```javascript
-{
-  "session_id": "WFS-test-[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": "test_session",
-  "use_codex": true | false,  // Determined by --use-codex flag
-  "session_metadata": {
-    // If in memory: use cached content
-    // Else: Load from .workflow/{test-session-id}/workflow-session.json
-  },
-  "test_analysis_results_path": ".workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md",
-  "test_analysis_results": {
-    // If in memory: use cached content
-    // Else: Load from TEST_ANALYSIS_RESULTS.md
-  },
-  "test_context_package_path": ".workflow/{test-session-id}/.process/test-context-package.json",
-  "test_context_package": {
-    // Existing test patterns and coverage analysis
-  },
-  "source_session_id": "[source-session-id]",  // if exists
-  "source_session_summaries": {
-    // Implementation context from source session
-  },
-  "mcp_capabilities": {
-    "code_index": true,
-    "exa_code": true,
-    "exa_web": true
-  }
-}
+Phase 1: Context Preparation (Command)
+   ├─ Assemble test session paths
+   │  ├─ session_metadata_path
+   │  ├─ test_analysis_results_path (REQUIRED)
+   │  └─ test_context_package_path
+   └─ Provide metadata (session_id, execution_mode, use_codex, source_session_id)
+
+Phase 2: Test Document Generation (Agent)
+   ├─ Load TEST_ANALYSIS_RESULTS.md as primary requirements source
+   ├─ Generate Test Task JSON Files (.task/IMPL-*.json)
+   │  ├─ IMPL-001: Test generation (meta.type: "test-gen")
+   │  └─ IMPL-002+: Test execution & fix (meta.type: "test-fix")
+   ├─ Create IMPL_PLAN.md (test_session variant)
+   └─ Generate TODO_LIST.md with test phase indicators
 ```
 
-**Discovery Actions**:
-1. **Load Test Session Context** (if not in memory)
-   ```javascript
-   if (!memory.has("workflow-session.json")) {
-     Read(.workflow/{test-session-id}/workflow-session.json)
-   }
-   ```
+## Document Generation Lifecycle
 
-2. **Load TEST_ANALYSIS_RESULTS.md** (if not in memory, REQUIRED)
-   ```javascript
-   if (!memory.has("TEST_ANALYSIS_RESULTS.md")) {
-     Read(.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md)
-   }
-   ```
+### Phase 1: Context Preparation (Command Responsibility)
 
-3. **Load Test Context Package** (if not in memory)
-   ```javascript
-   if (!memory.has("test-context-package.json")) {
-     Read(.workflow/{test-session-id}/.process/test-context-package.json)
-   }
-   ```
+**Command prepares test session paths and metadata for planning document generation.**
 
-4. **Load Source Session Summaries** (if source_session_id exists)
-   ```javascript
-   if (sessionMetadata.source_session_id) {
-     const summaryFiles = Bash("find .workflow/{source-session-id}/.summaries/ -name 'IMPL-*-summary.md'")
-     summaryFiles.forEach(file => Read(file))
-   }
-   ```
-
-5. **Code Analysis with Native Tools** (optional - enhance understanding)
-   ```bash
-   # Find test files and patterns
-   find . -name "*test*" -type f
-   rg "describe|it\(|test\(" -g "*.ts"
-   ```
-
-6. **MCP External Research** (optional - gather test best practices)
-   ```javascript
-   // Get external test examples and patterns
-   mcp__exa__get_code_context_exa(
-     query="TypeScript test generation best practices jest",
-     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";
+**Test Session Path Structure**:
 ```
+.workflow/active/WFS-test-{session-id}/
+├── workflow-session.json          # Test session metadata
+├── .process/
+│   ├── 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
+```
+
+**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
+
+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)
+
+### Phase 2: Test Document Generation (Agent Responsibility)
+
+**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-fix task JSON and implementation plan",
+  description="Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
   prompt=`
-## Execution Context
+## TASK OBJECTIVE
+Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for test workflow session
 
-**Session ID**: WFS-test-{session-id}
-**Workflow Type**: Test Session
-**Execution Mode**: {agent-mode | cli-execute-mode}
-**Task JSON Template Path**: {template_path}
-**Use Codex**: {true | false}
+IMPORTANT: This is TEST PLANNING ONLY - you are generating planning documents, NOT executing tests.
 
-## Phase 1: Discovery Results (Provided Context)
+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)
 
-### Test Session Metadata
-{session_metadata_content}
-- source_session_id: {source_session_id} (if exists)
-- workflow_type: "test_session"
+## AGENT CONFIGURATION REFERENCE
+All test task generation rules, schemas, and quality standards are defined in your agent specification:
+@.claude/agents/action-planning-agent.md
 
-### TEST_ANALYSIS_RESULTS.md (REQUIRED)
-{test_analysis_results_content}
-- Coverage Assessment
-- Test Framework & Conventions
-- Test Requirements by File
-- Test Generation Strategy
-- Implementation Targets
-- Success Criteria
+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)
 
-### Test Context Package
-{test_context_package_summary}
-- Existing test patterns, framework config, coverage analysis
+## 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)
 
-### Source Session Implementation Context (Optional)
-{source_session_summaries}
-- Implementation context from completed session
+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
 
-### MCP Analysis Results (Optional)
-**Code Structure**: {mcp_code_index_results}
-**External Research**: {mcp_exa_research_results}
+## 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}
 
-## Phase 2: Test Task Document Generation
+## TEST-SPECIFIC REQUIREMENTS SUMMARY
+(Detailed specifications in your agent definition)
 
-**Agent Configuration Reference**: All test task generation rules, test-fix cycle structure, quality standards, and execution details are defined in action-planning-agent.
+### 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)
 
-Refer to: @.claude/agents/action-planning-agent.md for:
-- Test Task Decomposition Standards
-- Test-Fix-Retest Cycle Requirements
-- 5-Field Task JSON Schema
-- IMPL_PLAN.md Structure (Test variant)
-- TODO_LIST.md Format
-- Test Execution Flow & Quality Validation
+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
 
-### Test-Specific Requirements Summary
+  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
 
-#### Task Structure Philosophy
-- **Minimum 2 tasks**: IMPL-001 (test generation) + IMPL-002 (test execution & fix)
-- **Expandable**: Add IMPL-003+ for complex projects (per-module, integration, etc.)
-- IMPL-001: Uses @code-developer or CLI execution
-- IMPL-002: Uses @test-fix-agent with iterative fix cycle
+### 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-Fix Cycle Configuration
-- **Max Iterations**: 5 (for IMPL-002)
-- **Diagnosis Tool**: Gemini with bug-fix template
-- **Fix Application**: Manual (default) or Codex (if --use-codex flag)
-- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
-- **Exit Conditions**: All tests pass OR max iterations reached (auto-revert)
+### 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)
 
-#### Required Outputs Summary
+## 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
 
-##### 1. Test Task JSON Files (.task/IMPL-*.json)
-- **Location**: `.workflow/{test-session-id}/.task/`
-- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
-- **Schema**: 5-field structure with test-specific metadata
-  - IMPL-001: `meta.type: "test-gen"`, `meta.agent: "@code-developer"`
-  - IMPL-002: `meta.type: "test-fix"`, `meta.agent: "@test-fix-agent"`, `meta.use_codex: {use_codex}`
-  - `flow_control`: Test generation approach (IMPL-001) or test-fix cycle (IMPL-002)
-- **Details**: See action-planning-agent.md § Test Task JSON Generation
+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)
 
-##### 2. IMPL_PLAN.md (Test Variant)
-- **Location**: `.workflow/{test-session-id}/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**: Iterative fix cycle with Gemini diagnosis
-- **Details**: See action-planning-agent.md § Test Implementation Plan Creation
+3. TODO List (TODO_LIST.md)
+   - Hierarchical structure with test phase containers
+   - Links to task JSONs with status markers
+   - Matches task JSON hierarchy
 
-##### 3. TODO_LIST.md
-- **Location**: `.workflow/{test-session-id}/TODO_LIST.md`
-- **Format**: Task list with test generation and execution phases
-- **Status**: [ ] (pending), [x] (completed)
-- **Details**: See action-planning-agent.md § TODO List Generation
+## 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
 
-### Agent Execution Summary
-
-**Key Steps** (Detailed instructions in action-planning-agent.md):
-1. Load task JSON template from provided path
-2. Parse TEST_ANALYSIS_RESULTS.md for test requirements
-3. Generate IMPL-001 (test generation) task JSON
-4. Generate IMPL-002 (test execution & fix) task JSON with use_codex flag
-5. Generate additional IMPL-*.json if project complexity requires
-6. Create IMPL_PLAN.md using test template variant
-7. Generate TODO_LIST.md with test task indicators
-8. Update session state with test metadata
-
-**Quality Gates** (Full checklist in action-planning-agent.md):
-- ✓ Minimum 2 tasks created (IMPL-001 + IMPL-002)
-- ✓ IMPL-001 has test generation approach from TEST_ANALYSIS_RESULTS.md
-- ✓ IMPL-002 has test-fix cycle with correct use_codex flag
-- ✓ Test framework configuration integrated
-- ✓ Source session context referenced (if exists)
-- ✓ MCP tool integration added
-- ✓ Documents follow test template structure
-
-## Output
-
-Generate all three documents and report completion status:
-- Test task JSON files created: N files (minimum 2)
-- Test requirements integrated: TEST_ANALYSIS_RESULTS.md
-- Test context integrated: existing patterns and coverage
-- Source session context: {source_session_id} summaries (if exists)
-- MCP enhancements: code-index, exa-research
-- Session ready for test execution: /workflow:execute or /workflow:test-cycle-execute
+## SUCCESS CRITERIA
+- All test planning documents generated successfully
+- Return completion status: task count, test framework, coverage targets, source session status
 `
 )
 ```
 
-### Agent Context Passing
-
-**Memory-Aware Context Assembly**:
-```javascript
-// Assemble context package for agent
-const agentContext = {
-  session_id: "WFS-test-[id]",
-  workflow_type: "test_session",
-  use_codex: hasUseCodexFlag,
-
-  // Use memory if available, else load
-  session_metadata: memory.has("workflow-session.json")
-    ? memory.get("workflow-session.json")
-    : Read(.workflow/WFS-test-[id]/workflow-session.json),
-
-  test_analysis_results_path: ".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",
-
-  test_analysis_results: memory.has("TEST_ANALYSIS_RESULTS.md")
-    ? memory.get("TEST_ANALYSIS_RESULTS.md")
-    : Read(".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),
-
-  test_context_package_path: ".workflow/WFS-test-[id]/.process/test-context-package.json",
-
-  test_context_package: memory.has("test-context-package.json")
-    ? memory.get("test-context-package.json")
-    : Read(".workflow/WFS-test-[id]/.process/test-context-package.json"),
-
-  // Load source session summaries if exists
-  source_session_id: session_metadata.source_session_id || null,
-
-  source_session_summaries: session_metadata.source_session_id
-    ? loadSourceSummaries(session_metadata.source_session_id)
-    : null,
-
-  // Optional MCP enhancements
-  mcp_analysis: executeMcpDiscovery()
-}
-```
-
-## Test Task Structure Reference
-
-This section provides quick reference for test task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
-
-**Quick Reference**:
-- Minimum 2 tasks: IMPL-001 (test-gen) + IMPL-002 (test-fix)
-- Expandable for complex projects (IMPL-003+)
-- IMPL-001: `meta.agent: "@code-developer"`, test generation approach
-- IMPL-002: `meta.agent: "@test-fix-agent"`, `meta.use_codex: {flag}`, test-fix cycle
-- See Phase 2 agent prompt for full schema and requirements
-
-## Output Files Structure
-```
-.workflow/WFS-test-[session]/
-├── workflow-session.json           # Test session metadata
-├── IMPL_PLAN.md                    # Test validation plan
-├── TODO_LIST.md                    # Progress tracking
-├── .task/
-│   └── IMPL-001.json               # Test-fix task with cycle spec
-├── .process/
-│   ├── ANALYSIS_RESULTS.md         # From concept-enhanced (optional)
-│   ├── context-package.json        # From context-gather
-│   ├── initial-test.log            # Phase 1: Initial test results
-│   ├── fix-iteration-1-diagnosis.md # Gemini diagnosis iteration 1
-│   ├── fix-iteration-1-changes.log  # Codex changes iteration 1
-│   ├── fix-iteration-1-retest.log   # Retest results iteration 1
-│   ├── fix-iteration-N-*.md/log    # Subsequent iterations
-│   └── final-test.log              # Phase 3: Final validation
-└── .summaries/
-    └── IMPL-001-summary.md         # Success report OR failure report
-```
-
-## Error Handling
-
-### Input Validation Errors
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Not a test session | Missing workflow_type: "test_session" | Verify session created by test-gen |
-| Source session not found | Invalid source_session_id | Check source session exists |
-| No implementation summaries | Source session incomplete | Ensure source session has completed tasks |
-
-### Test Framework Discovery Errors
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| No test command found | Unknown framework | Manual test command specification |
-| No test files found | Tests not written | Request user to write tests first |
-| Test dependencies missing | Incomplete setup | Run dependency installation |
-
-### Generation Errors
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Invalid JSON structure | Template error | Fix task generation logic |
-| Missing required fields | Incomplete metadata | Validate session metadata |
-
 ## Integration & Usage
 
 ### Command Chain
 - **Called By**: `/workflow:test-gen` (Phase 4), `/workflow:test-fix-gen` (Phase 4)
-- **Invokes**: `action-planning-agent` for autonomous task generation
-- **Followed By**: `/workflow:execute` or `/workflow:test-cycle-execute` (user-triggered)
+- **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
-# Agent mode (default, autonomous execution)
+# Agent mode (default)
 /workflow:tools:test-task-generate --session WFS-test-auth
 
-# With automated Codex fixes for IMPL-002
+# With automated Codex fixes
 /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
 
-# CLI execution mode for IMPL-001 test generation
+# CLI execution mode for test generation
 /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
-
-# Both flags combined
-/workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
 ```
 
-### Execution Modes
-- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
-- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen/Codex with cli-mode task template for IMPL-001
-- **Codex fixes** (`--use-codex`): Enables automated fixes in IMPL-002 task
-
 ### Flag Behavior
-- **No flags**: `meta.use_codex=false` (manual fixes), agent-mode generation
-- **--use-codex**: `meta.use_codex=true` (Codex automated fixes with resume mechanism in IMPL-002)
-- **--cli-execute**: Uses CLI tool execution mode for IMPL-001 test generation
+- **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
 
 ### Output
-- Test task JSON files in `.task/` directory (minimum 2: IMPL-001.json + IMPL-002.json)
-- IMPL_PLAN.md with test generation and fix cycle strategy
-- TODO_LIST.md with test task indicators
-- Session state updated with test metadata
-- MCP enhancements integrated (if available)
-
-## 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 `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` template for systematic root cause analysis, code path tracing, and targeted fix recommendations.
-
-**Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.
+- 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/animation-extract.md

@@ -23,6 +23,44 @@ Extract animation and transition patterns from prompt inference and image refere
 - **Production-Ready**: CSS var() format, WCAG-compliant, semantic naming
 - **Default Behavior**: Non-interactive mode uses inferred patterns + best practices
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --design-id, --session, --images, --focus, --interactive, --refine
+   └─ Decision (mode detection):
+      ├─ --refine flag → Refinement Mode
+      └─ No --refine → Exploration Mode
+
+Phase 0: Setup & Input Validation
+   ├─ Step 1: Detect input mode & base path
+   ├─ Step 2: Prepare image references (if available)
+   ├─ Step 3: Load design tokens context
+   └─ Step 4: Memory check (skip if exists)
+
+Phase 1: Animation Specification Generation
+   ├─ Step 1: Load project context
+   ├─ Step 2: Generate animation specification options (Agent Task 1)
+   │  └─ Decision:
+   │     ├─ Exploration Mode → Generate specification questions
+   │     └─ Refinement Mode → Generate refinement options
+   └─ Step 3: Verify options file created
+
+Phase 1.5: User Confirmation (Optional)
+   └─ Decision (--interactive flag):
+      ├─ --interactive present → Present options, capture selection
+      └─ No --interactive → Skip to Phase 2
+
+Phase 2: Animation System Generation
+   ├─ Step 1: Load user selection or use defaults
+   ├─ Step 2: Create output directory
+   └─ Step 3: Launch animation generation task (Agent Task 2)
+
+Phase 3: Verify Output
+   ├─ Step 1: Check files created
+   └─ Step 2: Verify file sizes
+```
+
 ## Phase 0: Setup & Input Validation
 
 ### Step 1: Detect Input Mode & Base Path
@@ -67,7 +105,7 @@ if [ -n "$DESIGN_ID" ]; then
   relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
 elif [ -n "$SESSION_ID" ]; then
   # Latest in session
-  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  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)
@@ -120,11 +158,7 @@ ELSE:
 - Infers animation patterns from UI element positioning and design style
 - Generates context-aware animation specifications based on visual analysis
 
-**Benefits**:
-- ✅ Flexible input - works with screenshots, mockups, or design files
-- ✅ AI-driven inference from visual cues
-- ✅ No external dependencies on MCP tools
-- ✅ Combines visual analysis with industry best practices
+
 
 ### Step 3: Load Design Tokens Context
 

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

@@ -480,11 +480,7 @@ TodoWrite({todos: [
 //    - Orchestrator's own task (no SlashCommand attachment)
 //    - Mark Phase 3 as completed
 //    - Final state: All 4 orchestrator tasks completed
-//
-// Benefits:
-// ✓ Real-time visibility into attached tasks during execution
-// ✓ Clean orchestrator-level summary after tasks complete
-// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+
 // ✓ Dynamic attachment/collapse maintains clarity
 ```
 
@@ -623,17 +619,7 @@ File discovery is fully automatic - no glob patterns needed.
 
 ---
 
-## Benefits
 
-- **Simplified Interface**: Single path parameter with intelligent defaults
-- **Auto-Generation**: Package names auto-generated from directory names
-- **Automatic Discovery**: No need to specify file patterns - finds all style files automatically
-- **Pure Orchestrator**: No direct agent execution, delegates to specialized commands
-- **Auto-Continue**: Autonomous 4-phase execution without user interaction
-- **Safety First**: Overwrite protection, validation checks, error handling
-- **Code Reuse**: Leverages existing `import-from-code` and `reference-page-generator` commands
-- **Clean Separation**: Each command has single responsibility
-- **Easy Maintenance**: Changes to sub-commands automatically apply
 
 ## Architecture
 

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

@@ -19,16 +19,58 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
 - **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
 - **Minimal Reading**: Verify file existence, don't read design content
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --session, --selected-prototypes
+   └─ Validation: session_id REQUIRED
+
+Phase 1: Session & Artifact Validation
+   ├─ Step 1: Validate session exists
+   ├─ Step 2: Find latest design run
+   ├─ Step 3: Detect design system structure
+   └─ Step 4: Select prototypes (--selected-prototypes OR all)
+
+Phase 1.1: Memory Check (Conditional)
+   └─ Decision (current design run in synthesis):
+      ├─ Already updated → Skip Phase 2-5, EXIT
+      └─ Not found → Continue to Phase 2
+
+Phase 2: Load Target Artifacts
+   ├─ Read role analysis documents (files to update)
+   ├─ Read ui-designer/analysis.md (if exists)
+   └─ Read prototype notes (minimal context)
+
+Phase 3: Update Synthesis Specification
+   └─ Edit role analysis documents with UI/UX Guidelines section
+
+Phase 4A: Update Relevant Role Analysis Documents
+   ├─ ui-designer/analysis.md (always)
+   ├─ ux-expert/analysis.md (if animations exist)
+   ├─ system-architect/analysis.md (if layouts exist)
+   └─ product-manager/analysis.md (if prototypes)
+
+Phase 4B: Create UI Designer Design System Reference
+   └─ Write ui-designer/design-system-reference.md
+
+Phase 5: Update Context Package
+   └─ Update context-package.json with design system references
+
+Phase 6: Completion
+   └─ Report updated artifacts
+```
+
 ## Execution Protocol
 
 ### Phase 1: Session & Artifact Validation
 
 ```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-run-*")
+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 +93,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 +110,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:
@@ -113,7 +155,7 @@ Update `.brainstorming/role analysis documents` with design system references.
 **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 +170,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**:
@@ -223,11 +265,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 +362,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

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

@@ -24,8 +24,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
    - **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** → Auto-continues to Phase 11
-7. **Phase 11 (preview-generation)** → **Execute script → Generate preview files** → Reports completion
+6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Workflow complete
 
 **Phase Transition Mechanism**:
 - **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7
@@ -33,15 +32,59 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 - **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
-- **Phase 11 (Script Execution)**: Execute preview generation script
 - No additional user interaction after Phase 5 confirmation
 
-**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 11 (preview generation).
+**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`.
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --input, --targets, --target-type, --device-type, --session, --style-variants, --layout-variants
+   └─ Decision (input detection):
+      ├─ Contains * or glob matches → images_input (visual)
+      ├─ File/directory exists → code import source
+      └─ Pure text → design prompt
+
+Phase 1-4: Parameter Parsing & Initialization
+   ├─ Phase 1: Normalize parameters (legacy deprecation warning)
+   ├─ Phase 2: Intelligent prompt parsing (extract variant counts)
+   ├─ Phase 3: Device type inference (explicit > keywords > target_type > default)
+   └─ Phase 4: Run initialization and directory setup
+
+Phase 5: Unified Target Inference
+   ├─ Priority: --pages/--components (legacy) → --targets → prompt analysis → synthesis → default
+   ├─ Display confirmation with modification options
+   └─ User confirms → IMMEDIATELY triggers Phase 7
+
+Phase 6: Code Import (Conditional)
+   └─ Decision (design_source):
+      ├─ code_only | hybrid → Execute /workflow:ui-design:import-from-code
+      └─ visual_only → Skip to Phase 7
+
+Phase 7: Style Extraction
+   └─ Decision (needs_visual_supplement):
+      ├─ visual_only OR supplement needed → Execute /workflow:ui-design:style-extract
+      └─ code_only AND style_complete → Use code import
+
+Phase 8: Animation Extraction
+   └─ Decision (should_extract_animation):
+      ├─ visual_only OR incomplete OR regenerate → Execute /workflow:ui-design:animation-extract
+      └─ code_only AND animation_complete → Use code import
+
+Phase 9: Layout Extraction
+   └─ Decision (needs_visual_supplement OR NOT layout_complete):
+      ├─ True → Execute /workflow:ui-design:layout-extract
+      └─ False → Use code import
+
+Phase 10: UI Assembly
+   └─ Execute /workflow:ui-design:generate → Workflow complete
+```
+
 ## Core Rules
 
 1. **Start Immediately**: TodoWrite initialization → Phase 7 execution
@@ -50,7 +93,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 4. **Default to All**: When selecting variants/prototypes, use ALL generated items
 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 11 (preview generation).
+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
 
@@ -127,145 +170,83 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 **Integrated vs. Standalone**:
 - `--session` flag determines session integration or standalone execution
 
-## 11-Phase Execution
+## 10-Phase Execution
 
 ### Phase 1: Parameter Parsing & Input Detection
+
+**Unified Principle**: Detect → Classify → Store (avoid string concatenation and escaping)
+
+**Step 1: Parameter Normalization**
 ```bash
-# Step 0: Parse and normalize parameters
-images_input = null
-prompt_text = null
-
-# Handle legacy parameters with deprecation warning
+# Legacy parameters (deprecated)
 IF --images OR --prompt:
-    WARN: "⚠️  DEPRECATION: --images and --prompt are deprecated. Use --input instead."
-    WARN: "   Example: --input \"design-refs/*\" or --input \"modern dashboard\""
-    images_input = --images
-    prompt_text = --prompt
+    WARN: "⚠️ --images/--prompt deprecated. Use --input"
+    images_input = --images; prompt_text = --prompt
 
-# Parse unified --input parameter
-IF --input:
-    # Split by | separator for multiple inputs
-    input_parts = split(--input, "|")
-
-    FOR part IN input_parts:
-        part = trim(part)
-
-        # Detection logic
-        IF contains(part, "*") OR glob_matches_files(part):
-            # Glob pattern detected → images
-            images_input = part
-        ELSE IF file_or_directory_exists(part):
-            # File/directory path → will be handled in code detection
-            IF NOT prompt_text:
-                prompt_text = part
-            ELSE:
-                prompt_text = prompt_text + " " + part
-        ELSE:
-            # Pure text → prompt
-            IF NOT prompt_text:
-                prompt_text = part
-            ELSE:
-                prompt_text = prompt_text + " " + part
-
-# Step 1: Detect design source from parsed inputs
-code_files_detected = false
-code_base_path = null
-has_visual_input = false
-
-IF prompt_text:
-    # Extract potential file paths from prompt
-    potential_paths = extract_paths_from_text(prompt_text)
-    FOR path IN potential_paths:
-        IF file_or_directory_exists(path):
-            code_files_detected = true
-            code_base_path = path
-            BREAK
-
-IF images_input:
-    # Check if images parameter points to existing files
-    IF glob_matches_files(images_input):
-        has_visual_input = true
-
-# Step 2: Determine design source strategy
-design_source = "unknown"
-IF code_files_detected AND has_visual_input:
-    design_source = "hybrid"  # Both code and visual
-ELSE IF code_files_detected:
-    design_source = "code_only"  # Only code files
-ELSE IF has_visual_input OR --prompt:
-    design_source = "visual_only"  # Only visual/prompt
-ELSE:
-    ERROR: "No design source provided (code files, images, or prompt required)"
-    EXIT 1
-
-STORE: design_source, code_base_path, has_visual_input
+# 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
 ```
 
+**Step 2: Design Source Detection**
+```bash
+code_base_path = extract_first_valid_path(prompt_text)
+has_visual_input = (images_input AND glob_exists(images_input))
+
+design_source = classify_source(code_base_path, has_visual_input):
+    • code + visual → "hybrid"
+    • code only → "code_only"
+    • visual/prompt → "visual_only"
+    • none → ERROR
+```
+
+**Stored Variables**: `design_source`, `code_base_path`, `has_visual_input`, `images_input`, `prompt_text`
+
+---
+
 ### Phase 2: Intelligent Prompt Parsing
+
+**Unified Principle**: explicit > inferred > default
+
 ```bash
-# Parse variant counts from prompt or use explicit/default values
-IF prompt_text AND (NOT --style-variants OR NOT --layout-variants):
-    style_variants = regex_extract(prompt_text, r"(\d+)\s*style") OR --style-variants OR 3
-    layout_variants = regex_extract(prompt_text, r"(\d+)\s*layout") OR --layout-variants OR 3
-ELSE:
-    style_variants = --style-variants OR 3
-    layout_variants = --layout-variants OR 3
+# 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
 
-VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
-
-# Interactive mode (always enabled)
-interactive_mode = true  # Always use interactive mode
+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 inference
-device_type = "auto"
+# 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"
 
-# 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_text:
-        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_text, device_keywords)
-        IF detected_device:
-            device_type = detected_device
-            device_source = "prompt_inference"
-
-    # Step 3: Target type inference
-    IF device_type == "auto":
-        # Components are typically desktop-first, pages can vary
-        device_type = target_type == "component" ? "desktop" : "responsive"
-        device_source = "target_type_inference"
-
-STORE: device_type, device_source
+device_source = track_detection_source()
 ```
 
-**Device Type Presets**:
-- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
-- **Mobile**: 375×812px - Touch-friendly, compact layouts
-- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
-- **Responsive**: 1920×1080px base with mobile-first breakpoints
+**Detection Keywords**: mobile, phone, smartphone → mobile | desktop, web, laptop → desktop | tablet, ipad → tablet | responsive, adaptive → responsive
 
-**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)
+**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/WFS-{session}/${design_id}" : ".workflow/${design_id}"
+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")
@@ -466,13 +447,13 @@ IF design_source IN ["code_only", "hybrid"]:
 
     # Animation reuse confirmation (code import with complete animations)
     IF design_source == "code_only" AND animation_complete:
-        REPORT: "✅ 检测到完整的动画系统（来自代码导入）"
+        REPORT: "✅ Complete animation system detected (from code import)"
         REPORT: "   Duration scales: {duration_count} | Easing functions: {easing_count}"
         REPORT: ""
         REPORT: "Options:"
-        REPORT: "  • 'reuse' (默认) - 复用已有动画系统"
-        REPORT: "  • 'regenerate' - 重新生成动画系统（交互式）"
-        REPORT: "  • 'cancel' - 取消工作流"
+        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
@@ -580,63 +561,22 @@ REPORT: "   → Assembly tasks: {total} combinations"
 SlashCommand(command)
 
 # After executing all attached tasks, collapse them into phase summary
-# When phase finishes, IMMEDIATELY execute Phase 11 (auto-continue)
-# Output:
+# 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
-# Note: compare.html and PREVIEW.md will be generated in Phase 11
-```
-
-### Phase 11: Generate Preview Files
-```bash
-REPORT: "🚀 Phase 11: Generate Preview Files"
-
-# Update TodoWrite to reflect preview generation phase
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
-  {"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
-  {"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
-  {"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
-  {"content": "Generate preview files", "status": "in_progress", "activeForm": "Generating preview files"}
-]})
-
-# Execute preview generation script
-Bash(~/.claude/scripts/ui-generate-preview.sh "${base_path}/prototypes")
-
-# Verify output files
-IF NOT exists("${base_path}/prototypes/compare.html"):
-    ERROR: "Preview generation failed: compare.html not found"
-    EXIT 1
-
-IF NOT exists("${base_path}/prototypes/PREVIEW.md"):
-    ERROR: "Preview generation failed: PREVIEW.md not found"
-    EXIT 1
-
-# Mark preview generation as complete
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
-  {"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
-  {"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
-  {"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
-  {"content": "Generate preview files", "status": "completed", "activeForm": "Generating preview files"}
-]})
-
-REPORT: "✅ Preview files generated successfully"
-REPORT: "   → compare.html (interactive matrix view)"
-REPORT: "   → PREVIEW.md (usage instructions)"
-
-# Workflow complete, display final report
+# - compare.html (interactive matrix view)
+# - PREVIEW.md (usage instructions)
 ```
 
 ## TodoWrite Pattern
 ```javascript
-// Initialize IMMEDIATELY after Phase 5 user confirmation to track multi-phase execution (5 orchestrator-level tasks)
+// 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 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"},
-  {"content": "Generate preview files", "status": "pending", "activeForm": "Generating preview files"}
+  {"content": "Phase 7: Style Extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
+  {"content": "Phase 8: Animation Extraction", "status": "pending", "activeForm": "Executing animation extraction"},
+  {"content": "Phase 9: Layout Extraction", "status": "pending", "activeForm": "Executing layout extraction"},
+  {"content": "Phase 10: UI Assembly", "status": "pending", "activeForm": "Executing UI assembly"}
 ]})
 
 // ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
@@ -644,26 +584,24 @@ TodoWrite({todos: [
 // **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)
+// Phase 7-10 SlashCommand Invocation Pattern (when tasks are attached):
+// Example - Phase 7 with sub-tasks:
+// [
+//   {"content": "Phase 7: Style Extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
+//   {"content": "  → Analyze style references", "status": "in_progress", "activeForm": "Analyzing style references"},
+//   {"content": "  → Generate style variants", "status": "pending", "activeForm": "Generating style variants"},
+//   {"content": "  → Create design tokens", "status": "pending", "activeForm": "Creating design tokens"},
+//   {"content": "Phase 8: Animation Extraction", "status": "pending", "activeForm": "Executing animation extraction"},
+//   ...
+// ]
 //
-// Phase 11 Script Execution Pattern:
-// 1. Mark "Generate preview files" as in_progress
-// 2. Execute preview generation script via Bash tool
-// 3. Verify output files (compare.html, PREVIEW.md)
-// 4. Mark "Generate preview files" as completed
+// After sub-tasks complete, COLLAPSE back to:
+// [
+//   {"content": "Phase 7: Style Extraction", "status": "completed", "activeForm": "Executing style extraction"},
+//   {"content": "Phase 8: Animation Extraction", "status": "in_progress", "activeForm": "Executing animation extraction"},
+//   ...
+// ]
 //
-// Benefits:
-// ✓ Real-time visibility into sub-command task progress
-// ✓ Clean orchestrator-level summary after each phase
-// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
-// ✓ Script execution for preview generation (no delegation)
-// ✓ Dynamic attachment/collapse maintains clarity
 ```
 
 ## Completion Output
@@ -682,7 +620,7 @@ Phase 9: {n×l} layout templates (layout-extract with multi-select)
 Phase 10: UI Assembly (generate)
   - Pure assembly: layout templates + design tokens
   - {s}×{l}×{n} = {total} final prototypes
-Phase 11: Preview files generated (compare.html, PREVIEW.md)
+  - Preview files: compare.html, PREVIEW.md (auto-generated by generate command)
 
 Assembly Process:
 ✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate

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

@@ -21,6 +21,36 @@ Pure assembler that combines pre-extracted layout templates with design tokens t
 - `/workflow:ui-design:style-extract` → Complete design systems (design-tokens.json + style-guide.md)
 - `/workflow:ui-design:layout-extract` → Layout structure
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --design-id, --session
+   └─ Decision (base path resolution):
+      ├─ --design-id provided → Exact match by design ID
+      ├─ --session provided → Latest in session
+      └─ No flags → Latest globally
+
+Phase 1: Setup & Validation
+   ├─ Step 1: Resolve base path & parse configuration
+   ├─ Step 2: Load layout templates
+   ├─ Step 3: Validate design tokens
+   └─ Step 4: Load animation tokens (optional)
+
+Phase 2: Assembly (Agent)
+   ├─ Step 1: Calculate agent grouping plan
+   │  └─ Grouping rules:
+   │     ├─ Style isolation: Each agent processes ONE style
+   │     ├─ Balanced distribution: Layouts evenly split
+   │     └─ Max 10 layouts per agent, max 6 concurrent agents
+   ├─ Step 2: Launch batched assembly tasks (parallel)
+   └─ Step 3: Verify generated files
+
+Phase 3: Generate Preview Files
+   ├─ Step 1: Run preview generation script
+   └─ Step 2: Verify preview files
+```
+
 ## Phase 1: Setup & Validation
 
 ### Step 1: Resolve Base Path & Parse Configuration
@@ -31,7 +61,7 @@ if [ -n "$DESIGN_ID" ]; then
   relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
 elif [ -n "$SESSION_ID" ]; then
   # Latest in session
-  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  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)

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

@@ -36,6 +36,50 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 
 **Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --input, --session (legacy: --images, --prompt)
+   └─ Decision (input detection):
+      ├─ Contains * or glob matches → images_input (visual)
+      ├─ File/directory exists → code import source
+      └─ Pure text → design prompt
+
+Phase 0: Parameter Parsing & Input Detection
+   ├─ Step 1: Normalize parameters (legacy deprecation warning)
+   ├─ Step 2: Detect design source (hybrid | code_only | visual_only)
+   └─ Step 3: Initialize directories and metadata
+
+Phase 0.5: Code Import (Conditional)
+   └─ Decision (design_source):
+      ├─ hybrid → Execute /workflow:ui-design:import-from-code
+      └─ Other → Skip to Phase 2
+
+Phase 2: Style Extraction
+   └─ Decision (skip_style):
+      ├─ code_only AND style_complete → Use code import
+      └─ Otherwise → Execute /workflow:ui-design:style-extract
+
+Phase 2.3: Animation Extraction
+   └─ Decision (skip_animation):
+      ├─ code_only AND animation_complete → Use code import
+      └─ Otherwise → Execute /workflow:ui-design:animation-extract
+
+Phase 2.5: Layout Extraction
+   └─ Decision (skip_layout):
+      ├─ code_only AND layout_complete → Use code import
+      └─ Otherwise → Execute /workflow:ui-design:layout-extract
+
+Phase 3: UI Assembly
+   └─ Execute /workflow:ui-design:generate
+
+Phase 4: Design System Integration
+   └─ Decision (session_id):
+      ├─ Provided → Execute /workflow:ui-design:update
+      └─ Not provided → Standalone completion
+```
+
 ## Core Rules
 
 1. **Start Immediately**: TodoWrite initialization → Phase 2 execution
@@ -67,7 +111,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 
 **Optional Parameters**:
 - `--session <id>`: Workflow session ID
-  - Integrate into existing session (`.workflow/WFS-{session}/`)
+  - Integrate into existing session (`.workflow/active/WFS-{session}/`)
   - Enable automatic design system integration (Phase 4)
   - If not provided: standalone mode (`.workflow/`)
 
@@ -98,7 +142,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 **Session Integration**:
 - `--session` flag determines session integration or standalone execution
 - Integrated: Design system automatically added to session artifacts
-- Standalone: Output in `.workflow/{run_id}/`
+- Standalone: Output in `.workflow/active/{run_id}/`
 
 ## 5-Phase Execution
 
@@ -184,11 +228,11 @@ design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
 
 IF --session:
     session_id = {provided_session}
-    relative_base_path = ".workflow/WFS-{session_id}/{design_id}"
+    relative_base_path = ".workflow/active/WFS-{session_id}/{design_id}"
     session_mode = "integrated"
 ELSE:
     session_id = null
-    relative_base_path = ".workflow/{design_id}"
+    relative_base_path = ".workflow/active/{design_id}"
     session_mode = "standalone"
 
 # Create base directory and convert to absolute path
@@ -570,12 +614,12 @@ ELSE:
 ```javascript
 // Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution (6 orchestrator-level tasks)
 TodoWrite({todos: [
-  {content: "Initialize and detect design source", status: "in_progress", activeForm: "Initializing"},
-  {content: "Extract style (complete design systems)", status: "pending", activeForm: "Extracting style"},
-  {content: "Extract animation (CSS auto mode)", status: "pending", activeForm: "Extracting animation"},
-  {content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
-  {content: "Assemble UI prototypes", status: "pending", activeForm: "Assembling UI"},
-  {content: "Integrate design system", status: "pending", activeForm: "Integrating"}
+  {content: "Phase 0: Initialize and Detect Design Source", status: "in_progress", activeForm: "Initializing"},
+  {content: "Phase 2: Style Extraction", status: "pending", activeForm: "Extracting style"},
+  {content: "Phase 2.3: Animation Extraction", status: "pending", activeForm: "Extracting animation"},
+  {content: "Phase 2.5: Layout Extraction", status: "pending", activeForm: "Extracting layout"},
+  {content: "Phase 3: UI Assembly", status: "pending", activeForm: "Assembling UI"},
+  {content: "Phase 4: Design System Integration", status: "pending", activeForm: "Integrating"}
 ]})
 
 // ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
@@ -583,19 +627,26 @@ TodoWrite({todos: [
 // **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
 // Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
 //
-// Phase 2-4 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 SlashCommand (auto-continue)
+// Phase 2-4 SlashCommand Invocation Pattern (when tasks are attached):
+// Example - Phase 2 with sub-tasks:
+// [
+//   {"content": "Phase 0: Initialize and Detect Design Source", "status": "completed", "activeForm": "Initializing"},
+//   {"content": "Phase 2: Style Extraction", "status": "in_progress", "activeForm": "Extracting style"},
+//   {"content": "  → Analyze design references", "status": "in_progress", "activeForm": "Analyzing references"},
+//   {"content": "  → Generate design tokens", "status": "pending", "activeForm": "Generating tokens"},
+//   {"content": "  → Create style guide", "status": "pending", "activeForm": "Creating guide"},
+//   {"content": "Phase 2.3: Animation Extraction", "status": "pending", "activeForm": "Extracting animation"},
+//   ...
+// ]
+//
+// After sub-tasks complete, COLLAPSE back to:
+// [
+//   {"content": "Phase 0: Initialize and Detect Design Source", "status": "completed", "activeForm": "Initializing"},
+//   {"content": "Phase 2: Style Extraction", "status": "completed", "activeForm": "Extracting style"},
+//   {"content": "Phase 2.3: Animation Extraction", "status": "in_progress", "activeForm": "Extracting animation"},
+//   ...
+// ]
 //
-// Benefits:
-// ✓ Real-time visibility into sub-command task progress
-// ✓ Clean orchestrator-level summary after each phase
-// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
-// ✓ Dynamic attachment/collapse maintains clarity
 ```
 
 ## Error Handling

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

@@ -43,6 +43,25 @@ Extract design system tokens from source code files (CSS/SCSS/JS/TS/HTML) using
 
 ## Execution Process
 
+```
+Input Parsing:
+   ├─ Parse flags: --design-id, --session, --source
+   └─ Decision (base path resolution):
+      ├─ --design-id provided → Exact match by design ID
+      ├─ --session provided → Latest design run in session
+      └─ Neither → ERROR: Must provide --design-id or --session
+
+Phase 0: Setup & File Discovery
+   ├─ Step 1: Resolve base path
+   ├─ Step 2: Initialize directories
+   └─ Step 3: Discover files using script
+
+Phase 1: Parallel Agent Analysis (3 agents)
+   ├─ Style Agent → design-tokens.json + code_snippets
+   ├─ Animation Agent → animation-tokens.json + code_snippets
+   └─ Layout Agent → layout-templates.json + code_snippets
+```
+
 ### Step 1: Setup & File Discovery
 
 **Purpose**: Initialize session, discover and categorize code files
@@ -61,7 +80,7 @@ if [ -n "$DESIGN_ID" ]; then
   fi
 elif [ -n "$SESSION_ID" ]; then
   # Latest in session
-  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  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"

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

@@ -1,7 +1,7 @@
 ---
 name: layout-extract
-description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode
-argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
+description: Extract structural layout information 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>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
 ---
 
@@ -9,7 +9,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestio
 
 ## Overview
 
-Extract structural layout information from reference images, URLs, or text prompts using AI analysis. Supports two modes:
+Extract structural layout information from reference images or text prompts using AI analysis. Supports two modes:
 1. **Exploration Mode** (default): Generate multiple contrasting layout variants
 2. **Refinement Mode** (`--refine`): Refine a single existing layout through detailed adjustments
 
@@ -23,29 +23,46 @@ This command separates the "scaffolding" (HTML structure and CSS layout) from th
 - **Device-Aware**: Optimized for specific device types (desktop, mobile, tablet, responsive)
 - **Token-Based**: CSS uses `var()` placeholders for spacing and breakpoints
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --design-id, --session, --images, --prompt, --targets, --variants, --device-type, --interactive, --refine
+   └─ Decision (mode detection):
+      ├─ --refine flag → Refinement Mode (variants_count = 1)
+      └─ No --refine → Exploration Mode (variants_count = --variants OR 3)
+
+Phase 0: Setup & Input Validation
+   ├─ Step 1: Detect input, mode & targets
+   ├─ Step 2: Load inputs & create directories
+   └─ Step 3: Memory check (skip if cached)
+
+Phase 1: Layout Concept/Refinement Options Generation
+   ├─ Step 0.5: Load existing layout (Refinement Mode only)
+   ├─ Step 1: Generate options (Agent Task 1)
+   │  └─ Decision:
+   │     ├─ Exploration Mode → Generate contrasting layout concepts
+   │     └─ Refinement Mode → Generate refinement options
+   └─ Step 2: Verify options file created
+
+Phase 1.5: User Confirmation (Optional)
+   └─ Decision (--interactive flag):
+      ├─ --interactive present → Present options, capture selection
+      └─ No --interactive → Skip to Phase 2
+
+Phase 2: Layout Template Generation
+   ├─ Step 1: Load user selections or default to all
+   ├─ Step 2: Launch parallel agent tasks
+   └─ Step 3: Verify output files
+```
+
 ## Phase 0: Setup & Input Validation
 
 ### Step 1: Detect Input, Mode & Targets
 
 ```bash
 # Detect input source
-# Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
-
-# Parse URLs if provided (format: "target:url,target:url,...")
-IF --urls:
-    url_list = []
-    FOR pair IN split(--urls, ","):
-        IF ":" IN pair:
-            target, url = pair.split(":", 1)
-            url_list.append({target: target.strip(), url: url.strip()})
-        ELSE:
-            # Single URL without target
-            url_list.append({target: "page", url: pair.strip()})
-
-    has_urls = true
-ELSE:
-    has_urls = false
-    url_list = []
+# Priority: --images → image | --prompt → text
 
 # Detect refinement mode
 refine_mode = --refine OR false
@@ -62,11 +79,9 @@ ELSE:
     REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting layout concepts per target"
 
 # Resolve targets
-# Priority: --targets → url_list targets → prompt analysis → default ["page"]
+# Priority: --targets → prompt analysis → default ["page"]
 IF --targets:
     targets = split(--targets, ",")
-ELSE IF has_urls:
-    targets = [url_info.target for url_info in url_list]
 ELSE IF --prompt:
     # Extract targets from prompt using pattern matching
     # Looks for keywords: "page names", target descriptors (login, dashboard, etc.)
@@ -84,7 +99,7 @@ if [ -n "$DESIGN_ID" ]; then
   relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
 elif [ -n "$SESSION_ID" ]; then
   # Latest in session
-  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  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)
@@ -107,10 +122,6 @@ bash(echo "✓ Base path: $base_path")
 bash(ls {images_pattern})  # Expand glob pattern
 Read({image_path})  # Load each image
 
-# For URL mode
-# Parse URL list format: "target:url,target:url"
-# Validate URLs are accessible
-
 # For text mode
 # Validate --prompt is non-empty
 
@@ -118,97 +129,6 @@ Read({image_path})  # Load each image
 bash(mkdir -p {base_path}/layout-extraction)
 ```
 
-### Step 2.5: Extract DOM Structure (URL Mode - Auto-Trigger)
-```bash
-# AUTO-TRIGGER: If URLs are available (from --urls parameter), automatically extract real DOM structure
-# This provides accurate layout data to supplement visual analysis
-
-# Check if URLs provided via --urls parameter
-IF --urls AND url_list:
-    REPORT: "🔍 Auto-triggering URL mode: Extracting DOM structure"
-
-    bash(mkdir -p {base_path}/.intermediates/layout-analysis)
-
-    # For each URL in url_list:
-    FOR url_info IN url_list:
-        target = url_info.target
-        url = url_info.url
-
-        IF mcp_chrome_devtools_available:
-            REPORT: "   Processing: {target} ({url})"
-
-            # Read extraction script
-            script_content = Read(~/.claude/scripts/extract-layout-structure.js)
-
-            # Open page in Chrome DevTools
-            mcp__chrome-devtools__navigate_page(url=url)
-
-            # Execute layout extraction script
-            result = mcp__chrome-devtools__evaluate_script(function=script_content)
-
-            # Save DOM structure for this target (intermediate file)
-            Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
-
-            REPORT: "   ✅ DOM structure extracted for '{target}'"
-        ELSE:
-            REPORT: "   ⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
-            BREAK
-
-    dom_structure_available = mcp_chrome_devtools_available
-ELSE:
-    dom_structure_available = false
-```
-
-**Extraction Script Reference**: `~/.claude/scripts/extract-layout-structure.js`
-
-**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
-
-**Script returns**:
-- `metadata`: Extraction timestamp, URL, method, version
-- `patterns`: Layout pattern statistics (flexColumn, flexRow, grid counts)
-- `structure`: Hierarchical DOM tree with layout properties
-- `exploration`: (Optional) Progressive exploration results when standard selectors fail
-
-**Benefits**:
-- ✅ Real flex/grid configuration (justifyContent, alignItems, gap, etc.)
-- ✅ Accurate element bounds (x, y, width, height)
-- ✅ Structural hierarchy with depth control
-- ✅ Layout pattern identification (flex-row, flex-column, grid-NCol)
-- ✅ Progressive exploration: Auto-discovers missing selectors
-
-**Progressive Exploration Strategy** (v2.2.0+):
-
-When script finds <3 main containers, it automatically:
-1. **Scans** all large visible containers (≥500×300px)
-2. **Extracts** class patterns matching: `main|content|wrapper|container|page|layout|app`
-3. **Suggests** new selectors to add to script
-4. **Returns** exploration data in `result.exploration`:
-   ```json
-   {
-     "triggered": true,
-     "discoveredCandidates": [{classes, bounds, display}],
-     "suggestedSelectors": [".wrapper", ".page-index"],
-     "recommendation": ".wrapper, .page-index, .app-container"
-   }
-   ```
-
-**Using Exploration Results**:
-```javascript
-// After extraction, check for suggestions
-IF result.exploration?.triggered:
-    REPORT: result.exploration.warning
-    REPORT: "Suggested selectors: " + result.exploration.recommendation
-
-    // Update script by adding to commonClassSelectors array
-    // Then re-run extraction for better coverage
-```
-
-**Selector Update Workflow**:
-1. Run extraction on unfamiliar site
-2. Check `result.exploration.suggestedSelectors`
-3. Add relevant selectors to script's `commonClassSelectors`
-4. Re-run extraction → improved container detection
-
 ### Step 3: Memory Check
 ```bash
 # 1. Check if inputs cached in session memory
@@ -711,13 +631,6 @@ Configuration:
 - Device Type: {device_type}
 - Targets: {targets.join(", ")}
 - Total Templates: {total_tasks} ({targets.length} targets with multi-selection)
-{IF has_urls AND dom_structure_available:
-- 🔍 URL Mode: DOM structure extracted from {len(url_list)} URL(s)
-- Accuracy: Real flex/grid properties from live pages
-}
-{IF has_urls AND NOT dom_structure_available:
-- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
-}
 
 User Selections:
 {FOR each target in targets:
@@ -734,10 +647,7 @@ Generated Templates:
 
 Intermediate Files:
 - {base_path}/.intermediates/layout-analysis/
-  ├── analysis-options.json (concept proposals + user selections embedded)
-  {IF dom_structure_available:
-  ├── dom-structure-*.json ({len(url_list)} DOM extracts)
-  }
+  └── analysis-options.json (concept proposals + user selections embedded)
 
 Next: /workflow:ui-design:generate will combine these structural templates with design systems to produce final prototypes.
 ```
@@ -867,15 +777,11 @@ ERROR: MCP search failed
 
 ## Key Features
 
-- **Auto-Trigger URL Mode** - Automatically extracts DOM structure when --urls provided (no manual flag needed)
-- **Hybrid Extraction Strategy** - Combines real DOM structure data with AI visual analysis
-- **Accurate Layout Properties** - Chrome DevTools extracts real flex/grid configurations, bounds, and hierarchy
 - **Separation of Concerns** - Decouples layout (structure) from style (visuals)
 - **Multi-Selection Workflow** - Generate N concepts → User selects multiple → Parallel template generation
 - **Structural Exploration** - Enables A/B testing of different layouts through multi-selection
 - **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
 - **Device-Specific** - Tailored structures for different screen sizes
-- **Graceful Fallback** - Falls back to visual analysis if Chrome DevTools unavailable
 - **Foundation for Assembly** - Provides structural blueprint for prototype generation
 - **Agent-Powered** - Deep structural analysis with AI
 

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

@@ -33,6 +33,29 @@ Converts design run extraction results into shareable reference package with:
 
 ## Execution Process
 
+```
+Input Parsing:
+   ├─ Parse flags: --design-run, --package-name, --output-dir
+   └─ Validation:
+      ├─ --design-run and --package-name REQUIRED
+      └─ Package name format: lowercase, alphanumeric, hyphens only
+
+Phase 0: Setup & Validation
+   ├─ Step 1: Validate required parameters
+   ├─ Step 2: Validate package name format
+   ├─ Step 3: Validate design run exists
+   ├─ Step 4: Check required extraction files (design-tokens.json, layout-templates.json)
+   └─ Step 5: Setup output directory
+
+Phase 1: Prepare Component Data
+   ├─ Step 1: Copy layout templates
+   ├─ Step 2: Copy design tokens
+   └─ Step 3: Copy animation tokens (optional)
+
+Phase 2: Preview Generation (Agent)
+   └─ Generate preview.html + preview.css via ui-design-agent
+```
+
 ### Phase 0: Setup & Validation
 
 **Purpose**: Validate inputs, prepare output directory

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

@@ -1,8 +1,8 @@
 ---
 name: style-extract
 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>"] [--urls "<list>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
+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
@@ -19,28 +19,49 @@ Extract design style from reference images or text prompts using Claude's built-
 - **Dual Mode**: Exploration (multiple contrasting variants) or Refinement (single design fine-tuning)
 - **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
 
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse flags: --design-id, --session, --images, --prompt, --variants, --interactive, --refine
+   └─ Decision (mode detection):
+      ├─ --refine flag → Refinement Mode (variants_count = 1)
+      └─ No --refine → Exploration Mode (variants_count = --variants OR 3)
+
+Phase 0: Setup & Input Validation
+   ├─ Step 1: Detect input mode, extraction mode & base path
+   ├─ Step 2: Load inputs
+   └─ Step 3: Memory check (skip if exists)
+
+Phase 1: Design Direction/Refinement Options Generation
+   ├─ Step 1: Load project context
+   ├─ Step 2: Generate options (Agent Task 1)
+   │  └─ Decision:
+   │     ├─ Exploration Mode → Generate contrasting design directions
+   │     └─ Refinement Mode → Generate refinement options
+   └─ Step 3: Verify options file created
+
+Phase 1.5: User Confirmation (Optional)
+   └─ Decision (--interactive flag):
+      ├─ --interactive present → Present options, capture selection
+      └─ No --interactive → Skip to Phase 2
+
+Phase 2: Design System Generation
+   ├─ Step 1: Load user selection or default to all
+   ├─ Step 2: Create output directories
+   └─ Step 3: Launch agent tasks (parallel)
+
+Phase 3: Verify Output
+   ├─ Step 1: Check files created
+   └─ Step 2: Verify file sizes
+```
+
 ## Phase 0: Setup & Input Validation
 
 ### Step 1: Detect Input Mode, Extraction Mode & Base Path
 ```bash
 # Detect input source
-# Priority: --urls + --images + --prompt → hybrid-url | --urls + --images → url-image | --urls → url | --images + --prompt → hybrid | --images → image | --prompt → text
-
-# Parse URLs if provided (format: "target:url,target:url,...")
-IF --urls:
-    url_list = []
-    FOR pair IN split(--urls, ","):
-        IF ":" IN pair:
-            target, url = pair.split(":", 1)
-            url_list.append({target: target.strip(), url: url.strip()})
-        ELSE:
-            # Single URL without target
-            url_list.append({target: "page", url: pair.strip()})
-
-    has_urls = true
-    primary_url = url_list[0].url  # First URL as primary source
-ELSE:
-    has_urls = false
+# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
 
 # Detect refinement mode
 refine_mode = --refine OR false
@@ -62,7 +83,7 @@ if [ -n "$DESIGN_ID" ]; then
   relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
 elif [ -n "$SESSION_ID" ]; then
   # Latest in session
-  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  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)
@@ -79,64 +100,7 @@ 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
@@ -161,7 +125,7 @@ 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 or Refinement Options Generation
 
@@ -571,9 +535,8 @@ FOR variant_index IN 1..actual_variants_count:
       - Preview Border Radius: ${selected_direction.preview.border_radius_base}
 
       ## Input Analysis
-      - Input mode: {input_mode} (image/text/hybrid${has_urls ? "/url" : ""})
+      - Input mode: {input_mode} (image/text/hybrid)
       - Visual references: {loaded_images OR prompt_guidance}
-      ${computed_styles_available ? "- Computed styles: Use as ground truth (Read from .intermediates/style-analysis/computed-styles.json)" : ""}
 
       ## Generation Rules
       - Develop the selected design direction into a complete design system
@@ -587,7 +550,7 @@ FOR variant_index IN 1..actual_variants_count:
         * innovation → token naming, experimental values
       - Honor search_keywords for design inspiration
       - Avoid anti_keywords patterns
-      - All colors in OKLCH format ${computed_styles_available ? "(convert from computed RGB)" : ""}
+      - All colors in OKLCH format
       - WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
 
       ## Generate
@@ -656,16 +619,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:
@@ -676,11 +632,6 @@ Design Direction Selection:
 Generated Files:
 {base_path}/style-extraction/
 └── style-1/design-tokens.json
-
-{IF computed_styles_available:
-Intermediate Analysis:
-{base_path}/.intermediates/style-analysis/computed-styles.json (extracted from {primary_url})
-}
 {IF extraction_mode == "explore":
 {base_path}/.intermediates/style-analysis/analysis-options.json (design direction options + user selection)
 }
@@ -811,15 +762,11 @@ 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
 

.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/skills/command-guide/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: command-guide
-description: Workflow command guide for Claude DMS3 (75 commands). Search/browse commands, get next-step recommendations, view documentation, report issues. Triggers "CCW-help", "CCW-issue", "ccw-help", "ccw-issue", "ccw"
+description: Workflow command guide for Claude DMS3 (78 commands). Search/browse commands, get next-step recommendations, view documentation, report issues. Triggers "CCW-help", "CCW-issue", "ccw-help", "ccw-issue", "ccw"
 allowed-tools: Read, Grep, Glob, AskUserQuestion
 version: 5.8.0
 ---
 
 # Command Guide Skill
 
-Comprehensive command guide for Claude DMS3 workflow system covering 75 commands across 4 categories (workflow, cli, memory, task).
+Comprehensive command guide for Claude DMS3 workflow system covering 78 commands across 5 categories (workflow, cli, memory, task, general).
 
 ## 🆕 What's New in v5.8.0
 
@@ -18,7 +18,6 @@ Comprehensive command guide for Claude DMS3 workflow system covering 75 commands
 - **`/workflow:ui-design:codify-style`** - Extract design tokens from code with automatic file discovery
 - **`/workflow:ui-design:reference-page-generator`** - Generate multi-component reference pages
 - **Workflow**: Design extraction → Token documentation → SKILL package → Easy loading
-- **Benefits**: Consistent design system usage, shareable style references, progressive loading
 
 **⚡ `/workflow:lite-plan`** - Intelligent Planning & Execution (Testing Phase)
 - Dynamic workflow adaptation (smart exploration, adaptive planning, progressive clarification)
@@ -32,9 +31,9 @@ Comprehensive command guide for Claude DMS3 workflow system covering 75 commands
 - Creates feature-specific SKILL packages for code understanding
 - Progressive loading (2K → 30K tokens) for efficient context management
 
-### Agent Enhancements
+### Agent 
 
-- **cli-explore-agent** (New) - Specialized code exploration with Deep Scan mode (Bash + Gemini)
+- **cli-explore-agent**  - Specialized code exploration with Deep Scan mode (Bash + Gemini)
 - **cli-planning-agent** - Enhanced task generation with improved context handling
 - **ui-design-agent** - Major refactoring for better design system extraction
 
@@ -277,13 +276,13 @@ All command metadata is stored in JSON indexes for fast querying:
 
 Complete backup of all command and agent documentation for deep analysis:
 
-- **[reference/agents/](reference/agents/)** - 13 agent markdown files with implementation details
+- **[reference/agents/](reference/agents/)** - 14 agent markdown files with implementation details
   - **New in v5.8**: cli-explore-agent (code exploration), cli-planning-agent (enhanced)
-- **[reference/commands/](reference/commands/)** - 75 command markdown files organized by category
-  - `cli/` - CLI tool commands (9 files)
-  - `memory/` - Memory management commands (10 files) - **New**: code-map-memory, style-skill-memory
+- **[reference/commands/](reference/commands/)** - 78 command markdown files organized by category
+  - `cli/` - CLI tool commands (10 files) - **New**: document-analysis mode
+  - `memory/` - Memory management commands (12 files) - **New**: docs-full-cli, docs-related-cli, code-map-memory, style-skill-memory
   - `task/` - Task management commands (4 files)
-  - `workflow/` - Workflow commands (50 files) - **New**: lite-plan, ui-design enhancements
+  - `workflow/` - Workflow commands (50 files) - **New**: lite-plan, lite-fix, ui-design enhancements
 
 **Installation Path**: `~/.claude/skills/command-guide/` (skill designed for global installation)
 
@@ -314,13 +313,13 @@ Templates are auto-populated during Mode 5 (Issue Reporting) interaction.
 
 ## 📊 System Statistics
 
-- **Total Commands**: 75
-- **Total Agents**: 13
-- **Categories**: 4 (workflow: 50, cli: 9, memory: 10, task: 4, general: 2)
-- **Use Cases**: 7 (planning, implementation, testing, documentation, session-management, analysis, ui-design)
+- **Total Commands**: 78
+- **Total Agents**: 14
+- **Categories**: 5 (workflow: 50, cli: 10, memory: 12, task: 4, general: 2)
+- **Use Cases**: 7 (planning, implementation, testing, documentation, session-management, analysis, general)
 - **Difficulty Levels**: 3 (Beginner, Intermediate, Advanced)
-- **Essential Commands**: 14
-- **Reference Docs**: 88 markdown files (13 agents + 75 commands)
+- **Essential Commands**: 13
+- **Reference Docs**: 92 markdown files (14 agents + 78 commands)
 
 ---
 

.claude/skills/command-guide/guides/cli-tools-guide.md

@@ -78,7 +78,7 @@ cd src/auth && qwen -p "
 追踪用户登录的完整执行流程，
 从 API 入口到数据库查询，
 列出所有调用的函数和依赖关系
-" -m coder-model
+"
 ```
 
 **工具输出**：Qwen 理解需求，自动追踪执行路径
@@ -278,7 +278,7 @@ codex -C src/auth --full-auto exec "
 **方式 1：CLI 工具语义调用**（推荐，灵活）
 
 - **用户输入**：`使用 gemini 分析这个项目的架构设计，识别主要模块、依赖关系和架构模式`
-- **Claude Code 生成并执行**：`cd project-root && gemini -p "..." -m gemini-3-pro-preview-11-2025`
+- **Claude Code 生成并执行**：`cd project-root && gemini -p "..."`
 
 **方式 2：Slash 命令**
 - **用户输入**：`/cli:analyze --tool gemini "分析项目架构"`
@@ -291,7 +291,7 @@ codex -C src/auth --full-auto exec "
 
 **方式 1：CLI 工具语义调用**
 - **用户输入**：`让 codex 实现用户认证功能：注册（邮箱+密码+验证）、登录（JWT token）、刷新令牌，技术栈 Node.js + Express`
-- **Claude Code 生成并执行**：`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
+- **Claude Code 生成并执行**：`codex -C src/auth --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
 
 **方式 2：Slash 命令**（工作流化）
 - **用户输入**：`/workflow:plan --agent "实现用户认证功能"` → `/workflow:execute`
@@ -304,9 +304,9 @@ codex -C src/auth --full-auto exec "
 
 **方式 1：CLI 工具语义调用**
 - **用户输入**：`使用 gemini 诊断登录超时问题，分析处理流程、性能瓶颈、数据库查询效率`
-- **Claude Code 生成并执行**：`cd src/auth && gemini -p "..." -m gemini-3-pro-preview-11-2025`
+- **Claude Code 生成并执行**：`cd src/auth && gemini -p "..."`
 - **用户输入**：`让 codex 根据上述分析修复登录超时，优化查询、添加缓存`
-- **Claude Code 生成并执行**：`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
+- **Claude Code 生成并执行**：`codex -C src/auth --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
 
 **方式 2：Slash 命令**
 - **用户输入**：`/cli:mode:bug-diagnosis --tool gemini "诊断登录超时"` → `/cli:execute --tool codex "修复登录超时"`
@@ -319,7 +319,7 @@ codex -C src/auth --full-auto exec "
 
 **方式 1：CLI 工具语义调用**
 - **用户输入**：`使用 gemini 为 API 模块生成技术文档，包含端点说明、数据模型、使用示例`
-- **Claude Code 生成并执行**：`cd src/api && gemini -p "..." -m gemini-3-pro-preview-11-2025 --approval-mode yolo`
+- **Claude Code 生成并执行**：`cd src/api && gemini -p "..." --approval-mode yolo`
 
 **方式 2：Slash 命令**
 - **用户输入**：`/memory:docs src/api --tool gemini --mode full`

.claude/skills/command-guide/guides/implementation-details.md

@@ -762,7 +762,7 @@ async function executeCLIAnalysis(prompt) {
 
   // Execute gemini with analysis prompt using --include-directories
   // This allows gemini to access reference docs while maintaining correct file context
-  const command = `gemini -p "${escapePrompt(prompt)}" -m gemini-3-pro-preview-11-2025 --include-directories ${referencePath}`;
+  const command = `gemini -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
 
   try {
     const result = await execBash(command, { timeout: 120000 }); // 2 min timeout
@@ -770,7 +770,7 @@ async function executeCLIAnalysis(prompt) {
   } catch (error) {
     // Fallback to qwen if gemini fails
     console.warn('Gemini failed, falling back to qwen');
-    const fallbackCmd = `qwen -p "${escapePrompt(prompt)}" -m coder-model --include-directories ${referencePath}`;
+    const fallbackCmd = `qwen -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
     const result = await execBash(fallbackCmd, { timeout: 120000 });
     return parseAnalysisResult(result.stdout);
   }

.claude/skills/command-guide/guides/ui-design-workflow-guide.md

@@ -11,7 +11,7 @@ The UI Design Workflow System is a comprehensive suite of 11 autonomous commands
 These commands automate end-to-end processes by chaining specialized sub-commands.
 
 - **`/workflow:ui-design:explore-auto`**: For creating *new* designs. Generates multiple style and layout variants from a prompt to explore design directions.
-- **`/workflow:ui-design:imitate-auto`**: For *replicating* existing designs. High-fidelity cloning of target URLs into a reusable design system.
+- **`/workflow:ui-design:imitate-auto`**: For *replicating* existing designs. Creates design systems from local reference files (images, code) or text prompts.
 
 ### 2. Core Extractors (Specialized Analysis)
 
@@ -88,41 +88,41 @@ Tools for combining components and integrating results.
 4. **User selects** 2 preferred layouts (multi-select)
 5. System generates only 4-6 final prototypes (selected combinations)
 
-**Benefits:**
-- Reduces unnecessary generation (from 20 to 4-6 prototypes)
-- Focuses resources on preferred design directions
-- Saves 70-80% computation time
-- Better exploration quality
+
 
 ---
 
 ### Workflow B: Design Replication (Imitation)
 
-**Goal:** Create a design system and prototypes based on existing reference sites.
+**Goal:** Create a design system and prototypes based on existing local references.
 
 **Primary Command:** `imitate-auto`
 
 **Steps:**
 
-1. **Initiate**: User runs `/workflow:ui-design:imitate-auto --url-map "home:https://example.com, pricing:https://example.com/pricing"`
-2. **Capture**: System screenshots all provided URLs.
-3. **Extraction**: System extracts a unified design system (style, layout, animation) from the primary URL.
-4. **Assembly**: System recreates all target pages using the extracted system.
+1. **Initiate**: User runs `/workflow:ui-design:imitate-auto --input "design-refs/*.png"` with local reference files
+2. **Input Detection**: System detects input type (images, code files, or text)
+3. **Extraction**: System extracts a unified design system (style, layout, animation) from the references.
+4. **Assembly**: System creates prototypes using the extracted system.
 
 **Example:**
 
 ```bash
+# Using reference images
 /workflow:ui-design:imitate-auto \
-  --url-map "landing:https://stripe.com, pricing:https://stripe.com/pricing, docs:https://stripe.com/docs" \
-  --capture-mode batch \
+  --input "design-refs/*.png" \
+  --session WFS-002
+
+# Or importing from existing code
+/workflow:ui-design:imitate-auto \
+  --input "./src/components" \
   --session WFS-002
 ```
 
 **Output:**
-- Screenshots of all URLs
 - `design-tokens.json` (unified style system)
 - `layout-templates.json` (page structures)
-- 3 HTML prototypes matching the captured pages
+- HTML prototypes based on the input references
 
 ---
 
@@ -165,10 +165,7 @@ Tools for combining components and integrating results.
 - `layout-templates.json` (Structure) - DOM hierarchy, CSS layout rules
 - `animation-tokens.json` (Motion) - Transitions, keyframes, timing functions
 
-**Benefits:**
-- Instant re-theming by swapping design tokens
-- Layout reuse across different visual styles
-- Independent evolution of style and structure
+
 
 ### Token-First CSS
 
@@ -204,10 +201,10 @@ For high-volume generation:
 - Specify the *targets* (e.g., "dashboard, settings page")
 - Include functional requirements (e.g., "responsive, mobile-first")
 
-**For URL Mapping:**
-- First URL is treated as primary source of truth
-- Use descriptive keys in `--url-map`
-- Ensure URLs are accessible (no authentication walls)
+**For Local References:**
+- Use high-quality reference images (PNG, JPG)
+- Organize files in accessible directories
+- For code imports, ensure files are properly structured (CSS, JS, HTML)
 
 ---
 
@@ -233,8 +230,8 @@ You can run UI design workflows within an existing workflow session:
 **Example: Imitation + Custom Extraction**
 
 ```bash
-# 1. Replicate existing design
-/workflow:ui-design:imitate-auto --url-map "ref:https://example.com"
+# 1. Import design from local references
+/workflow:ui-design:imitate-auto --input "design-refs/*.png"
 
 # 2. Extract additional layouts and generate prototypes
 /workflow:ui-design:layout-extract --targets "new-page-1,new-page-2"

.claude/skills/command-guide/index/all-commands.json

@@ -87,6 +87,17 @@
     "difficulty": "Intermediate",
     "file_path": "cli/mode/code-analysis.md"
   },
+  {
+    "name": "document-analysis",
+    "command": "/cli:mode:document-analysis",
+    "description": "Read-only technical document/paper analysis using Gemini/Qwen/Codex with systematic comprehension template for insights extraction",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] document path or topic",
+    "category": "cli",
+    "subcategory": "mode",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "cli/mode/document-analysis.md"
+  },
   {
     "name": "plan",
     "command": "/cli:mode:plan",
@@ -101,7 +112,7 @@
   {
     "name": "enhance-prompt",
     "command": "/enhance-prompt",
-    "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection",
+    "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection",
     "arguments": "user input to enhance",
     "category": "general",
     "subcategory": null,
@@ -120,6 +131,28 @@
     "difficulty": "Intermediate",
     "file_path": "memory/code-map-memory.md"
   },
+  {
+    "name": "docs-full-cli",
+    "command": "/memory: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",
+    "arguments": "[path] [--tool <gemini|qwen|codex>]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/docs-full-cli.md"
+  },
+  {
+    "name": "docs-related-cli",
+    "command": "/memory: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",
+    "arguments": "[--tool <gemini|qwen|codex>]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/docs-related-cli.md"
+  },
   {
     "name": "docs",
     "command": "/memory:docs",
@@ -428,11 +461,44 @@
     "difficulty": "Intermediate",
     "file_path": "workflow/execute.md"
   },
+  {
+    "name": "init",
+    "command": "/workflow:init",
+    "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent",
+    "arguments": "[--regenerate]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/init.md"
+  },
+  {
+    "name": "lite-execute",
+    "command": "/workflow:lite-execute",
+    "description": "Execute tasks based on in-memory plan, prompt description, or file content",
+    "arguments": "[--in-memory] [\\\"task description\\\"|file-path]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/lite-execute.md"
+  },
+  {
+    "name": "lite-fix",
+    "command": "/workflow:lite-fix",
+    "description": "Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents",
+    "arguments": "[--hotfix] \\\"bug description or issue reference\\",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/lite-fix.md"
+  },
   {
     "name": "lite-plan",
     "command": "/workflow:lite-plan",
-    "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
-    "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
+    "description": "Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation",
+    "arguments": "[-e|--explore] \\\"task description\\\"|file.md",
     "category": "workflow",
     "subcategory": null,
     "usage_scenario": "planning",
@@ -451,15 +517,15 @@
     "file_path": "workflow/plan.md"
   },
   {
-    "name": "resume",
-    "command": "/workflow:resume",
-    "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection",
-    "arguments": "session-id for workflow session to resume",
+    "name": "replan",
+    "command": "/workflow:replan",
+    "description": "Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning",
+    "arguments": "[--session session-id] [task-id] \\\"requirements\\\"|file.md [--interactive]",
     "category": "workflow",
     "subcategory": null,
-    "usage_scenario": "session-management",
+    "usage_scenario": "planning",
     "difficulty": "Intermediate",
-    "file_path": "workflow/resume.md"
+    "file_path": "workflow/replan.md"
   },
   {
     "name": "review",
@@ -519,8 +585,8 @@
   {
     "name": "workflow:status",
     "command": "/workflow:status",
-    "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view",
-    "arguments": "[optional: task-id]",
+    "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view",
+    "arguments": "[optional: --project|task-id|--validate|--dashboard]",
     "category": "workflow",
     "subcategory": null,
     "usage_scenario": "session-management",
@@ -692,17 +758,6 @@
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/animation-extract.md"
   },
-  {
-    "name": "capture",
-    "command": "/workflow:ui-design:capture",
-    "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
-    "arguments": "--url-map \"target:url,...\" [--design-id <id>] [--session <id>]",
-    "category": "workflow",
-    "subcategory": "ui-design",
-    "usage_scenario": "general",
-    "difficulty": "Intermediate",
-    "file_path": "workflow/ui-design/capture.md"
-  },
   {
     "name": "workflow:ui-design:codify-style",
     "command": "/workflow:ui-design:codify-style",
@@ -714,6 +769,17 @@
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/codify-style.md"
   },
+  {
+    "name": "design-sync",
+    "command": "/workflow:ui-design:design-sync",
+    "description": "Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption",
+    "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/design-sync.md"
+  },
   {
     "name": "explore-auto",
     "command": "/workflow:ui-design:explore-auto",
@@ -725,17 +791,6 @@
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/explore-auto.md"
   },
-  {
-    "name": "explore-layers",
-    "command": "/workflow:ui-design:explore-layers",
-    "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
-    "arguments": "--url <url> --depth <1-5> [--design-id <id>] [--session <id>]",
-    "category": "workflow",
-    "subcategory": "ui-design",
-    "usage_scenario": "general",
-    "difficulty": "Intermediate",
-    "file_path": "workflow/ui-design/explore-layers.md"
-  },
   {
     "name": "generate",
     "command": "/workflow:ui-design:generate",
@@ -772,25 +827,14 @@
   {
     "name": "layout-extract",
     "command": "/workflow:ui-design:layout-extract",
-    "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode",
-    "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
+    "description": "Extract structural layout information from reference images or text prompts using Claude analysis with variant generation or refinement mode",
+    "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/layout-extract.md"
   },
-  {
-    "name": "list",
-    "command": "/workflow:ui-design:list",
-    "description": "List all available design runs with metadata (session, created time, prototype count)",
-    "arguments": "[--session <id>]",
-    "category": "workflow",
-    "subcategory": "ui-design",
-    "usage_scenario": "general",
-    "difficulty": "Beginner",
-    "file_path": "workflow/ui-design/list.md"
-  },
   {
     "name": "workflow:ui-design:reference-page-generator",
     "command": "/workflow:ui-design:reference-page-generator",
@@ -806,22 +850,11 @@
     "name": "style-extract",
     "command": "/workflow:ui-design:style-extract",
     "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode",
-    "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
+    "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/style-extract.md"
-  },
-  {
-    "name": "update",
-    "command": "/workflow:ui-design:update",
-    "description": "Update brainstorming artifacts with finalized design system references from selected prototypes",
-    "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
-    "category": "workflow",
-    "subcategory": "ui-design",
-    "usage_scenario": "general",
-    "difficulty": "Intermediate",
-    "file_path": "workflow/ui-design/update.md"
   }
 ]

.claude/skills/command-guide/index/by-category.json

@@ -91,6 +91,17 @@
         "difficulty": "Intermediate",
         "file_path": "cli/mode/code-analysis.md"
       },
+      {
+        "name": "document-analysis",
+        "command": "/cli:mode:document-analysis",
+        "description": "Read-only technical document/paper analysis using Gemini/Qwen/Codex with systematic comprehension template for insights extraction",
+        "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] document path or topic",
+        "category": "cli",
+        "subcategory": "mode",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "cli/mode/document-analysis.md"
+      },
       {
         "name": "plan",
         "command": "/cli:mode:plan",
@@ -109,7 +120,7 @@
       {
         "name": "enhance-prompt",
         "command": "/enhance-prompt",
-        "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection",
+        "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection",
         "arguments": "user input to enhance",
         "category": "general",
         "subcategory": null,
@@ -143,6 +154,28 @@
         "difficulty": "Intermediate",
         "file_path": "memory/code-map-memory.md"
       },
+      {
+        "name": "docs-full-cli",
+        "command": "/memory: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",
+        "arguments": "[path] [--tool <gemini|qwen|codex>]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/docs-full-cli.md"
+      },
+      {
+        "name": "docs-related-cli",
+        "command": "/memory: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",
+        "arguments": "[--tool <gemini|qwen|codex>]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/docs-related-cli.md"
+      },
       {
         "name": "docs",
         "command": "/memory:docs",
@@ -316,11 +349,44 @@
         "difficulty": "Intermediate",
         "file_path": "workflow/execute.md"
       },
+      {
+        "name": "init",
+        "command": "/workflow:init",
+        "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent",
+        "arguments": "[--regenerate]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/init.md"
+      },
+      {
+        "name": "lite-execute",
+        "command": "/workflow:lite-execute",
+        "description": "Execute tasks based on in-memory plan, prompt description, or file content",
+        "arguments": "[--in-memory] [\\\"task description\\\"|file-path]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/lite-execute.md"
+      },
+      {
+        "name": "lite-fix",
+        "command": "/workflow:lite-fix",
+        "description": "Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents",
+        "arguments": "[--hotfix] \\\"bug description or issue reference\\",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/lite-fix.md"
+      },
       {
         "name": "lite-plan",
         "command": "/workflow:lite-plan",
-        "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
-        "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
+        "description": "Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation",
+        "arguments": "[-e|--explore] \\\"task description\\\"|file.md",
         "category": "workflow",
         "subcategory": null,
         "usage_scenario": "planning",
@@ -339,15 +405,15 @@
         "file_path": "workflow/plan.md"
       },
       {
-        "name": "resume",
-        "command": "/workflow:resume",
-        "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection",
-        "arguments": "session-id for workflow session to resume",
+        "name": "replan",
+        "command": "/workflow:replan",
+        "description": "Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning",
+        "arguments": "[--session session-id] [task-id] \\\"requirements\\\"|file.md [--interactive]",
         "category": "workflow",
         "subcategory": null,
-        "usage_scenario": "session-management",
+        "usage_scenario": "planning",
         "difficulty": "Intermediate",
-        "file_path": "workflow/resume.md"
+        "file_path": "workflow/replan.md"
       },
       {
         "name": "review",
@@ -363,8 +429,8 @@
       {
         "name": "workflow:status",
         "command": "/workflow:status",
-        "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view",
-        "arguments": "[optional: task-id]",
+        "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view",
+        "arguments": "[optional: --project|task-id|--validate|--dashboard]",
         "category": "workflow",
         "subcategory": null,
         "usage_scenario": "session-management",
@@ -720,17 +786,6 @@
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/animation-extract.md"
       },
-      {
-        "name": "capture",
-        "command": "/workflow:ui-design:capture",
-        "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
-        "arguments": "--url-map \"target:url,...\" [--design-id <id>] [--session <id>]",
-        "category": "workflow",
-        "subcategory": "ui-design",
-        "usage_scenario": "general",
-        "difficulty": "Intermediate",
-        "file_path": "workflow/ui-design/capture.md"
-      },
       {
         "name": "workflow:ui-design:codify-style",
         "command": "/workflow:ui-design:codify-style",
@@ -742,6 +797,17 @@
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/codify-style.md"
       },
+      {
+        "name": "design-sync",
+        "command": "/workflow:ui-design:design-sync",
+        "description": "Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption",
+        "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/design-sync.md"
+      },
       {
         "name": "explore-auto",
         "command": "/workflow:ui-design:explore-auto",
@@ -753,17 +819,6 @@
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/explore-auto.md"
       },
-      {
-        "name": "explore-layers",
-        "command": "/workflow:ui-design:explore-layers",
-        "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
-        "arguments": "--url <url> --depth <1-5> [--design-id <id>] [--session <id>]",
-        "category": "workflow",
-        "subcategory": "ui-design",
-        "usage_scenario": "general",
-        "difficulty": "Intermediate",
-        "file_path": "workflow/ui-design/explore-layers.md"
-      },
       {
         "name": "generate",
         "command": "/workflow:ui-design:generate",
@@ -800,25 +855,14 @@
       {
         "name": "layout-extract",
         "command": "/workflow:ui-design:layout-extract",
-        "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode",
-        "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
+        "description": "Extract structural layout information from reference images or text prompts using Claude analysis with variant generation or refinement mode",
+        "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/layout-extract.md"
       },
-      {
-        "name": "list",
-        "command": "/workflow:ui-design:list",
-        "description": "List all available design runs with metadata (session, created time, prototype count)",
-        "arguments": "[--session <id>]",
-        "category": "workflow",
-        "subcategory": "ui-design",
-        "usage_scenario": "general",
-        "difficulty": "Beginner",
-        "file_path": "workflow/ui-design/list.md"
-      },
       {
         "name": "workflow:ui-design:reference-page-generator",
         "command": "/workflow:ui-design:reference-page-generator",
@@ -834,23 +878,12 @@
         "name": "style-extract",
         "command": "/workflow:ui-design:style-extract",
         "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode",
-        "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
+        "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/style-extract.md"
-      },
-      {
-        "name": "update",
-        "command": "/workflow:ui-design:update",
-        "description": "Update brainstorming artifacts with finalized design system references from selected prototypes",
-        "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
-        "category": "workflow",
-        "subcategory": "ui-design",
-        "usage_scenario": "general",
-        "difficulty": "Intermediate",
-        "file_path": "workflow/ui-design/update.md"
       }
     ]
   }

.claude/skills/command-guide/index/by-use-case.json

@@ -68,10 +68,21 @@
       "difficulty": "Intermediate",
       "file_path": "cli/mode/code-analysis.md"
     },
+    {
+      "name": "document-analysis",
+      "command": "/cli:mode:document-analysis",
+      "description": "Read-only technical document/paper analysis using Gemini/Qwen/Codex with systematic comprehension template for insights extraction",
+      "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] document path or topic",
+      "category": "cli",
+      "subcategory": "mode",
+      "usage_scenario": "general",
+      "difficulty": "Intermediate",
+      "file_path": "cli/mode/document-analysis.md"
+    },
     {
       "name": "enhance-prompt",
       "command": "/enhance-prompt",
-      "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection",
+      "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection",
       "arguments": "user input to enhance",
       "category": "general",
       "subcategory": null,
@@ -244,6 +255,28 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/brainstorm/ux-expert.md"
     },
+    {
+      "name": "init",
+      "command": "/workflow:init",
+      "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent",
+      "arguments": "[--regenerate]",
+      "category": "workflow",
+      "subcategory": null,
+      "usage_scenario": "general",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/init.md"
+    },
+    {
+      "name": "lite-fix",
+      "command": "/workflow:lite-fix",
+      "description": "Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents",
+      "arguments": "[--hotfix] \\\"bug description or issue reference\\",
+      "category": "workflow",
+      "subcategory": null,
+      "usage_scenario": "general",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/lite-fix.md"
+    },
     {
       "name": "list",
       "command": "/workflow:session:list",
@@ -299,17 +332,6 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/ui-design/animation-extract.md"
     },
-    {
-      "name": "capture",
-      "command": "/workflow:ui-design:capture",
-      "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
-      "arguments": "--url-map \"target:url,...\" [--design-id <id>] [--session <id>]",
-      "category": "workflow",
-      "subcategory": "ui-design",
-      "usage_scenario": "general",
-      "difficulty": "Intermediate",
-      "file_path": "workflow/ui-design/capture.md"
-    },
     {
       "name": "explore-auto",
       "command": "/workflow:ui-design:explore-auto",
@@ -321,17 +343,6 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/ui-design/explore-auto.md"
     },
-    {
-      "name": "explore-layers",
-      "command": "/workflow:ui-design:explore-layers",
-      "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
-      "arguments": "--url <url> --depth <1-5> [--design-id <id>] [--session <id>]",
-      "category": "workflow",
-      "subcategory": "ui-design",
-      "usage_scenario": "general",
-      "difficulty": "Intermediate",
-      "file_path": "workflow/ui-design/explore-layers.md"
-    },
     {
       "name": "imitate-auto",
       "command": "/workflow:ui-design:imitate-auto",
@@ -346,46 +357,24 @@
     {
       "name": "layout-extract",
       "command": "/workflow:ui-design:layout-extract",
-      "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode",
-      "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
+      "description": "Extract structural layout information from reference images or text prompts using Claude analysis with variant generation or refinement mode",
+      "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
       "difficulty": "Intermediate",
       "file_path": "workflow/ui-design/layout-extract.md"
     },
-    {
-      "name": "list",
-      "command": "/workflow:ui-design:list",
-      "description": "List all available design runs with metadata (session, created time, prototype count)",
-      "arguments": "[--session <id>]",
-      "category": "workflow",
-      "subcategory": "ui-design",
-      "usage_scenario": "general",
-      "difficulty": "Beginner",
-      "file_path": "workflow/ui-design/list.md"
-    },
     {
       "name": "style-extract",
       "command": "/workflow:ui-design:style-extract",
       "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode",
-      "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
+      "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
       "difficulty": "Intermediate",
       "file_path": "workflow/ui-design/style-extract.md"
-    },
-    {
-      "name": "update",
-      "command": "/workflow:ui-design:update",
-      "description": "Update brainstorming artifacts with finalized design system references from selected prototypes",
-      "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
-      "category": "workflow",
-      "subcategory": "ui-design",
-      "usage_scenario": "general",
-      "difficulty": "Intermediate",
-      "file_path": "workflow/ui-design/update.md"
     }
   ],
   "implementation": [
@@ -444,6 +433,17 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/execute.md"
     },
+    {
+      "name": "lite-execute",
+      "command": "/workflow:lite-execute",
+      "description": "Execute tasks based on in-memory plan, prompt description, or file content",
+      "arguments": "[--in-memory] [\\\"task description\\\"|file-path]",
+      "category": "workflow",
+      "subcategory": null,
+      "usage_scenario": "implementation",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/lite-execute.md"
+    },
     {
       "name": "test-cycle-execute",
       "command": "/workflow:test-cycle-execute",
@@ -592,8 +592,8 @@
     {
       "name": "lite-plan",
       "command": "/workflow:lite-plan",
-      "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
-      "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
+      "description": "Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation",
+      "arguments": "[-e|--explore] \\\"task description\\\"|file.md",
       "category": "workflow",
       "subcategory": null,
       "usage_scenario": "planning",
@@ -611,6 +611,17 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/plan.md"
     },
+    {
+      "name": "replan",
+      "command": "/workflow:replan",
+      "description": "Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning",
+      "arguments": "[--session session-id] [task-id] \\\"requirements\\\"|file.md [--interactive]",
+      "category": "workflow",
+      "subcategory": null,
+      "usage_scenario": "planning",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/replan.md"
+    },
     {
       "name": "tdd-plan",
       "command": "/workflow:tdd-plan",
@@ -633,6 +644,17 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/ui-design/codify-style.md"
     },
+    {
+      "name": "design-sync",
+      "command": "/workflow:ui-design:design-sync",
+      "description": "Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption",
+      "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
+      "category": "workflow",
+      "subcategory": "ui-design",
+      "usage_scenario": "planning",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/ui-design/design-sync.md"
+    },
     {
       "name": "workflow:ui-design:import-from-code",
       "command": "/workflow:ui-design:import-from-code",
@@ -668,6 +690,28 @@
       "difficulty": "Intermediate",
       "file_path": "memory/code-map-memory.md"
     },
+    {
+      "name": "docs-full-cli",
+      "command": "/memory: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",
+      "arguments": "[path] [--tool <gemini|qwen|codex>]",
+      "category": "memory",
+      "subcategory": null,
+      "usage_scenario": "documentation",
+      "difficulty": "Intermediate",
+      "file_path": "memory/docs-full-cli.md"
+    },
+    {
+      "name": "docs-related-cli",
+      "command": "/memory: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",
+      "arguments": "[--tool <gemini|qwen|codex>]",
+      "category": "memory",
+      "subcategory": null,
+      "usage_scenario": "documentation",
+      "difficulty": "Intermediate",
+      "file_path": "memory/docs-related-cli.md"
+    },
     {
       "name": "docs",
       "command": "/memory:docs",
@@ -725,17 +769,6 @@
     }
   ],
   "session-management": [
-    {
-      "name": "resume",
-      "command": "/workflow:resume",
-      "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection",
-      "arguments": "session-id for workflow session to resume",
-      "category": "workflow",
-      "subcategory": null,
-      "usage_scenario": "session-management",
-      "difficulty": "Intermediate",
-      "file_path": "workflow/resume.md"
-    },
     {
       "name": "complete",
       "command": "/workflow:session:complete",
@@ -761,8 +794,8 @@
     {
       "name": "workflow:status",
       "command": "/workflow:status",
-      "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view",
-      "arguments": "[optional: task-id]",
+      "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view",
+      "arguments": "[optional: --project|task-id|--validate|--dashboard]",
       "category": "workflow",
       "subcategory": null,
       "usage_scenario": "session-management",

.claude/skills/command-guide/index/essential-commands.json

@@ -24,8 +24,8 @@
   {
     "name": "workflow:status",
     "command": "/workflow:status",
-    "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view",
-    "arguments": "[optional: task-id]",
+    "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view",
+    "arguments": "[optional: --project|task-id|--validate|--dashboard]",
     "category": "workflow",
     "subcategory": null,
     "usage_scenario": "session-management",
@@ -109,17 +109,6 @@
     "difficulty": "Intermediate",
     "file_path": "workflow/action-plan-verify.md"
   },
-  {
-    "name": "resume",
-    "command": "/workflow:resume",
-    "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection",
-    "arguments": "session-id for workflow session to resume",
-    "category": "workflow",
-    "subcategory": null,
-    "usage_scenario": "session-management",
-    "difficulty": "Intermediate",
-    "file_path": "workflow/resume.md"
-  },
   {
     "name": "review",
     "command": "/workflow:review",
@@ -145,7 +134,7 @@
   {
     "name": "enhance-prompt",
     "command": "/enhance-prompt",
-    "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection",
+    "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection",
     "arguments": "user input to enhance",
     "category": "general",
     "subcategory": null,

.claude/skills/command-guide/reference/agents/action-planning-agent.md

@@ -21,15 +21,15 @@ You are a pure execution agent specialized in creating actionable implementation
 ## Execution Process
 
 ### Input Processing
-**What you receive:**
-- **Execution Context Package**: Structured context from command layer
+
+**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
@@ -37,73 +37,103 @@ You are a pure execution agent specialized in creating actionable implementation
 - **Task requirements**: Direct task description
 
 ### Execution Flow (Two-Phase)
+
 ```
-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):
+Phase 1: Content Loading & Context Assembly
+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 key fields
+   - brainstorm_artifacts: Catalog of brainstorming outputs
+     - guidance_specification: Path to overall framework
+     - role_analyses[]: Array of role analysis files with priorities
+     - synthesis_output: Path to synthesis results (if exists)
+     - conflict_resolution: Conflict status and affected files
+   - focus_areas: Target directories for implementation
+   - assets: Existing code patterns to reuse
+   - conflict_risk: Risk level (low/medium/high)
+
+3. Load brainstorming artifacts (in priority order)
+   a. guidance-specification.md (Highest Priority)
+      → Overall design framework and architectural decisions
+   b. Role analyses (High Priority - load ALL files)
+      → system-architect/analysis.md
+      → subject-matter-expert/analysis.md
+      → (Other roles as listed in context package)
+   c. Synthesis output (if exists)
+      → Integrated view with clarifications
+   d. Conflict resolution (if conflict_risk ≥ medium)
+      → Review resolved conflicts in artifacts
+
+4. 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
+
+5. Assess task complexity (simple/medium/complex)
 
 Phase 2: Document Generation (Autonomous Output)
-1. Extract task definitions from analysis_results
-2. Generate task JSON files with 5-field schema + artifacts
+1. Synthesize requirements from all sources (user input + brainstorming artifacts)
+2. Generate task JSON files with 6-field schema + artifacts integration
 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
 ```
 
-### Context Package Usage
+### Context Package Fields to Load
 
-**Standard Context Structure**:
+**Load from `context_package_path` - fields defined by context-search-agent**:
+
+**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) {
+  contextPackage.brainstorm_artifacts.role_analyses.forEach(role => {
+    role.files.forEach(file => {
+      const analysis = file.content || Read(file.path);
+    });
+  });
 }
 ```
 
-**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}/)
-
 ### MCP Integration Guidelines
 
 **Exa Code Context** (`mcp_capabilities.exa_code = true`):
@@ -137,19 +167,44 @@ Break work into 3-5 logical implementation stages with:
 - Dependencies on previous stages
 - Estimated complexity and time requirements
 
-### 2. Task JSON Generation (5-Field Schema + Artifacts)
+### 2. Task JSON Generation (6-Field Schema + Artifacts)
 Generate individual `.task/IMPL-*.json` files with:
 
-**Required Fields**:
+#### Top-Level Fields
 ```json
 {
   "id": "IMPL-N[.M]",
   "title": "Descriptive task name",
-  "status": "pending",
+  "status": "pending|active|completed|blocked|container",
+  "context_package_path": ".workflow/active/WFS-{session}/.process/context-package.json"
+}
+```
+
+**Field Descriptions**:
+- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks, max 2 levels)
+- `title`: Descriptive task name summarizing the work
+- `status`: Task state - `pending` (not started), `active` (in progress), `completed` (done), `blocked` (waiting on dependencies), `container` (has subtasks, cannot be executed directly)
+- `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"
-  },
+    "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"
+  }
+}
+```
+
+**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
+
+#### Context Object
+```json
+{
   "context": {
     "requirements": [
       "Implement 3 features: [authentication, authorization, session management]",
@@ -162,43 +217,131 @@ Generate individual `.task/IMPL-*.json` files with:
       "5 files created: verify by ls src/auth/*.ts | wc -l = 5",
       "Test coverage >=80%: verify by npm test -- --coverage | grep auth"
     ],
+    "parent": "IMPL-N",
     "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",
+        "type": "synthesis_specification|topic_framework|individual_role_analysis",
+        "source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
         "path": "{from artifacts_inventory}",
-        "priority": "highest"
+        "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")
+- `parent`: Parent task ID for subtasks (establishes container/subtask hierarchy)
+- `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
+
+#### 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.
+
+**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
+
+```json
+{
   "flow_control": {
     "pre_analysis": [
+      // === REQUIRED: Context Package Loading (Always Include) ===
       {
-        "step": "load_synthesis_specification",
-        "commands": ["bash(ls {path} 2>/dev/null)", "Read({path})"],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
+        "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": "mcp_codebase_exploration",
-        "command": "mcp__code-index__find_files() && mcp__code-index__search_code_advanced()",
-        "output_to": "codebase_structure"
+        "step": "load_role_analysis_artifacts",
+        "action": "Load role analyses from context-package.json",
+        "commands": [
+          "Read({{context_package_path}})",
+          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
+          "Read(each extracted path)"
+        ],
+        "output_to": "role_analysis_artifacts",
+        "on_error": "skip_optional"
+      },
+
+      // === OPTIONAL: Select and adapt based on task needs ===
+
+      // 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"
       }
     ],
     "implementation_approach": [
+      // === DEFAULT MODE: Agent Execution (no command field) ===
       {
         "step": 1,
         "title": "Load and analyze role analyses",
-        "description": "Load 3 role analysis files and extract quantified requirements",
+        "description": "Load role analysis files and extract quantified requirements",
         "modification_points": [
-          "Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]",
-          "Extract 15 requirements from role analyses",
-          "Parse 8 architecture decisions from system-architect analysis"
+          "Load N role analysis files: [list]",
+          "Extract M requirements from role analyses",
+          "Parse K architecture decisions"
         ],
         "logic_flow": [
-          "Read 3 role analyses from artifacts inventory",
-          "Parse architecture decisions (8 total)",
-          "Extract implementation requirements (15 total)",
+          "Read role analyses from artifacts inventory",
+          "Parse architecture decisions",
+          "Extract implementation requirements",
           "Build consolidated requirements list"
         ],
         "depends_on": [],
@@ -207,21 +350,33 @@ Generate individual `.task/IMPL-*.json` files with:
       {
         "step": 2,
         "title": "Implement following specification",
-        "description": "Implement 3 features across 5 files following consolidated role analyses",
+        "description": "Implement features following consolidated role analyses",
         "modification_points": [
-          "Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]",
-          "Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]",
-          "Implement 3 core features: [JWT authentication, role-based authorization, session management]"
+          "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 15 requirements from [synthesis_requirements]",
-          "Implement 3 features across 5 new files (600 total lines)",
-          "Modify 2 existing functions (30 lines total)",
-          "Write 25 test cases covering all features",
-          "Validate against 3 acceptance criteria"
+          "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": [
@@ -237,6 +392,72 @@ Generate individual `.task/IMPL-*.json` files with:
 }
 ```
 
+**Field Descriptions**:
+- `pre_analysis`: Context loading and preparation steps (executed sequentially before implementation)
+- `implementation_approach`: Implementation steps with dependency management (array of step objects)
+- `target_files`: Specific files/functions/lines to modify (format: `file:function:lines` for existing, `file` for new)
+
+**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.
+
+**Pre-Analysis Step Selection Guide (举一反三 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. **Selectively Include Based on Task Type**:
+   - **Architecture tasks**: Project structure + Gemini architecture analysis
+   - **Refactoring tasks**: Gemini execution flow tracing + code quality analysis
+   - **Frontend tasks**: React/Vue component searches + UI pattern analysis
+   - **Backend tasks**: Database schema + API endpoint searches
+   - **Security tasks**: Vulnerability scans + security pattern analysis
+   - **Performance tasks**: Bottleneck identification + profiling data
+
+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.
+
 **Artifact Mapping**:
 - Use `artifacts_inventory` from context package
 - Highest priority: synthesis_specification
@@ -244,14 +465,14 @@ Generate individual `.task/IMPL-*.json` files with:
 - Low priority: role_analyses
 
 ### 3. Implementation Plan Creation
-Generate `IMPL_PLAN.md` at `.workflow/{session_id}/IMPL_PLAN.md`:
+Generate `IMPL_PLAN.md` at `.workflow/active/{session_id}/IMPL_PLAN.md`:
 
 **Structure**:
 ```markdown
 ---
 identifier: {session_id}
 source: "User requirements"
-analysis: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
+analysis: .workflow/active/{session_id}/.process/ANALYSIS_RESULTS.md
 ---
 
 # Implementation Plan: {Project Title}
@@ -280,7 +501,7 @@ analysis: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
 ```
 
 ### 4. TODO List Generation
-Generate `TODO_LIST.md` at `.workflow/{session_id}/TODO_LIST.md`:
+Generate `TODO_LIST.md` at `.workflow/active/{session_id}/TODO_LIST.md`:
 
 **Structure**:
 ```markdown
@@ -312,13 +533,13 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Flat structure: IMPL_PLAN.md + TODO_LIST.md + task JSONs
 - No container tasks, all leaf tasks
 
-**Medium Tasks** (6-10 tasks):
+**Medium Tasks** (6-12 tasks):
 - Two-level hierarchy: IMPL_PLAN.md + TODO_LIST.md + task JSONs
 - Optional container tasks for grouping
 
-**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
 
 ## Quantification Requirements (MANDATORY)
 
@@ -375,7 +596,7 @@ Use `analysis_results.complexity` or task count to determine structure:
 - **Follow 5-field schema**: All task JSONs must have id, title, status, 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
@@ -384,6 +605,6 @@ Use `analysis_results.complexity` or task count to determine structure:
 - 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

.claude/skills/command-guide/reference/agents/cli-execution-agent.md

@@ -162,15 +162,15 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
 
 **Gemini/Qwen (Write)**:
 ```bash
-cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
+cd {dir} && gemini -p "..." --approval-mode yolo
 ```
 
 **Codex (Auto)**:
 ```bash
-codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
+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 -m gpt-5 --skip-git-repo-check -s danger-full-access
+codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
 ```
 
 **Cross-Directory** (Gemini/Qwen):
@@ -190,11 +190,11 @@ cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories
 
 **Session Detection**:
 ```bash
-find .workflow/ -name '.active-*' -type f
+find .workflow/active/ -name 'WFS-*' -type d
 ```
 
 **Output Paths**:
-- **With session**: `.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md`
+- **With session**: `.workflow/active/WFS-{id}/.chat/{agent}-{timestamp}.md`
 - **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md`
 
 **Log Structure**:

.claude/skills/command-guide/reference/agents/cli-explore-agent.md

@@ -22,7 +22,7 @@ description: |
   - Progressive disclosure: Quick overview → detailed analysis → dependency deep-dive
   - Context-aware filtering based on task requirements
 
-color: blue
+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.
@@ -513,37 +513,19 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-
    - Use Gemini semantic analysis as tiebreaker
    - Document uncertainty in report with attribution
 
-## Integration with Other Agents
+## Available Tools & Services
 
-### As Service Provider (Called by Others)
-
-**Planning Agents** (`action-planning-agent`, `conceptual-planning-agent`):
-- **Use Case**: Pre-planning reconnaissance to understand existing code
-- **Input**: Task description + focus areas
-- **Output**: Structural overview + dependency analysis
-- **Flow**: Planning agent → CLI explore agent (quick-scan) → Context for planning
-
-**Execution Agents** (`code-developer`, `cli-execution-agent`):
-- **Use Case**: Refactoring impact analysis before code modifications
-- **Input**: Target files/functions to modify
-- **Output**: Dependency map + risk assessment
-- **Flow**: Execution agent → CLI explore agent (dependency-map) → Safe modification strategy
-
-**UI Design Agent** (`ui-design-agent`):
-- **Use Case**: Discover existing UI components and design tokens
-- **Input**: Component directory + file patterns
-- **Output**: Component inventory + styling patterns
-- **Flow**: UI agent delegates structure analysis to CLI explore agent
-
-### As Consumer (Calls Others)
+This agent can leverage the following tools to enhance analysis:
 
 **Context Search Agent** (`context-search-agent`):
 - **Use Case**: Get project-wide context before analysis
-- **Flow**: CLI explore agent → Context search agent → Enhanced analysis with full context
+- **When to use**: Need comprehensive project understanding beyond file structure
+- **Integration**: Call context-search-agent first, then use results to guide exploration
 
-**MCP Tools**:
+**MCP Tools** (Code Index):
 - **Use Case**: Enhanced file discovery and search capabilities
-- **Flow**: CLI explore agent → Code Index MCP → Faster pattern discovery
+- **When to use**: Large codebases requiring fast pattern discovery
+- **Integration**: Prefer Code Index MCP when available, fallback to rg/bash tools
 
 ## Key Reminders
 
@@ -636,52 +618,3 @@ rg "^import .*;" --type java -n
 # Find test files
 find . -name "*Test.java" -o -name "*Tests.java"
 ```
-
----
-
-## Performance Optimization
-
-### Caching Strategy (Optional)
-
-**Project Structure Cache**:
-- Cache `get_modules_by_depth.sh` output for 1 hour
-- Invalidate on file system changes (watch .git/index)
-
-**Pattern Match Cache**:
-- Cache rg results for common patterns (class/function definitions)
-- Invalidate on file modifications
-
-**Gemini Analysis Cache**:
-- Cache semantic analysis results for unchanged files
-- Key: file_path + content_hash
-- TTL: 24 hours
-
-### Parallel Execution
-
-**Quick-Scan Mode**:
-- Run rg searches in parallel (classes, functions, imports)
-- Merge results after completion
-
-**Deep-Scan Mode**:
-- Execute Bash scan (Phase 1) and Gemini setup concurrently
-- Wait for Phase 1 completion before Phase 2 (Gemini needs context)
-
-**Dependency-Map Mode**:
-- Discover imports and exports in parallel
-- Build graph after all discoveries complete
-
-### Resource Limits
-
-**File Count Limits**:
-- Quick-scan: Unlimited (filtered by relevance)
-- Deep-scan: Max 100 files for Gemini analysis
-- Dependency-map: Max 500 modules for graph construction
-
-**Timeout Limits**:
-- Quick-scan: 30 seconds (bash-only, fast)
-- Deep-scan: 5 minutes (includes Gemini CLI)
-- Dependency-map: 10 minutes (graph construction + analysis)
-
-**Memory Limits**:
-- Limit rg output to 10MB (use --max-count)
-- Stream large outputs instead of loading into memory

.claude/skills/command-guide/reference/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/skills/command-guide/reference/agents/cli-planning-agent.md

@@ -10,7 +10,7 @@ description: |
     commentary: Agent encapsulates CLI execution + result parsing + task generation
 
   - Context: Coverage gap analysis
-    user: "Analyze coverage gaps and generate补充test task"
+    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
@@ -18,12 +18,11 @@ 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 Responsibilities
-
-1. **Execute CLI Analysis**: Run Gemini/Qwen with appropriate templates and context
-2. **Parse CLI Results**: Extract structured information (fix strategies, root causes, modification points)
-3. **Generate Task JSONs**: Create IMPL-fix-N.json or IMPL-supplement-N.json dynamically
-4. **Save Analysis Reports**: Store detailed CLI output as iteration-N-analysis.md
+**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
 
@@ -43,7 +42,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
         "file": "tests/test_auth.py",
         "line": 45,
         "criticality": "high",
-        "test_type": "integration"  // ← NEW: L0: static, L1: unit, L2: integration, L3: e2e
+        "test_type": "integration"  // L0: static, L1: unit, L2: integration, L3: e2e
       }
     ],
     "error_messages": ["error1", "error2"],
@@ -61,7 +60,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
     "tool": "gemini|qwen",
     "model": "gemini-3-pro-preview-11-2025|qwen-coder-model",
     "template": "01-diagnose-bug-root-cause.txt",
-    "timeout": 2400000,
+    "timeout": 2400000,  // 40 minutes for analysis
     "fallback": "qwen"
   },
   "task_config": {
@@ -79,16 +78,16 @@ You are a specialized execution agent that bridges CLI analysis tools with task
 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
+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
+   - Root cause analysis (RCA)
    - Fix strategy and approach
    - Modification points (files, functions, line numbers)
-   - Expected outcome
+   - Expected outcome and verification steps
 2. Extract quantified requirements:
    - Number of files to modify
    - Specific functions to fix (with line numbers)
@@ -96,18 +95,18 @@ Phase 2: Results Parsing & Strategy Extraction
 3. Generate structured analysis report (iteration-N-analysis.md)
 
 Phase 3: Task JSON Generation
-1. Load task JSON template (defined below)
+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}/.task/IMPL-fix-N.json
+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 Command Construction
+### 1. CLI Analysis Execution
 
-**Template-Based Approach with Test Layer Awareness**:
+**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}
@@ -136,7 +135,7 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
 - Consider previous iteration failures
 - Validate fix doesn't introduce new vulnerabilities
 - analysis=READ-ONLY
-" -m {model} {timeout_flag}
+" {timeout_flag}
 ```
 
 **Layer-Specific Guidance Injection**:
@@ -151,8 +150,9 @@ const layerGuidance = {
 const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches";
 ```
 
-**Error Handling & Fallback**:
+**Error Handling & Fallback Strategy**:
 ```javascript
+// Primary execution with fallback chain
 try {
   result = executeCLI("gemini", config);
 } catch (error) {
@@ -173,16 +173,18 @@ try {
     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
+}
 ```
 
-**Fallback Strategy (When All CLI Tools Fail)**:
-- Generate basic fix task based on error patterns 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 (may skip iteration)
-
-### 2. CLI Output Parsing
+### 2. Output Parsing & Task Generation
 
 **Expected CLI Output Structure** (from bug diagnosis template):
 ```markdown
@@ -220,18 +222,34 @@ try {
 ```javascript
 const parsedResults = {
   root_causes: extractSection("根本原因分析"),
-  modification_points: extractModificationPoints(),
+  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;
+}
 ```
 
-### 3. Task JSON Generation (Template Definition)
-
-**Task JSON Template for IMPL-fix-N** (Simplified):
+**Task JSON Generation** (Simplified Template):
 ```json
 {
   "id": "IMPL-fix-{iteration}",
@@ -284,9 +302,7 @@ const parsedResults = {
       {
         "step": "load_analysis_context",
         "action": "Load CLI analysis report for full failure context if needed",
-        "commands": [
-          "Read({meta.analysis_report})"
-        ],
+        "commands": ["Read({meta.analysis_report})"],
         "output_to": "full_failure_analysis",
         "note": "Analysis report contains: failed_tests, error_messages, pass_rate, root causes, previous_attempts"
       }
@@ -334,19 +350,17 @@ const parsedResults = {
 
 **Template Variables Replacement**:
 - `{iteration}`: From context.iteration
-- `{test_type}`: Dominant test type from failed_tests (e.g., "integration", "unit")
+- `{test_type}`: Dominant test type from failed_tests
 - `{dominant_test_type}`: Most common test_type in failed_tests array
-- `{layer_specific_approach}`: Guidance based on test layer from layerGuidance map
+- `{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 from parsed CLI output
+- `{modification_points}`: Array of file:function:lines
 - `{timestamp}`: ISO 8601 timestamp
-- `{parent_task_id}`: ID of the parent test task (e.g., "IMPL-002")
-- `{file1}`, `{file2}`, etc.: Specific file paths from modification_points
-- `{specific_change_1}`, etc.: Change descriptions for each modification point
+- `{parent_task_id}`: ID of parent test task
 
-### 4. Analysis Report Generation
+### 3. Analysis Report Generation
 
 **Structure of iteration-N-analysis.md**:
 ```markdown
@@ -373,6 +387,7 @@ pass_rate: {pass_rate}%
 - **Error**: {test.error}
 - **File**: {test.file}:{test.line}
 - **Criticality**: {test.criticality}
+- **Test Type**: {test.test_type}
 {endforeach}
 
 ## Root Cause Analysis
@@ -403,15 +418,16 @@ See: `.process/iteration-{iteration}-cli-output.txt`
 
 ### CLI Execution Standards
 - **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
-- **Fallback Chain**: Gemini → Qwen (if Gemini fails with 429/404)
+- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
 - **Error Context**: Include full error details in failure reports
-- **Output Preservation**: Save raw CLI output for debugging
+- **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
@@ -430,19 +446,23 @@ See: `.process/iteration-{iteration}-cli-output.txt`
 - **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)
+- 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)
 
-## CLI Tool Configuration
+## Configuration & Examples
 
-### Gemini Configuration
+### CLI Tool Configuration
+
+**Gemini Configuration**:
 ```javascript
 {
   "tool": "gemini",
@@ -452,11 +472,12 @@ See: `.process/iteration-{iteration}-cli-output.txt`
     "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)
+**Qwen Configuration (Fallback)**:
 ```javascript
 {
   "tool": "qwen",
@@ -464,47 +485,12 @@ See: `.process/iteration-{iteration}-cli-output.txt`
   "templates": {
     "test-failure": "01-diagnose-bug-root-cause.txt",
     "coverage-gap": "02-analyze-code-patterns.txt"
-  }
+  },
+  "timeout": 2400000  // 40 minutes
 }
 ```
 
-## Integration with test-cycle-execute
-
-**Orchestrator Call Pattern**:
-```javascript
-// When pass_rate < 95%
-Task(
-  subagent_type="cli-planning-agent",
-  description=`Analyze test failures and generate fix task (iteration ${iteration})`,
-  prompt=`
-    ## Context Package
-    ${JSON.stringify(contextPackage, null, 2)}
-
-    ## Your Task
-    1. Execute CLI analysis using ${cli_config.tool}
-    2. Parse CLI output and extract fix strategy
-    3. Generate IMPL-fix-${iteration}.json with structured task definition
-    4. Save analysis report to .process/iteration-${iteration}-analysis.md
-    5. Report success and task ID back to orchestrator
-  `
-)
-```
-
-**Agent Response**:
-```javascript
-{
-  "status": "success",
-  "task_id": "IMPL-fix-{iteration}",
-  "task_path": ".workflow/{session}/.task/IMPL-fix-{iteration}.json",
-  "analysis_report": ".process/iteration-{iteration}-analysis.md",
-  "cli_output": ".process/iteration-{iteration}-cli-output.txt",
-  "summary": "{fix_strategy.approach first 100 chars}",
-  "modification_points_count": {count},
-  "estimated_complexity": "low|medium|high"
-}
-```
-
-## Example Execution
+### Example Execution
 
 **Input Context**:
 ```json
@@ -530,24 +516,45 @@ Task(
   "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 Steps**:
-1. Detect test_type: "integration" → Apply integration-specific diagnosis
-2. Execute: `gemini -p "PURPOSE: Analyze integration test failure... [layer-specific context]"`
-   - CLI prompt includes: "Examine component interactions, data flow, interface contracts"
-   - Guidance: "Analyze full call stack and data flow across components"
-3. Parse: Extract RCA, 修复建议, 验证建议 sections
-4. Generate: IMPL-fix-1.json (SIMPLIFIED) with:
+**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, not embedded data)
+   - meta.analysis_report: ".process/iteration-1-analysis.md" (reference)
    - meta.test_layer: "integration"
-   - Requirements: "Fix 1 integration test failures by applying the provided fix strategy"
-   - fix_strategy.modification_points: ["src/auth/auth.service.ts:validateToken:45-60", "src/middleware/auth.middleware.ts:checkExpiry:120-135"]
+   - 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}
-   - **NO failure_context object** - full context available via analysis_report reference
-5. Save: iteration-1-analysis.md with full CLI output, layer context, failed_tests details, previous_attempts
-6. Return: task_id="IMPL-fix-1", test_layer="integration", status="success"
+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/skills/command-guide/reference/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/skills/command-guide/reference/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/skills/command-guide/reference/agents/test-context-search-agent.md

@@ -304,7 +304,7 @@ if (!validation.all_passed()) {
 ## Output Location
 
 ```
-.workflow/{test_session_id}/.process/test-context-package.json
+.workflow/active/{test_session_id}/.process/test-context-package.json
 ```
 
 ## Helper Functions Reference

.claude/skills/command-guide/reference/agents/ui-design-agent.md

@@ -217,11 +217,6 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
 
 ### Structure Optimization
 
-**Layout Structure Benefits**:
-- Eliminates redundancy between structure and styling
-- Layout properties co-located with DOM elements
-- Responsive overrides apply directly to affected elements
-- Single source of truth for each element
 
 **Component State Coverage**:
 - Interactive components (button, input, dropdown) MUST define: default, hover, focus, active, disabled
@@ -784,12 +779,7 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
 - usage_guide OPTIONAL for specialized components (can be simplified or omitted)
 - extraction_metadata.code_snippets ONLY present in Code Import mode
 
-**Structure Optimization Benefits**:
-- Eliminates redundancy between dom_structure and css_layout_rules
-- Layout properties are co-located with corresponding DOM elements
-- Responsive overrides apply directly to the element they affect
-- Single source of truth for each element's structure and layout
-- Easier to maintain and understand hierarchy
+
 
 ### animation-tokens.json