feat: enhance pre_analysis with comprehensive CLI examples and dynamic guidance

- Add extensive pre_analysis examples organized by category:
  - Required context loading steps
  - Project structure analysis
  - Local codebase exploration (bash/rg/find)
  - Gemini CLI analysis (architecture, execution flow)
  - Qwen CLI analysis (code quality, fallback)
  - MCP tools integration
  - Tech-specific searches (React, database, etc.)

- Add "举一反三" (draw inferences) principle with detailed guidance:
  - Dynamic step selection based on task type
  - Tool selection strategy (Gemini/Qwen/Bash/MCP)
  - Task-specific adaptation examples (security, performance, API)
  - Command composition patterns

- Emphasize that examples are reference templates, not fixed requirements
- Agent must dynamically select and adapt steps based on actual task needs
- Provide clear guidelines for when to use each type of analysis tool

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

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

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

@@ -223,10 +223,21 @@ Generate individual `.task/IMPL-*.json` files with:
 - `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_context_package",
         "action": "Load context package for artifact paths and smart context",
@@ -245,27 +256,99 @@ Generate individual `.task/IMPL-*.json` files with:
         "output_to": "role_analysis_artifacts",
         "on_error": "skip_optional"
       },
+
+      // === PROJECT STRUCTURE ANALYSIS ===
       {
         "step": "analyze_project_architecture",
-        "action": "Analyze project module structure and depth",
+        "action": "Analyze project module structure and dependency depth",
         "commands": ["bash(~/.claude/scripts/get_modules_by_depth.sh)"],
         "output_to": "project_architecture",
         "on_error": "skip_optional"
       },
+
+      // === LOCAL CODEBASE EXPLORATION (bash/rg/find) ===
       {
-        "step": "local_codebase_exploration",
-        "action": "Explore codebase structure using local search",
+        "step": "search_existing_patterns",
+        "action": "Search for existing implementation patterns related to task",
         "commands": [
-          "bash(rg '^(function|class|interface).*[task_keyword]' --type ts -n --max-count 15)",
-          "bash(find . -name '*[task_keyword]*' -type f | grep -v node_modules | head -10)"
+          "bash(rg '^(function|class|interface).*auth' --type ts -n --max-count 20)",
+          "bash(find . -name '*auth*' -type f | grep -v node_modules | head -15)",
+          "bash(rg 'export.*Component' --type tsx -l | head -10)"
         ],
-        "output_to": "codebase_structure"
+        "output_to": "existing_patterns",
+        "on_error": "skip_optional"
       },
       {
-        "step": "mcp_codebase_exploration",
-        "action": "Explore codebase patterns using MCP tools (if available)",
-        "command": "mcp__code-index__find_files() && mcp__code-index__search_code_advanced()",
-        "output_to": "mcp_codebase_patterns",
+        "step": "analyze_dependencies",
+        "action": "Analyze package dependencies and imports",
+        "commands": [
+          "bash(cat package.json | grep -A 20 'dependencies')",
+          "bash(rg '^import.*from' --type ts -n | head -30)"
+        ],
+        "output_to": "dependency_analysis",
+        "on_error": "skip_optional"
+      },
+
+      // === GEMINI CLI ANALYSIS (Deep Pattern Analysis) ===
+      {
+        "step": "gemini_analyze_architecture",
+        "action": "Analyze architecture patterns using Gemini for comprehensive insights",
+        "command": "bash(cd [focus_path] && gemini -p 'PURPOSE: Analyze architecture patterns in auth module\\nTASK: • Identify design patterns • Extract code conventions • List dependencies\\nMODE: analysis\\nCONTEXT: @src/auth/**/* @CLAUDE.md\\nEXPECTED: Architecture pattern summary with conventions\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on reusable patterns | analysis=READ-ONLY')",
+        "output_to": "architecture_patterns",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "gemini_trace_execution_flow",
+        "action": "Trace code execution flow using Gemini (for complex logic understanding)",
+        "command": "bash(cd [focus_path] && gemini -p 'PURPOSE: Trace authentication flow execution\\nTASK: Map request flow from entry to database\\nMODE: analysis\\nCONTEXT: @src/auth/**/* @src/middleware/**/*\\nEXPECTED: Step-by-step execution trace with file:line references\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt) | Include all middleware | analysis=READ-ONLY')",
+        "output_to": "execution_flow",
+        "on_error": "skip_optional"
+      },
+
+      // === QWEN CLI ANALYSIS (Gemini Fallback or Alternative) ===
+      {
+        "step": "qwen_analyze_code_quality",
+        "action": "Analyze code quality and identify refactoring opportunities using Qwen",
+        "command": "bash(cd [focus_path] && qwen -p 'PURPOSE: Analyze code quality in auth module\\nTASK: • Identify code smells • Suggest refactoring • Check best practices\\nMODE: analysis\\nCONTEXT: @src/auth/**/*\\nEXPECTED: Code quality report with specific improvement suggestions\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on maintainability | analysis=READ-ONLY')",
+        "output_to": "code_quality_review",
+        "on_error": "skip_optional"
+      },
+
+      // === MCP TOOLS INTEGRATION ===
+      {
+        "step": "mcp_search_similar_implementations",
+        "action": "Search for similar implementations using MCP code index",
+        "command": "mcp__code-index__search_code_advanced(pattern='authentication', context_lines=5)",
+        "output_to": "similar_implementations",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "mcp_exa_research_best_practices",
+        "action": "Research best practices and patterns using Exa",
+        "command": "mcp__exa__get_code_context_exa(query='Node.js JWT authentication best practices', tokensNum=3000)",
+        "output_to": "external_best_practices",
+        "on_error": "skip_optional"
+      },
+
+      // === TECH-SPECIFIC SEARCHES (Add as needed) ===
+      {
+        "step": "search_react_components",
+        "action": "Search React component patterns (example for frontend tasks)",
+        "commands": [
+          "bash(rg 'export.*FC<.*>' --type tsx -n)",
+          "bash(find src/components -name '*.tsx' -type f | head -20)"
+        ],
+        "output_to": "react_component_patterns",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "search_database_schemas",
+        "action": "Search database schemas and models (example for backend tasks)",
+        "commands": [
+          "bash(rg '@Entity|@Table|CREATE TABLE' -n)",
+          "bash(find . -name '*.prisma' -o -name '*migration*.sql' | head -10)"
+        ],
+        "output_to": "database_schemas",
         "on_error": "skip_optional"
       }
     ],
@@ -326,6 +409,66 @@ Generate individual `.task/IMPL-*.json` files with:
 - `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)
 
+**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**: Add `gemini_analyze_architecture`, `analyze_project_architecture`
+   - **Refactoring tasks**: Add `gemini_trace_execution_flow`, `qwen_analyze_code_quality`
+   - **Frontend tasks**: Add `search_react_components`, React-specific pattern searches
+   - **Backend tasks**: Add `search_database_schemas`, API endpoint searches
+   - **Integration tasks**: Add dependency analysis, external API searches
+   - **Performance tasks**: Add profiling data searches, bottleneck analysis
+
+3. **Tool Selection Strategy**:
+   - **Gemini CLI**: Use for deep analysis (architecture, execution flow, pattern identification) when task is complex
+   - **Qwen CLI**: Use as fallback or for code quality analysis
+   - **Bash/rg/find**: Use for quick pattern matching and file discovery
+   - **MCP tools**: Use when available for enhanced semantic search and external research
+
+4. **Dynamic Adaptation Examples**:
+   ```json
+   // Example: Security audit task
+   {
+     "step": "gemini_security_analysis",
+     "action": "Analyze security vulnerabilities using Gemini",
+     "command": "bash(cd [focus_path] && gemini -p 'PURPOSE: Security audit\\nTASK: • Find SQL injection risks • Check XSS vulnerabilities • Review auth flaws\\nMODE: analysis\\nCONTEXT: @**/*\\nEXPECTED: Security vulnerability report\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/03-assess-security-risks.txt) | OWASP Top 10 focus | analysis=READ-ONLY')"
+   }
+
+   // Example: Performance optimization task
+   {
+     "step": "analyze_performance_bottlenecks",
+     "action": "Identify performance bottlenecks",
+     "commands": [
+       "bash(rg 'TODO.*performance|FIXME.*slow' -n)",
+       "bash(find . -name '*.log' -o -name 'benchmark*' | head -5)"
+     ]
+   }
+
+   // Example: API documentation task
+   {
+     "step": "search_api_endpoints",
+     "action": "Search and catalog all API endpoints",
+     "commands": [
+       "bash(rg '@(Get|Post|Put|Delete|Patch)\\(' --type ts -n)",
+       "bash(rg 'app\\.(get|post|put|delete)\\(' --type js -n)"
+     ]
+   }
+   ```
+
+5. **Command Composition Patterns**:
+   - **Single command**: For simple searches (`bash(rg 'pattern')`)
+   - **Multiple commands**: For comprehensive analysis (array of bash commands)
+   - **CLI analysis**: For deep insights (`gemini -p "..."` or `qwen -p "..."`)
+   - **MCP integration**: For semantic search and external research
+
+**Key Principle**: These examples show **HOW** to structure steps, **not WHAT** steps to include. Agent must analyze task requirements and create appropriate pre_analysis steps dynamically.
+
 **Artifact Mapping**:
 - Use `artifacts_inventory` from context package
 - Highest priority: synthesis_specification