Claude-Code-Workflow/.claude/workflows/intelligent-tools-strategy.md

name, description, type

name	description	type
intelligent-tools-strategy	Strategic decision framework for intelligent tool selection	strategic-guideline

Intelligent Tools Selection Strategy

📋 Table of Contents

1. Quick Start
2. Tool Specifications
3. Command Templates
4. Execution Configuration
5. Best Practices

---

⚡ Quick Start

Tool Overview

• Gemini: Analysis, understanding, exploration & documentation (primary)
• Qwen: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
• Codex: Development, implementation & automation

Model Selection (-m parameter)

Gemini Models:

• gemini-2.5-pro - Analysis tasks (default)
• gemini-2.5-flash - Documentation updates

Qwen Models:

• coder-model - Code analysis (default, -m optional)
• vision-model - Image analysis (rare usage)

Codex Models:

• gpt-5 - Analysis & execution (default)
• gpt5-codex - Large context tasks

Usage: tool -p "prompt" -m model-name (NOTE: -m placed AFTER prompt)

Quick Decision Matrix

Scenario	Tool	Command Pattern
Exploring/Understanding	Gemini → Qwen	cd [dir] && gemini -p "PURPOSE:... CONTEXT: @**/*"
Architecture/Analysis	Gemini → Qwen	cd [dir] && gemini -p "PURPOSE:... CONTEXT: @**/*"
Building/Fixing	Codex	codex -C [dir] --full-auto exec "PURPOSE:... MODE: auto"
Not sure?	Multiple	Use tools in parallel
Small task?	Still use tools	Tools are faster than manual work

Core Principles

• Use tools early and often - Tools are faster, more thorough, and reliable than manual approaches
• When in doubt, use both - Parallel usage provides comprehensive coverage
• Default to tools - Use specialized tools for most coding tasks, no matter how small
• Lower barriers - Engage tools immediately when encountering any complexity
• ⚠️ Write operation protection - For local codebase write/modify operations, require EXPLICIT user confirmation unless user provides clear instructions containing MODE=write or MODE=auto

---

🎯 Tool Specifications

Gemini & Qwen

Overview

• Commands: gemini (primary) | qwen (fallback)
• Strengths: Large context window, pattern recognition
• Best For: Analysis, documentation generation, code exploration, architecture review
• Permissions: Default read-only analysis, MODE=write requires explicit specification
• Default MODE: analysis (read-only)
• ⚠️ Write Trigger: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
• Priority: Prefer Gemini; use Qwen as fallback when Gemini unavailable

MODE Options

analysis (default) - Read-only analysis and documentation generation

• ⚠️ CRITICAL CONSTRAINT: Absolutely NO file creation, modification, or deletion operations
• Analysis output should be returned as text response only
• Use for: code review, architecture analysis, pattern discovery, documentation reading

write - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)

• Use for: generating documentation files, creating code files, modifying existing files

Tool Selection

# Default: Use Gemini
gemini -p "analysis prompt"

# Fallback: Use Qwen if Gemini unavailable
qwen -p "analysis prompt"

Error Handling

⚠️ Gemini 429 Behavior: May show HTTP 429 error but still return results - ignore error messages, only check if results exist (results present = success, no results = retry/fallback to Qwen)

---

Codex

Overview

• Command: codex --full-auto exec
• Strengths: Autonomous development, mathematical reasoning
• Best For: Implementation, testing, automation
• Permissions: Requires explicit MODE=auto or MODE=write specification
• Default MODE: No default, must be explicitly specified
• ⚠️ Write Trigger: Only when user explicitly requests "implement", "modify", "generate code" AND specifies MODE

MODE Options

auto - ⚠️ Autonomous development with full file operations

• Requires explicit specification
• Enables -s danger-full-access
• Use for: feature implementation, bug fixes, autonomous development

write - ⚠️ Test generation and file modification

• Requires explicit specification
• Use for: test generation, focused file modifications

Session Management

Basic Commands:

• codex resume - Resume previous interactive session (picker by default)
• codex resume --last - Resume most recent session directly
• codex -i <image_file> - Attach image(s) to initial prompt (useful for UI/design references)

Multi-task Pattern: First task uses exec, subsequent tasks use exec "..." resume --last for context continuity

Parameter Position: resume --last must be placed AFTER the prompt string at command END

Example:

# First task - establish session
codex -C project --full-auto exec "Implement auth module" --skip-git-repo-check -s danger-full-access

# Subsequent tasks - continue same session
codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access
codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s danger-full-access

Auto-Resume Decision Rules

When to use resume --last:

• Current task is related to/extends previous Codex task in conversation memory
• Current task requires context from previous implementation
• Current task is part of multi-step workflow (e.g., implement → enhance → test)
• Session memory indicates recent Codex execution on same module/feature

When NOT to use resume --last:

• First Codex task in conversation
• New independent task unrelated to previous work
• Switching to different module/feature area
• No recent Codex task in conversation memory

---

🎯 Command Templates

Universal Template Structure

Every command MUST follow this structure:

• PURPOSE - Clear goal and intent
• TASK - Specific execution task (use list format: • Task item 1 • Task item 2 • Task item 3)
• MODE - Execution mode and permission level
• CONTEXT - File references and memory context from previous sessions
• EXPECTED - Clear expected results
• RULES - Template reference and constraints (include mode constraints: analysis=READ-ONLY | write=CREATE/MODIFY/DELETE | auto=FULL operations)

---

Standard Command Formats

Gemini & Qwen Commands

# Analysis Mode (read-only, default)
# Use 'gemini' (primary) or 'qwen' (fallback)
cd [directory] && gemini -p "
PURPOSE: [clear analysis goal]
TASK: [specific analysis task]
MODE: analysis
CONTEXT: @**/* [default: all files, or specify file patterns]
EXPECTED: [expected output]
RULES: [template reference and constraints]
"

# Model Selection Examples (NOTE: -m placed AFTER prompt)
cd [directory] && gemini -p "..." -m gemini-2.5-pro      # Analysis (default)
cd [directory] && gemini -p "..." -m gemini-2.5-flash    # Documentation updates
cd [directory] && qwen -p "..."                          # coder-model (default, -m optional)
cd [directory] && qwen -p "..." -m vision-model           # Image analysis (rare)

# Write Mode (requires explicit MODE=write)
# NOTE: --approval-mode yolo must be placed AFTER the prompt
cd [directory] && gemini -p "
PURPOSE: [clear goal]
TASK: [specific task]
MODE: write
CONTEXT: @**/* [default: all files, or specify file patterns]
EXPECTED: [expected output]
RULES: [template reference and constraints]
" -m gemini-2.5-flash --approval-mode yolo

# Fallback: Replace 'gemini' with 'qwen' if Gemini unavailable
cd [directory] && qwen -p "..." # coder-model default (-m optional)

Codex Commands

# Codex Development (requires explicit MODE=auto)
# NOTE: -m, --skip-git-repo-check and -s danger-full-access must be placed at command END
codex -C [directory] --full-auto exec "
PURPOSE: [clear development goal]
TASK: [specific development task]
MODE: auto
CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
EXPECTED: [expected deliverables]
RULES: [template reference and constraints]
" -m gpt-5 --skip-git-repo-check -s danger-full-access

# Model Selection Examples (NOTE: -m placed AFTER prompt, BEFORE flags)
codex -C [directory] --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access        # Analysis & execution (default)
codex -C [directory] --full-auto exec "..." -m gpt5-codex --skip-git-repo-check -s danger-full-access   # Large context tasks

# Codex Test/Write Mode (requires explicit MODE=write)
# NOTE: -m, --skip-git-repo-check and -s danger-full-access must be placed at command END
codex -C [directory] --full-auto exec "
PURPOSE: [clear goal]
TASK: [specific task]
MODE: write
CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
EXPECTED: [expected deliverables]
RULES: [template reference and constraints]
" -m gpt-5 --skip-git-repo-check -s danger-full-access

---

Directory Context Configuration

Tool Directory Navigation:

• Gemini & Qwen: cd path/to/project && gemini -p "prompt" (or qwen)
• Codex: codex -C path/to/project --full-auto exec "task" (Codex still supports -C)
• Path types: Supports both relative (../project) and absolute (/full/path) paths
• Token analysis: For Gemini/Qwen, token counting happens in current directory

⚠️ Critical Directory Scope Rules

Once cd to a directory:

• @ references ONLY apply to current directory and its subdirectories
• @**/* = All files within current directory tree
• @*.ts = TypeScript files in current directory tree
• @src/**/* = Files within src subdirectory (if exists under current directory)
• CANNOT reference parent or sibling directories via @ alone

To reference files outside current directory (TWO-STEP REQUIREMENT):

• Step 1: Add --include-directories parameter to make external directories ACCESSIBLE
• Step 2: Explicitly reference external files in CONTEXT field with @ patterns
• ⚠️ BOTH steps are MANDATORY - missing either step will fail
• Example: cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared
• Rule: If CONTEXT contains @../dir/**/*, command MUST include --include-directories ../dir
• Without --include-directories, @ patterns CANNOT access parent/sibling directories at all

Multi-Directory Support (Gemini & Qwen)

Purpose: For large projects requiring fine-grained access across multiple directories

Use Case: When cd limits scope but you need to reference files from parent/sibling folders

Parameter: --include-directories <dir1,dir2,...>

• Includes additional directories in the workspace beyond current cd directory
• Can be specified multiple times or as comma-separated values
• Maximum 5 directories can be added
• REQUIRED when working in a subdirectory but needing context from parent or sibling directories

Syntax Options:

# Comma-separated format
gemini -p "prompt" --include-directories /path/to/project1,/path/to/project2

# Multiple flags format
gemini -p "prompt" --include-directories /path/to/project1 --include-directories /path/to/project2

# Combined with cd for focused analysis with extended context (RECOMMENDED)
cd src/auth && gemini -p "
PURPOSE: Analyze authentication with shared utilities context
TASK: Review auth implementation and its dependencies
MODE: analysis
CONTEXT: @**/* @../shared/**/* @../types/**/*
EXPECTED: Complete analysis with cross-directory dependencies
RULES: Focus on integration patterns
" --include-directories ../shared,../types

Best Practices:

• Recommended Pattern: Use cd to navigate to primary focus directory, then use --include-directories for additional context
  • Example: cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared,../types
  • ⚠️ CRITICAL: CONTEXT must explicitly list external files (e.g., @../shared/**/*), AND command must include --include-directories ../shared
  • Benefits: More precise file references (relative to current directory), clearer intent, better context control
• Enforcement Rule: When CONTEXT references external directories, ALWAYS add corresponding --include-directories
• Use when cd alone limits necessary context visibility
• Keep directory count ≤ 5 for optimal performance
• Pattern matching rule: @../dir/**/* in CONTEXT → --include-directories ../dir in command (MANDATORY)
• Prefer cd + --include-directories over multiple cd commands for cross-directory analysis

---

CONTEXT Field Configuration

File Pattern Reference

Default Pattern:

• All files (default): @**/* - Use this as default for comprehensive context

Common Patterns:

• Source files: @src/**/*
• TypeScript: @*.ts @*.tsx (multiple @ for multiple patterns)
• With docs: @CLAUDE.md @**/*CLAUDE.md (multiple @ for multiple patterns)
• Tests: @src/**/*.test.*

Complex Pattern Discovery

For complex file pattern requirements, use semantic discovery tools BEFORE CLI execution:

• rg (ripgrep): Content-based file discovery with regex patterns
• Code Index MCP: Semantic file search based on task requirements
• Workflow: Discover → Extract precise paths → Build CONTEXT field

Example:

# Step 1: Discover files semantically
rg "export.*Component" --files-with-matches --type ts  # Find component files
mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx")  # Find interface files

# Step 2: Build precise CONTEXT from discovery results
CONTEXT: @src/components/Auth.tsx @src/types/auth.d.ts @src/hooks/useAuth.ts

# Step 3: Execute CLI with precise file references
cd src && gemini -p "
PURPOSE: Analyze authentication components
TASK: Review auth component patterns and props interfaces
MODE: analysis
CONTEXT: @components/Auth.tsx @types/auth.d.ts @hooks/useAuth.ts
EXPECTED: Pattern analysis and improvement suggestions
RULES: Focus on type safety and component composition
"

---

RULES Field Configuration

Basic Format

RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]

⚠️ CRITICAL: Command Substitution Rules

When using $(cat ...) for template loading in actual CLI commands:

• Template reference only, never read: When user specifies template name, use $(cat ...) directly in RULES field, do NOT read template content first
• NEVER use escape characters: \$, \", \' will break command substitution
• In prompt context: Path in $(cat ...) needs NO quotes (tilde expands correctly)
• Correct: RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
• WRONG: RULES: \$(cat ...) or RULES: $(cat \"...\") or RULES: $(cat '...')
• Why: Shell executes $(...) in subshell where path is safe without quotes

Examples

• Single template: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) | Focus on security
• Multiple templates: $(cat template1.txt) $(cat template2.txt) | Enterprise standards
• No template: Focus on security patterns, include dependency analysis
• File patterns: @src/**/*.ts @CLAUDE.md - Stay within scope

---

Template System

Base Structure

~/.claude/workflows/cli-templates/

Available Templates

prompts/
├── analysis/
│   ├── pattern.txt      - Code pattern analysis
│   ├── architecture.txt - System architecture review
│   ├── security.txt     - Security assessment
│   └── quality.txt      - Code quality review
├── development/
│   ├── feature.txt      - Feature implementation
│   ├── refactor.txt     - Refactoring tasks
│   └── testing.txt      - Test generation
├── memory/
│   └── claude-module-unified.txt  - Universal module/file documentation template
└── planning/
    └── task-breakdown.txt - Task decomposition

planning-roles/
├── system-architect.md  - System design perspective
├── security-expert.md   - Security architecture
└── feature-planner.md   - Feature specification

tech-stacks/
├── typescript-dev.md    - TypeScript guidelines
├── python-dev.md        - Python conventions
└── react-dev.md         - React architecture

Task-Template Selection Matrix

Task Type	Tool	Use Case	Template
Analysis	Gemini (Qwen fallback)	Code exploration, architecture review, patterns	analysis/pattern.txt
Architecture	Gemini (Qwen fallback)	System design, architectural analysis	analysis/architecture.txt
Documentation	Gemini (Qwen fallback)	Code docs, API specs, guides	analysis/quality.txt
Development	Codex	Feature implementation, bug fixes, testing	development/feature.txt
Planning	Gemini/Qwen	Task breakdown, migration planning	planning/task-breakdown.txt
Security	Codex	Vulnerability assessment, fixes	analysis/security.txt
Refactoring	Multiple	Gemini/Qwen for analysis, Codex for execution	development/refactor.txt
Module Documentation	Gemini (Qwen fallback)	Universal module/file documentation for all levels	memory/claude-module-unified.txt

---

⚙️ Execution Configuration

Dynamic Timeout Allocation

Timeout Ranges:

• Simple tasks (analysis, search): 20-40min (1200000-2400000ms)
• Medium tasks (refactoring, documentation): 40-60min (2400000-3600000ms)
• Complex tasks (implementation, migration): 60-120min (3600000-7200000ms)

Codex Multiplier: Codex commands use 1.5x of allocated time

Application: All bash() wrapped commands including Gemini, Qwen and Codex executions

Auto-detection: Analyze PURPOSE and TASK fields to determine appropriate timeout

Command Examples:

bash(gemini -p "prompt")  # Simple analysis: 20-40min
bash(codex -C directory --full-auto exec "task")  # Complex implementation: 90-180min

---

Permission Framework

Write Operation Protection

⚠️ WRITE PROTECTION: Local codebase write/modify requires EXPLICIT user confirmation

Mode Hierarchy:

• Analysis Mode (default): Read-only, safe for auto-execution
• Write Mode: Requires user explicitly states MODE=write or MODE=auto in prompt
• Exception: User provides clear instructions like "modify", "create", "implement"

Tool-Specific Permissions

Gemini/Qwen Write Access:

• Use --approval-mode yolo ONLY when MODE=write explicitly specified
• Parameter Position: Place AFTER the prompt: gemini -p "..." --approval-mode yolo

Codex Write Access:

• Use -s danger-full-access and --skip-git-repo-check ONLY when MODE=auto explicitly specified
• Parameter Position: Place AFTER the prompt string at command END: codex ... exec "..." --skip-git-repo-check -s danger-full-access

Default Behavior: All tools default to analysis/read-only mode without explicit write permission

---

🔧 Best Practices

General Guidelines

Workflow Principles:

• Start with templates - Use predefined templates for consistency
• Be specific - Clear PURPOSE, TASK, and EXPECTED fields
• Include constraints - File patterns, scope, requirements in RULES
• Discover patterns first - Use rg/MCP for complex file discovery before CLI execution
• Build precise CONTEXT - Convert discovery results to explicit file references
• Document context - Always reference CLAUDE.md for context
• Default to full context - Use @**/* in CONTEXT for comprehensive analysis unless specific files needed
• ⚠️ No escape characters in CLI commands - NEVER use \$, \", \' in actual CLI execution (breaks command substitution and path expansion)

---

Context Optimization Strategy

Directory Navigation: Use cd [directory] && pattern when analyzing specific areas to reduce irrelevant context

When to change directory:

• Specific directory mentioned → Use cd directory && pattern
• Focused analysis needed → Target specific directory with cd
• Multi-directory scope → Use cd + --include-directories for precise control

When to use --include-directories:

• Working in subdirectory but need parent/sibling context
• Cross-directory dependency analysis required
• Multiple related modules need simultaneous access

---

Workflow Integration (REQUIRED)

When planning any coding task, ALWAYS integrate CLI tools:

1. Understanding Phase: Use Gemini for analysis (Qwen as fallback)
2. Architecture Phase: Use Gemini for design and analysis (Qwen as fallback)
3. Implementation Phase: Use Codex for development
4. Quality Phase: Use Codex for testing and validation

---

Planning Checklist

For every development task:

• Purpose defined - Clear goal and intent
• Mode selected - Execution mode and permission level determined
• Context gathered - File references and session memory documented (default @**/*)
• Directory navigation - Determine if cd or cd + --include-directories needed
• Gemini analysis completed for understanding
• Template selected - Appropriate template chosen
• Constraints specified - File patterns, scope, requirements
• Implementation approach - Tool selection and workflow