refactor: Enhance agent definitions and workflow documentation structure

- Update agent role definitions with clearer responsibilities and capabilities
- Refine task execution workflows with improved context gathering protocols
- Enhance tool implementation guide with better command examples
- Streamline workflow architecture documentation for better clarity

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

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

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

@@ -22,6 +22,10 @@ You are a pure execution agent specialized in creating actionable implementation
 ## Execution Process
 
 ### Input Processing
+**What you receive:**
+- **pre_analysis configuration**: Multi-step array format with action, template, method fields
+- **Brief actions**: 2-3 word descriptions to expand into comprehensive analysis tasks
+
 **What you receive:**
 - Task requirements and context
 - Control flags from command layer (DEEP_ANALYSIS_REQUIRED, etc.)
@@ -30,10 +34,11 @@ You are a pure execution agent specialized in creating actionable implementation
 ### Execution Flow
 ```
 1. Parse input requirements and extract control flags
-2. IF DEEP_ANALYSIS_REQUIRED flag present:
+2. Process pre_analysis configuration:
-     → Check for analysis method markers:
+   → Process multi-step array: Sequential analysis steps
-       - [GEMINI_CLI_REQUIRED] → Execute comprehensive Gemini CLI analysis using gemini-wrapper
+   → Check for analysis marker:
-       - [CODEX_CLI_REQUIRED] → Execute autonomous Codex CLI analysis
+       - [MULTI_STEP_ANALYSIS] → Execute sequential analysis steps with specified templates and methods
+   → Expand brief actions into comprehensive analysis tasks
    → Use analysis results for planning context
 3. Assess task complexity (simple/medium/complex)
 4. Create staged implementation plan
@@ -41,32 +46,36 @@ You are a pure execution agent specialized in creating actionable implementation
 6. Update workflow structure
 ```
 
-**Analysis CLI Usage Standards**:
+**Pre-Execution Analysis Standards**:
-- **Gemini CLI**: Use task-specific paths: `bash(~/.claude/scripts/gemini-wrapper -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md}")`
+- **Multi-step Pre-Analysis**: Execute comprehensive analysis BEFORE implementation begins
-- **Codex CLI**: Use task-specific paths: `bash(codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")`
+  - **Purpose**: Gather context, understand patterns, identify requirements before coding
+  - **Sequential Processing**: Process each step sequentially, expanding brief actions
+  - **Example**: "analyze auth" → "Analyze existing authentication patterns, identify current implementation approaches, understand dependency relationships"
+  - **Template Usage**: Use full template paths with $(cat template_path) for enhanced prompts
+  - **Method Selection**: Use method specified in each step (gemini/codex/manual/auto-detected)
+- **CLI Commands**:
+  - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")`
+  - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [expanded_action]")`
 - **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md
 
-### Deep Analysis Execution
+### Pre-Execution Analysis
-**When DEEP_ANALYSIS_REQUIRED flag is present:**
+**When [MULTI_STEP_ANALYSIS] marker is present:**
 
-#### Gemini CLI Analysis (Pattern-Based)
+#### Multi-Step Pre-Analysis Execution
-**When [GEMINI_CLI_REQUIRED] marker present:**
+1. Process each analysis step sequentially from pre_analysis array
-1. Execute comprehensive Gemini CLI analysis across 4 dimensions:
+2. For each step:
+   - Expand brief action into comprehensive analysis task
+   - Use specified template with $(cat template_path)
+   - Execute with specified method (gemini/codex/manual/auto-detected)
+3. Accumulate results across all steps for comprehensive context
+4. Use consolidated analysis to inform implementation stages and task breakdown
+
+#### Analysis Dimensions Coverage
 - Architecture patterns and component relationships
 - Implementation conventions and coding standards
 - Module dependencies and integration points
 - Testing requirements and coverage patterns
-2. Consolidate analysis results for planning context
+- Security considerations and performance implications
-3. Use analysis to inform implementation stages and task breakdown
-
-#### Codex CLI Analysis (Autonomous Development)
-**When [CODEX_CLI_REQUIRED] marker present:**
-1. Execute autonomous Codex CLI analysis:
-   - Intelligent file discovery and code pattern recognition
-   - Autonomous implementation strategy development
-   - System-wide impact assessment and integration planning
-   - Automated testing and validation approach recommendations
-2. Integrate autonomous analysis results into planning framework
 3. Use Codex insights to create self-guided implementation stages
 
 ## Core Functions

.claude/agents/code-developer.md

@@ -38,26 +38,26 @@ You are a code execution specialist focused on implementing high-quality, produc
 IF context sufficient for implementation:
     → Proceed with execution
 ELIF context insufficient OR task has analysis marker:
-    → Check marker type:
+    → Check for [MULTI_STEP_ANALYSIS] marker:
-       - [GEMINI_CLI_REQUIRED] → Execute Gemini CLI for codebase analysis (MANDATORY)
+       - Execute comprehensive pre-analysis BEFORE implementation begins
-       - [CODEX_CLI_REQUIRED] → Execute Codex CLI for autonomous context gathering (MANDATORY)
+       - Process each step with specified method (gemini/codex/manual/auto-detected)
+       - Expand brief actions into comprehensive analysis tasks
     → Extract patterns and conventions
     → Proceed with execution
 ```
 
-**Analysis CLI Marker System**:
+**Pre-Execution Analysis System**:
-- **[GEMINI_CLI_REQUIRED]**: Mandatory Gemini analysis flag
+- **[MULTI_STEP_ANALYSIS]**: Mandatory pre-execution analysis flag
-  - **Trigger**: Auto-added when task.analysis_source = "gemini" or scope > 3 files (default)
+  - **Trigger**: Auto-added when task.pre_analysis is an array (default format)
-  - **Action**: MUST run Gemini CLI first to gather context
+  - **Action**: MUST run multi-step pre-analysis first to gather comprehensive context
-  - **Purpose**: Ensures code aligns with existing patterns through pattern-based analysis
+  - **Purpose**: Ensures code aligns with existing patterns through comprehensive pre-execution analysis
-- **[CODEX_CLI_REQUIRED]**: Mandatory Codex analysis flag
-  - **Trigger**: Auto-added when task.analysis_source = "codex"
-  - **Action**: MUST run Codex CLI in autonomous mode first to gather context
-  - **Purpose**: Enables autonomous development with intelligent file discovery and code generation
 
-**Analysis CLI Usage Standards**:
+**Pre-Analysis CLI Usage Standards**:
-- **Gemini CLI**: Use task-specific paths from JSON: `bash(~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")`
+- **Multi-step Processing**: Execute each analysis step sequentially with specified templates
-- **Codex CLI**: Use task-specific paths from JSON: `bash(codex --full-auto exec "$(~/.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")`
+- **Method Selection**: Use method specified in each step (gemini/codex/manual/auto-detected)
+- **CLI Commands**:
+  - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")`
+  - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [expanded_action]")`
 - **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md
 
 

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

@@ -50,54 +50,58 @@ You will review code changes AND handle test implementation by understanding the
 ## Analysis CLI Context Activation Rules
 
 **🎯 Analysis Marker Detection**
-When task assignment includes analysis markers:
+When task assignment includes analysis marker:
-- **[GEMINI_CLI_REQUIRED]**: Execute Gemini CLI context gathering as first step
+- **[MULTI_STEP_ANALYSIS]**: Execute sequential analysis steps with specified templates, expanding brief actions
-- **[CODEX_CLI_REQUIRED]**: Execute Codex CLI autonomous analysis as first step
+
+**Multi-Step Analysis Support**:
+- **Process pre_analysis array**: Handle multi-step array format
+- **Expand brief actions**: Convert 2-3 word descriptions into comprehensive analysis tasks
+- **Sequential execution**: Execute each analysis step in order, accumulating context
+- **Template integration**: Use full template paths for enhanced analysis prompts
 
 **Context Gathering Decision Logic**:
 ```
-IF task contains [GEMINI_CLI_REQUIRED] flag:
+IF task contains [MULTI_STEP_ANALYSIS] flag:
-    → Execute Gemini CLI context gathering (MANDATORY)
+    → Execute each analysis step sequentially with specified templates
-    → Use pattern-based code review analysis
+    → Expand brief actions into comprehensive analysis tasks
-ELIF task contains [CODEX_CLI_REQUIRED] flag:
+    → Use method specified in each step (gemini/codex/manual/auto-detected)
-    → Execute Codex CLI autonomous analysis (MANDATORY)  
+    → Accumulate results for comprehensive context
-    → Use autonomous development context for review
 ELIF reviewing >3 files OR security changes OR architecture modifications:
-    → Execute Gemini CLI context gathering (AUTO-TRIGGER, default)
+    → Execute default multi-step analysis (AUTO-TRIGGER)
 ELSE:
     → Proceed with review using standard quality checks
 ```
 
-## Context Gathering Phase (Execute When Required)
+## Multi-Step Pre-Analysis Phase (Execute When Required)
 
-### Gemini CLI Context Gathering
+### Multi-Step Analysis Execution
-When [GEMINI_CLI_REQUIRED] flag is present or complexity triggers apply, gather precise, change-focused context:
+When [MULTI_STEP_ANALYSIS] flag is present, execute comprehensive pre-review analysis:
 
-Use the targeted review context template:
+Process each step from pre_analysis array sequentially:
-@~/.claude/workflows/tools-implementation-guide.md
 
-**Gemini CLI Command**:
+**Multi-Step Analysis Process**:
+1. For each analysis step:
+   - Extract action, template, method from step configuration
+   - Expand brief action into comprehensive analysis task
+   - Execute with specified method and template
+
+**Example CLI Commands**:
 ```bash
-bash(~/.claude/scripts/gemini-wrapper -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md} [review-analysis-prompt]")
+# For method="gemini"
+bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")
+
+# For method="codex"
+bash(codex --full-auto exec "$(cat template_path) [expanded_action]")
 ```
 
-This executes a change-specific Gemini CLI command that identifies:
+This executes comprehensive pre-review analysis that covers:
 - **Change understanding**: What specific task was being implemented
 - **Repository conventions**: Standards used in similar files and functions
 - **Impact analysis**: Other code that might be affected by these changes
 - **Test coverage validation**: Whether changes are properly tested
 - **Integration verification**: If necessary integration points are handled
-
+- **Security implications**: Potential security considerations
-### Codex CLI Context Gathering  
+- **Performance impact**: Performance-related changes and implications
-When [CODEX_CLI_REQUIRED] flag is present, execute autonomous analysis:
-
-Use the autonomous development context template:
-@~/.claude/workflows/tools-implementation-guide.md
-
-**Codex CLI Command**:
-```bash
-bash(codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [autonomous-review-prompt]")
-```
 
 This executes autonomous Codex CLI analysis that provides:
 - **Autonomous understanding**: Intelligent discovery of implementation context

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

@@ -37,9 +37,8 @@ You are a conceptual planning specialist focused on single-role strategic thinki
 ## Analysis Method Integration
 
 ### Detection and Activation
-When receiving task prompt, check for analysis markers:
+When receiving task prompt, check for analysis marker:
-- **[GEMINI_CLI_REQUIRED]** - Execute mandatory Gemini CLI pattern-based analysis
+- **[MULTI_STEP_ANALYSIS]** - Execute mandatory multi-step pre-execution analysis
-- **[CODEX_CLI_REQUIRED]** - Execute mandatory Codex CLI autonomous analysis
 - **ASSIGNED_ROLE** - Extract the specific role for focused analysis
 - **ANALYSIS_DIMENSIONS** - Load role-specific analysis dimensions
 
@@ -50,20 +49,24 @@ def handle_analysis_markers(prompt):
     dimensions = extract_value("ANALYSIS_DIMENSIONS", prompt)
     topic = extract_topic(prompt)
 
-    if "[GEMINI_CLI_REQUIRED]" in prompt:
+    if "[MULTI_STEP_ANALYSIS]" in prompt:
-        for dimension in dimensions:
+        analysis_steps = extract_pre_analysis_array(prompt)
+        for step in analysis_steps:
+            action = step["action"]
+            template = step["template"]
+            method = step["method"]
+
+            expanded_action = expand_brief_action(action, role, topic)
+
+            if method == "gemini":
                 result = execute_gemini_cli(
-                command=f"bash(~/.claude/scripts/gemini-wrapper -p \"$(.claude/scripts/read-task-paths.sh [task-json-file]) @{{CLAUDE.md}} {dimension}\")",
+                    command=f"bash(~/.claude/scripts/gemini-wrapper -p \"$(cat {template}) {expanded_action}\")",
-                dimension=dimension,
                     role_context=role,
                     topic=topic
                 )
-            integrate_to_role_output(result, role)
+            elif method == "codex":
-    
-    elif "[CODEX_CLI_REQUIRED]" in prompt:
                 result = execute_codex_cli(
-            command=f"bash(codex --full-auto exec \"$(.claude/scripts/read-task-paths.sh [task-json-file]) {topic}\")",
+                    command=f"bash(codex --full-auto exec \"$(cat {template}) {expanded_action}\")",
-            autonomous_analysis=True,
                     role_context=role, 
             topic=topic
         )

.claude/commands/task/create.md

@@ -72,7 +72,7 @@ Status: pending
 
 ### Auto-Population Strategy
 - **Detailed info**: Extract from task description and scope
-- **Missing info**: Mark `analysis_source` as "gemini" for later analysis
+- **Missing info**: Mark `pre_analysis` as multi-step array format for later pre-analysis
 - **Basic structure**: Initialize with standard template
 
 ### Analysis Triggers

.claude/commands/task/execute.md

@@ -189,7 +189,13 @@ This is the simplified data structure loaded to provide context for task executi
         "performance_considerations": "JWT validation adds ~10ms per request, OAuth callbacks may timeout",
         "error_handling": "Ensure sensitive authentication errors don't leak user enumeration data"
       },
-      "analysis_source": "gemini"
+      "pre_analysis": [
+        {
+          "action": "analyze patterns",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+          "method": "gemini"
+        }
+      ]
     }
   },
   "workflow": {

.claude/commands/workflow/execute.md

@@ -23,19 +23,20 @@ The intelligent execution approach focuses on:
 - **Dynamic task orchestration** - Coordinate based on discovered task relationships
 - **Progress tracking** - Update task status after agent completion
 
-**Analysis Markers**:
+**Analysis Marker**:
-- **[GEMINI_CLI_REQUIRED]**: Forces agent to use Gemini CLI for pattern-based codebase analysis
+- **[MULTI_STEP_ANALYSIS]**: Indicates sequential pre-execution analysis required
-  - **Auto-trigger**: When task.analysis_source = "gemini" OR scope > 3 files (default)
+  - **Auto-trigger**: When task.pre_analysis is an array (default format)
-  - **Agent Action**: MUST execute Gemini CLI as first step
+  - **Agent Action**: Execute comprehensive pre-analysis BEFORE implementation begins
-- **[CODEX_CLI_REQUIRED]**: Forces agent to use Codex CLI for autonomous development analysis
+    - Process each step sequentially with specified templates and methods
-  - **Auto-trigger**: When task.analysis_source = "codex"
+    - Expand brief actions into full analysis tasks
-  - **Agent Action**: MUST execute Codex CLI in autonomous mode as first step
+    - Gather context, understand patterns, identify requirements
+    - Use method specified in each step (gemini/codex/manual/auto-detected)
 
-**analysis_source to Marker Mapping**:
+**pre_analysis to Marker Mapping**:
-- **"gemini"** → Add [GEMINI_CLI_REQUIRED]
+- **Array format (multi-step pre-analysis)**:
-- **"codex"** → Add [CODEX_CLI_REQUIRED]
+  - Add [MULTI_STEP_ANALYSIS] - triggers comprehensive pre-execution analysis
-- **"auto-detected"** + scope > 3 files → Add [GEMINI_CLI_REQUIRED] (default)
+  - Agent processes each step with specified method (gemini/codex/manual/auto-detected)
-- **"manual"** → No marker added
+  - Agent expands each action into comprehensive analysis based on template
 
 ## Execution Flow
 
@@ -65,14 +66,13 @@ Workflow Discovery:
 *Session: WFS-[topic-slug]*
 
 ## Execution Plan
-- [ ] **TASK-001**: [Agent: planning-agent] [GEMINI_CLI_REQUIRED] Design auth schema (impl-1.1)
+- [ ] **TASK-001**: [Agent: planning-agent] [MULTI_STEP_ANALYSIS] Design auth schema (impl-1.1)
-- [ ] **TASK-002**: [Agent: code-developer] [CODEX_CLI_REQUIRED] Implement auth logic (impl-1.2)  
+- [ ] **TASK-002**: [Agent: code-developer] [MULTI_STEP_ANALYSIS] Implement auth logic (impl-1.2)  
 - [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
 - [ ] **TASK-004**: Update task statuses and session state
 
 **Marker Legend**:
-- [GEMINI_CLI_REQUIRED] = Agent must use Gemini CLI for pattern analysis
+- [MULTI_STEP_ANALYSIS] = Agent must execute multi-step pre-execution analysis
-- [CODEX_CLI_REQUIRED] = Agent must use Codex CLI for autonomous analysis
 - [PREPARATION_INCLUDED] = Task includes preparation phase (analyze then implement)
 ```
 
@@ -124,7 +124,23 @@ For each executable task:
         "performance_considerations": "Index JWT fields for faster lookups",
         "error_handling": "Graceful schema validation errors"
       },
-      "analysis_source": "auto-detected"
+      "pre_analysis": [
+        {
+          "action": "analyze auth",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+          "method": "gemini"
+        },
+        {
+          "action": "security review",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/security.txt",
+          "method": "gemini"
+        },
+        {
+          "action": "implement feature",
+          "template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
+          "method": "codex"
+        }
+      ]
     }
   },
   "workflow": {
@@ -144,14 +160,14 @@ For each executable task:
 - **Risk Awareness**: Alert agents to implementation.context_notes.risks before execution
 - **Workflow Integration**: Include session state and IMPL_PLAN.md context
 - **Scope Focus**: Direct agents to specific files from implementation.files[].path
-- **Gemini Marker**: Auto-add [GEMINI_CLI_REQUIRED] when analysis_source = "gemini"
+- **Analysis Marker**: Auto-add [MULTI_STEP_ANALYSIS] when pre_analysis is array format
 - **Merged Task Handling**: Add [PREPARATION_INCLUDED] marker when preparation_complexity exists
 
 ### 4. Agent Execution & Progress Tracking
 
 ```bash
 Task(subagent_type="code-developer",
-     prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Analyze auth patterns and implement JWT authentication system
+     prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Analyze auth patterns and implement JWT authentication system
 
      Task Context: impl-1.2 - Saturated task with merged preparation and execution
 
@@ -241,7 +257,7 @@ Based on discovered task data:
 ```bash
 # Agent receives complete discovered context with saturation handling
 Task(subagent_type="code-developer",
-     prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Execute impl-1.2: Analyze and implement auth logic
+     prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Execute impl-1.2: Analyze and implement auth logic
 
      TASK TYPE: Saturated task (preparation_complexity: simple)
 

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

@@ -90,8 +90,8 @@ Task(action-planning-agent):
     - Execute comprehensive Gemini CLI analysis (4 dimensions)
     - Skip PRD processing (no PRD provided)
     - Skip session inheritance (standalone planning)
-    - Force GEMINI_CLI_REQUIRED flag = true
+    - Force MULTI_STEP_ANALYSIS flag = true
-    - Set analysis_source = "gemini" (深度分析固定值)
+    - Set pre_analysis = multi-step array format with comprehensive analysis steps
     - Generate hierarchical task decomposition (max 2 levels: impl-N.M)
     - Create detailed IMPL_PLAN.md with subtasks
     - Generate TODO_LIST.md for tracking
@@ -126,8 +126,8 @@ def process_plan_deep_command(input):
     TASK: {task_description}
     
     MANDATORY FLAGS:
-    - GEMINI_CLI_REQUIRED = true
+    - MULTI_STEP_ANALYSIS = true
-    - analysis_source = "gemini" (固定设置)
+    - pre_analysis = multi-step array format for comprehensive pre-analysis
     - FORCE_PARALLEL_ANALYSIS = true
     - SKIP_PRD = true
     - SKIP_SESSION_INHERITANCE = true

.claude/commands/workflow/plan.md

@@ -24,7 +24,7 @@ Creates actionable implementation plans with intelligent input source detection.
 
 ### Analysis Method Flag (--AM)
 Optional flag to specify which CLI tool to use for context analysis:
-- **gemini** (default): Uses Gemini CLI for pattern-based analysis and architectural understanding
+- **gemini** (default): Uses Gemini CLI for pattern-based analysis, architectural understanding, and broader context acquisition
 - **codex**: Uses Codex CLI for autonomous development context gathering with intelligent file discovery
 
 **Examples**:
@@ -67,7 +67,30 @@ The command automatically detects input type:
 - Uses active session if available
 - Generates session ID: WFS-[topic-slug]
 
+### Pre-Planning Analysis
+⚠️ **CRITICAL**: Determine decomposition strategy BEFORE generating any plan documents
+
+**Required Pre-Analysis Steps**:
+1. **Complexity Assessment**: Analyze requirements to determine total saturated task count
+2. **Decomposition Strategy**: Based on complexity, decide:
+   - Task structure (flat vs hierarchical)
+   - Subtask necessity (>15 tasks triggers decomposition)
+   - Task saturation level (merged vs separated)
+3. **Quantity Prediction**: Calculate expected:
+   - Total main tasks (IMPL-XXX)
+   - Subtasks per main task (impl-N.M)
+   - Container vs leaf task ratio
+
+**Pre-Planning Outputs**:
+- Complexity level: Simple (≤8) | Medium (9-15) | Complex (>15)
+- Decomposition approach: Flat | Two-level hierarchy
+- Estimated task count: [number] main tasks, [number] total leaf tasks
+- Document set: Which documents will be generated (IMPL_PLAN.md, TODO_LIST.md, .task/*.json)
+
+**Only after completing pre-planning analysis**: Proceed to generate actual plan documents
+
 ### Complexity Detection with Saturation
+*Based on Pre-Planning Analysis results:*
 - **Simple**: ≤8 saturated tasks → Direct IMPL_PLAN.md
 - **Medium**: 9-15 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
 - **Complex**: >15 saturated tasks → Full decomposition
@@ -93,6 +116,7 @@ The command automatically detects input type:
 - IMPL-002: Implement data export functionality (includes processing logic, UI, file generation)
 
 ### Task Generation with Saturation Control
+*Using decomposition strategy determined in Pre-Planning Analysis:*
 - **Task Saturation Assessment**: Evaluates whether to merge preparation and execution
 - **Default merge mode**: "Analyze and implement X" instead of "Analyze X" + "Implement X"
 - **Smart splitting**: Only separate when preparation complexity > threshold
@@ -158,9 +182,14 @@ Evaluates whether to merge preparation and execution:
 - **Maximum depth**: 2 levels (impl-N.M) to maintain manageable hierarchy
 
 ### Implementation Field Requirements
-- **analysis_source**: Determines context gathering method (manual|auto-detected|gemini|codex)
+- **pre_analysis**: Multi-step analysis configuration array containing:
-- **Auto-assignment**: manual (user provides details) → auto-detected (system infers) → gemini/codex (needs analysis)
+  - `action`: Brief 2-3 word description (e.g., "analyze patterns", "review security") - agent expands based on context
-- **Required fields**: files (with path/location/modifications), context_notes, analysis_source
+  - `template`: Full template path (e.g., "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt")
+  - `method`: Analysis method ("manual"|"auto-detected"|"gemini"|"codex")
+  - **Agent Behavior**: Agents interpret brief actions and expand them into comprehensive analysis tasks
+  - **Execution**: Steps processed sequentially, results accumulated for comprehensive context
+- **Auto-assignment**: Defaults to appropriate multi-step configuration based on complexity
+- **Required fields**: files (with path/location/modifications), context_notes, pre_analysis
 - **Paths format**: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json")
 
 ## Session Check Process

.claude/workflows/task-core.md

@@ -71,7 +71,18 @@ All task files use this unified 10-field structure:
       "performance_considerations": "JWT adds ~5ms latency",
       "error_handling": "No sensitive data in errors"
     },
-    "analysis_source": "manual|gemini|codex|auto-detected"
+    "pre_analysis": [
+      {
+        "action": "analyze patterns",
+        "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+        "method": "gemini"
+      },
+      {
+        "action": "implement feature",
+        "template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
+        "method": "codex"
+      }
+    ]
   }
 }
 ```
@@ -96,7 +107,7 @@ All task files use this unified 10-field structure:
 - **performance_considerations**: Performance impact
 - **error_handling**: Error handling requirements
 
-### analysis_source Options
+### pre_analysis Options
 - **manual**: User-provided details
 - **auto-detected**: System-inferred
 - **gemini**: Requires Gemini CLI analysis

.claude/workflows/tools-implementation-guide.md

@@ -22,6 +22,39 @@ type: technical-guideline
 
 **Usage**: `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)`
 
+### 📚 Template Quick Reference Map
+
+**Full Path Format**: All templates use complete paths starting with `~/.claude/`
+
+**Analysis Templates**:
+- `~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt` - Pattern detection and convention analysis
+- `~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt` - System architecture review
+- `~/.claude/workflows/cli-templates/prompts/analysis/security.txt` - Security vulnerability assessment
+- `~/.claude/workflows/cli-templates/prompts/analysis/performance.txt` - Performance bottleneck analysis
+- `~/.claude/workflows/cli-templates/prompts/analysis/quality.txt` - Code quality and maintainability review
+
+**Development Templates**:
+- `~/.claude/workflows/cli-templates/prompts/development/feature.txt` - Feature implementation guidance
+- `~/.claude/workflows/cli-templates/prompts/development/component.txt` - Component development patterns
+- `~/.claude/workflows/cli-templates/prompts/development/refactor.txt` - Refactoring strategies
+- `~/.claude/workflows/cli-templates/prompts/development/testing.txt` - Test generation and coverage
+- `~/.claude/workflows/cli-templates/prompts/development/debugging.txt` - Issue diagnosis and resolution
+
+**Planning Templates**:
+- `~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt` - Task decomposition strategy
+- `~/.claude/workflows/cli-templates/prompts/planning/migration.txt` - Migration planning and execution
+
+**Automation Templates**:
+- `~/.claude/workflows/cli-templates/prompts/automation/scaffold.txt` - Project scaffolding automation
+- `~/.claude/workflows/cli-templates/prompts/automation/deployment.txt` - Deployment configuration
+
+**Review Templates**:
+- `~/.claude/workflows/cli-templates/prompts/review/code-review.txt` - Code review checklist
+
+**Integration Templates**:
+- `~/.claude/workflows/cli-templates/prompts/integration/api-design.txt` - API design patterns
+- `~/.claude/workflows/cli-templates/prompts/integration/database.txt` - Database schema design
+
 ### 📂 File Pattern Wildcards
 
 ```bash

.claude/workflows/workflow-architecture.md

@@ -152,7 +152,18 @@ All task files use this 10-field schema:
       "performance_considerations": "JWT validation will add approximately 5ms latency",
       "error_handling": "Ensure sensitive information is not leaked in error responses"
     },
-    "analysis_source": "manual|gemini|codex|auto-detected"
+    "pre_analysis": [
+      {
+        "action": "analyze patterns",
+        "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+        "method": "gemini"
+      },
+      {
+        "action": "generate implementation",
+        "template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
+        "method": "codex"
+      }
+    ]
   }
 }
 ```
@@ -221,7 +232,7 @@ The **implementation** field provides detailed code implementation guidance with
 - **performance_considerations**: Performance impact assessment
 - **error_handling**: Error handling requirements
 
-#### analysis_source - Information Source Identifier
+#### pre_analysis - Information Source Identifier
 - **manual**: Detailed information manually provided by user
 - **gemini**: Automatically obtained through Gemini CLI analysis
 - **codex**: Automatically obtained through Codex CLI analysis
@@ -419,7 +430,7 @@ generate_todo_list_from_json .task/
 5. **Status Consistency**: Status values from defined enumeration
 6. **Required Fields**: All 9 core fields must be present
 7. **Implementation Structure**: implementation.files array must contain valid file paths
-8. **Analysis Source**: analysis_source must be one of: manual|gemini|codex|auto-detected
+8. **Pre-Analysis Source**: pre_analysis must be multi-step array format with action, template, method
 
 ### Session Consistency Checks
 ```bash