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

Intelligent Tools Selection Strategy

Table of Contents

1. Quick Reference
2. Tool Specifications
3. Prompt Template
4. CLI Execution
5. Configuration
6. Best Practices

---

Quick Reference

Universal Prompt Template

PURPOSE: [objective + why + success criteria]
TASK: • [step 1] • [step 2] • [step 3]
MODE: [analysis|write|auto]
CONTEXT: @**/* | Memory: [session/tech/module context]
EXPECTED: [format + quality + structure]
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints] | MODE=[permission]

Tool Selection

Task Type	Tool	Fallback
Analysis/Documentation	Gemini	Qwen
Implementation/Testing	Codex	-

CCW Command Syntax

ccw cli exec "<prompt>" --tool <gemini|qwen|codex> --mode <analysis|write|auto>
ccw cli exec "<prompt>" --tool gemini --cd <path> --includeDirs <dirs>
ccw cli exec "<prompt>" --resume [id]  # Resume previous session

CLI Subcommands

Command	Description
ccw cli status	Check CLI tools availability
ccw cli exec "<prompt>"	Execute a CLI tool
ccw cli exec "<prompt>" --resume [id]	Resume a previous session
ccw cli history	Show execution history
ccw cli detail <id>	Show execution detail

Core Principles

• Use tools early and often - Tools are faster and more thorough
• Unified CLI - Always use ccw cli exec for consistent parameter handling
• One template required - ALWAYS reference exactly ONE template in RULES (use universal fallback if no specific match)
• Write protection - Require EXPLICIT --mode write or --mode auto
• No escape characters - NEVER use \$, \", \' in CLI commands

---

Tool Specifications

MODE Options

Mode	Permission	Use For	Specification
analysis	Read-only (default)	Code review, architecture analysis, pattern discovery	Auto for Gemini/Qwen
write	Create/Modify/Delete	Documentation, code creation, file modifications	Requires --mode write
auto	Full operations	Feature implementation, bug fixes, autonomous development	Codex only, requires --mode auto

Gemini & Qwen

Via CCW: ccw cli exec "<prompt>" --tool gemini or --tool qwen

Characteristics:

• Large context window, pattern recognition
• Best for: Analysis, documentation, code exploration, architecture review
• Default MODE: analysis (read-only)
• Priority: Prefer Gemini; use Qwen as fallback

Models (override via --model):

• Gemini: gemini-2.5-pro
• Qwen: coder-model, vision-model

Error Handling: HTTP 429 may show error but still return results - check if results exist

Codex

Via CCW: ccw cli exec "<prompt>" --tool codex --mode auto

Characteristics:

• Autonomous development, mathematical reasoning
• Best for: Implementation, testing, automation
• No default MODE - must explicitly specify --mode write or --mode auto

Models: gpt-5.2

Session Resume

Resume via --resume parameter:

ccw cli exec "Continue analyzing" --resume              # Resume last session
ccw cli exec "Fix issues found" --resume <id>           # Resume specific session

Value	Description
--resume (empty)	Resume most recent session
--resume <id>	Resume specific execution ID

Context Assembly (automatic):

=== PREVIOUS CONVERSATION ===
USER PROMPT: [Previous prompt]
ASSISTANT RESPONSE: [Previous output]
=== CONTINUATION ===
[Your new prompt]

Tool Behavior: Codex uses native codex resume; Gemini/Qwen assembles context as single prompt

---

Prompt Template

Template Structure

Every command MUST include these fields:

Field	Purpose	Example
PURPOSE	Goal, why needed, success criteria	"Analyze auth module for security vulnerabilities"
TASK	Actionable steps (• bullet format)	"• Review patterns • Identify risks • Document findings"
MODE	Permission level	analysis / write / auto
CONTEXT	File patterns + Memory context	`@src/**/*
EXPECTED	Deliverable format, quality criteria	"Security report with risk levels and recommendations"
RULES	Template (REQUIRED) + constraints	`$(cat ~/.claude/.../analysis/02-analyze-code-patterns.txt)

CONTEXT Configuration

Format: CONTEXT: [file patterns] | Memory: [memory context]

File Patterns

Pattern	Scope
@**/*	All files (default)
@src/**/*.ts	TypeScript in src
@../shared/**/*	Sibling directory (requires --includeDirs)
@CLAUDE.md	Specific file

Memory Context

Include when building on previous work:

# Cross-task reference
Memory: Building on auth refactoring (commit abc123), implementing refresh tokens

# Cross-module integration
Memory: Integration with auth module, using shared error patterns from @shared/utils/errors.ts

Memory Sources:

• Related Tasks: Previous refactoring, extensions, conflict resolution
• Tech Stack Patterns: Framework conventions, security guidelines
• Cross-Module References: Integration points, shared utilities, type dependencies

Pattern Discovery Workflow

For complex requirements, discover files BEFORE CLI execution:

# Step 1: Discover files
rg "export.*Component" --files-with-matches --type ts

# Step 2: Build CONTEXT
CONTEXT: @components/Auth.tsx @types/auth.d.ts | Memory: Previous type refactoring

# Step 3: Execute CLI
ccw cli exec "..." --tool gemini --cd src

RULES Configuration

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

⚠️ MANDATORY: Exactly ONE template reference is REQUIRED. Select from Task-Template Matrix or use universal fallback:

• universal/00-universal-rigorous-style.txt - For precision-critical tasks (default fallback)
• universal/00-universal-creative-style.txt - For exploratory tasks

Command Substitution Rules:

• Use $(cat ...) directly - do NOT read template content first
• NEVER use escape characters: \$, \", \'
• Tilde expands correctly in prompt context

Examples:

# Specific template (preferred)
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Focus on auth | analysis=READ-ONLY

# Universal fallback (when no specific template matches)
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/universal/00-universal-rigorous-style.txt) | Focus on security patterns | analysis=READ-ONLY

Template System

Base Path: ~/.claude/workflows/cli-templates/prompts/

Naming Convention:

• 00-* - Universal fallbacks (when no specific match)
• 01-* - Universal, high-frequency
• 02-* - Common specialized
• 03-* - Domain-specific

Universal Templates:

Template	Use For
universal/00-universal-rigorous-style.txt	Precision-critical, systematic methodology
universal/00-universal-creative-style.txt	Exploratory, innovative solutions

Task-Template Matrix:

Task Type	Template
Analysis
Execution Tracing	analysis/01-trace-code-execution.txt
Bug Diagnosis	analysis/01-diagnose-bug-root-cause.txt
Code Patterns	analysis/02-analyze-code-patterns.txt
Document Analysis	analysis/02-analyze-technical-document.txt
Architecture Review	analysis/02-review-architecture.txt
Code Review	analysis/02-review-code-quality.txt
Performance	analysis/03-analyze-performance.txt
Security	analysis/03-assess-security-risks.txt
Planning
Architecture	planning/01-plan-architecture-design.txt
Task Breakdown	planning/02-breakdown-task-steps.txt
Component Design	planning/02-design-component-spec.txt
Migration	planning/03-plan-migration-strategy.txt
Development
Feature	development/02-implement-feature.txt
Refactoring	development/02-refactor-codebase.txt
Tests	development/02-generate-tests.txt
UI Component	development/02-implement-component-ui.txt
Debugging	development/03-debug-runtime-issues.txt

---

CLI Execution

Command Options

Option	Description	Default
--tool <tool>	gemini, qwen, codex	gemini
--mode <mode>	analysis, write, auto	analysis
--model <model>	Model override	auto-select
--cd <path>	Working directory	current
--includeDirs <dirs>	Additional directories (comma-separated)	none
--timeout <ms>	Timeout in milliseconds	300000
--resume [id]	Resume previous session	-
--no-stream	Disable streaming	false

Directory Configuration

Working Directory (--cd)

When using --cd:

• @**/* = Files within working directory tree only
• CANNOT reference parent/sibling via @ alone
• Must use --includeDirs for external directories

Include Directories (--includeDirs)

TWO-STEP requirement for external files:

1. Add --includeDirs parameter
2. Reference in CONTEXT with @ patterns

# Single directory
ccw cli exec "CONTEXT: @**/* @../shared/**/*" --cd src/auth --includeDirs ../shared

# Multiple directories
ccw cli exec "..." --cd src/auth --includeDirs ../shared,../types,../utils

Rule: If CONTEXT contains @../dir/**/*, MUST include --includeDirs ../dir

Benefits: Excludes unrelated directories, reduces token usage

CCW Parameter Mapping

CCW automatically maps to tool-specific syntax:

CCW Parameter	Gemini/Qwen	Codex
--cd <path>	cd <path> &&	-C <path>
--includeDirs <dirs>	--include-directories	--add-dir (per dir)
--mode write	--approval-mode yolo	-s danger-full-access
--mode auto	N/A	-s danger-full-access

Command Examples

# Analysis (default)
ccw cli exec "
PURPOSE: Analyze authentication
TASK: • Review patterns • Identify risks
MODE: analysis
CONTEXT: @**/* @../shared/**/*
EXPECTED: Analysis report
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | analysis=READ-ONLY
" --tool gemini --cd src/auth --includeDirs ../shared

# Write mode
ccw cli exec "
PURPOSE: Generate API docs
TASK: • Create docs • Add examples
MODE: write
CONTEXT: @src/api/**/*
EXPECTED: Complete documentation
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | write=CREATE/MODIFY/DELETE
" --tool gemini --mode write

# Auto mode (Codex)
ccw cli exec "
PURPOSE: Implement auth module
TASK: • Create service • Add validation • Setup JWT
MODE: auto
CONTEXT: @**/* | Memory: Following project security patterns
EXPECTED: Complete module with tests
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | auto=FULL
" --tool codex --mode auto

# Fallback strategy
ccw cli exec "<prompt>" --tool gemini    # Primary
ccw cli exec "<prompt>" --tool qwen      # Fallback

---

Configuration

Timeout Allocation

Minimum: 5 minutes (300000ms)

Complexity	Range	Examples
Simple	5-10min (300000-600000ms)	Analysis, search
Medium	10-20min (600000-1200000ms)	Refactoring, documentation
Complex	20-60min (1200000-3600000ms)	Implementation, migration
Heavy	60-120min (3600000-7200000ms)	Large codebase, multi-file

Codex Multiplier: 3x allocated time (minimum 15min / 900000ms)

ccw cli exec "<prompt>" --tool gemini --timeout 600000   # 10 min
ccw cli exec "<prompt>" --tool codex --timeout 1800000   # 30 min

Permission Framework

Single-Use Authorization: Each execution requires explicit user instruction. Previous authorization does NOT carry over.

Mode Hierarchy:

• analysis (default): Read-only, safe for auto-execution
• write: Requires explicit --mode write
• auto: Requires explicit --mode auto
• Exception: User provides clear instructions like "modify", "create", "implement"

---

Best Practices

Workflow Principles

• Use CCW unified interface for all executions
• Always include template - Use Task-Template Matrix or universal fallback
• Be specific - Clear PURPOSE, TASK, EXPECTED fields
• Include constraints - File patterns, scope in RULES
• Leverage memory context when building on previous work
• Discover patterns first - Use rg/MCP before CLI execution
• Default to full context - Use @**/* unless specific files needed

Workflow Integration

Phase	Command
Understanding	ccw cli exec "<prompt>" --tool gemini
Architecture	ccw cli exec "<prompt>" --tool gemini
Implementation	ccw cli exec "<prompt>" --tool codex --mode auto
Quality	ccw cli exec "<prompt>" --tool codex --mode write

Planning Checklist

• Purpose defined - Clear goal and intent
• Mode selected - --mode analysis|write|auto
• Context gathered - File references + memory (default @**/*)
• Directory navigation - --cd and/or --includeDirs
• Tool selected - --tool gemini|qwen|codex
• Template applied (REQUIRED) - Use specific or universal fallback template
• Constraints specified - Scope, requirements
• Timeout configured - Based on complexity