|
|
|
|
@@ -1,9 +1,3 @@
|
|
|
|
|
---
|
|
|
|
|
name: intelligent-tools-strategy
|
|
|
|
|
description: Strategic decision framework for intelligent tool selection
|
|
|
|
|
type: strategic-guideline
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Intelligent Tools Selection Strategy
|
|
|
|
|
|
|
|
|
|
## 📋 Table of Contents
|
|
|
|
|
@@ -17,140 +11,148 @@ type: strategic-guideline
|
|
|
|
|
|
|
|
|
|
## ⚡ Quick Start
|
|
|
|
|
|
|
|
|
|
### Tool Overview
|
|
|
|
|
- **Gemini**: Analysis, understanding, exploration & documentation (primary)
|
|
|
|
|
- **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
|
|
|
|
|
- **Codex**: Development, implementation & automation
|
|
|
|
|
### Universal Prompt Template
|
|
|
|
|
|
|
|
|
|
### Model Selection (-m parameter)
|
|
|
|
|
All CLI tools (Gemini, Qwen, Codex) share this template structure:
|
|
|
|
|
|
|
|
|
|
**Gemini Models**:
|
|
|
|
|
- `gemini-2.5-pro` - Analysis tasks (default)
|
|
|
|
|
```
|
|
|
|
|
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/analysis/pattern.txt) | [constraints] | MODE=[permission level]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Tool Selection
|
|
|
|
|
|
|
|
|
|
- **Analysis/Documentation** → Gemini (preferred) or Qwen (fallback)
|
|
|
|
|
- **Implementation/Testing** → Codex
|
|
|
|
|
|
|
|
|
|
### Quick Command Syntax
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Gemini/Qwen
|
|
|
|
|
cd [dir] && gemini -p "[prompt]" [-m model] [--approval-mode yolo]
|
|
|
|
|
|
|
|
|
|
# Codex
|
|
|
|
|
codex -C [dir] --full-auto exec "[prompt]" [-m model] [--skip-git-repo-check -s danger-full-access]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Model Selection
|
|
|
|
|
|
|
|
|
|
**Gemini**:
|
|
|
|
|
- `gemini-3-pro-preview-11-2025` - Analysis (default, preferred)
|
|
|
|
|
- `gemini-2.5-pro` - Analysis (alternative)
|
|
|
|
|
- `gemini-2.5-flash` - Documentation updates
|
|
|
|
|
|
|
|
|
|
**Qwen Models**:
|
|
|
|
|
- `coder-model` - Code analysis (default, -m optional)
|
|
|
|
|
- `vision-model` - Image analysis (rare usage)
|
|
|
|
|
**Error Handling**: If `gemini-3-pro-preview-11-2025` returns 404 error, fallback to `gemini-2.5-pro`
|
|
|
|
|
|
|
|
|
|
**Codex Models**:
|
|
|
|
|
**Qwen**:
|
|
|
|
|
- `coder-model` - Code analysis (default)
|
|
|
|
|
- `vision-model` - Image analysis (rare)
|
|
|
|
|
|
|
|
|
|
**Codex**:
|
|
|
|
|
- `gpt-5` - Analysis & execution (default)
|
|
|
|
|
- `gpt5-codex` - Large context tasks
|
|
|
|
|
|
|
|
|
|
**Usage**: `tool -p "prompt" -m model-name` (NOTE: -m placed AFTER prompt)
|
|
|
|
|
**Note**: `-m` parameter 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: @**/*"` |
|
|
|
|
|
| **Multi-directory Analysis** | Gemini → Qwen | `cd [main-dir] && gemini -p "CONTEXT: @**/* @../dep/**/*" --include-directories ../dep` (reduces noise) |
|
|
|
|
|
| **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 |
|
|
|
|
|
| Scenario | Tool | MODE | Template |
|
|
|
|
|
|----------|------|------|----------|
|
|
|
|
|
| Execution Tracing | Gemini → Qwen | analysis | `analysis/01-trace-code-execution.txt` |
|
|
|
|
|
| Bug Diagnosis | Gemini → Qwen | analysis | `analysis/01-diagnose-bug-root-cause.txt` |
|
|
|
|
|
| Architecture Planning | Gemini → Qwen | analysis | `planning/01-plan-architecture-design.txt` |
|
|
|
|
|
| Code Pattern Analysis | Gemini → Qwen | analysis | `analysis/02-analyze-code-patterns.txt` |
|
|
|
|
|
| Architecture Review | Gemini → Qwen | analysis | `analysis/02-review-architecture.txt` |
|
|
|
|
|
| Feature Implementation | Codex | auto | `development/02-implement-feature.txt` |
|
|
|
|
|
| Component Development | Codex | auto | `development/02-implement-component-ui.txt` |
|
|
|
|
|
| Documentation | Gemini/Qwen | write | `memory/02-document-module-structure.txt` |
|
|
|
|
|
| Test Generation | Codex | write | `development/02-generate-tests.txt` |
|
|
|
|
|
|
|
|
|
|
### Core Principles
|
|
|
|
|
- **Use tools early and often** - Tools are faster, more thorough, and reliable than manual approaches
|
|
|
|
|
|
|
|
|
|
- **Use tools early and often** - Tools are faster and more thorough
|
|
|
|
|
- **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
|
|
|
|
|
- **Minimize context noise** - Use `cd` + `--include-directories` to focus on relevant files, exclude unrelated directories
|
|
|
|
|
- **⚠️ Write operation protection** - For local codebase write/modify operations, require EXPLICIT user confirmation unless user provides clear instructions containing MODE=write or MODE=auto
|
|
|
|
|
- **Default to tools** - Use for most coding tasks, no matter how small
|
|
|
|
|
- **Minimize context noise** - Use `cd` + `--include-directories` to focus on relevant files
|
|
|
|
|
- **⚠️ Choose templates by need** - Select templates based on task requirements:
|
|
|
|
|
- `01-*` for general exploratory/diagnostic work
|
|
|
|
|
- `02-*` for common implementation/analysis tasks
|
|
|
|
|
- `03-*` for specialized domains
|
|
|
|
|
- **⚠️ Always specify templates** - Include appropriate template in RULES field via `$(cat ~/.claude/workflows/cli-templates/prompts/.../...txt)`
|
|
|
|
|
- **⚠️ Write protection** - Require EXPLICIT MODE=write or MODE=auto specification
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🎯 Tool Specifications
|
|
|
|
|
|
|
|
|
|
### MODE Options
|
|
|
|
|
|
|
|
|
|
**analysis** (default for Gemini/Qwen)
|
|
|
|
|
- Read-only operations, no file modifications
|
|
|
|
|
- Analysis output returned as text response
|
|
|
|
|
- Use for: code review, architecture analysis, pattern discovery
|
|
|
|
|
- Permission: Default, no special parameters needed
|
|
|
|
|
|
|
|
|
|
**write** (Gemini/Qwen/Codex)
|
|
|
|
|
- File creation/modification/deletion allowed
|
|
|
|
|
- Requires explicit MODE=write specification
|
|
|
|
|
- Use for: documentation generation, code creation, file modifications
|
|
|
|
|
- Permission:
|
|
|
|
|
- Gemini/Qwen: `--approval-mode yolo`
|
|
|
|
|
- Codex: `--skip-git-repo-check -s danger-full-access`
|
|
|
|
|
|
|
|
|
|
**auto** (Codex only)
|
|
|
|
|
- Full autonomous development operations
|
|
|
|
|
- Requires explicit MODE=auto specification
|
|
|
|
|
- Use for: feature implementation, bug fixes, autonomous development
|
|
|
|
|
- Permission: `--skip-git-repo-check -s danger-full-access`
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
**Commands**: `gemini` (primary) | `qwen` (fallback)
|
|
|
|
|
|
|
|
|
|
#### MODE Options
|
|
|
|
|
**Strengths**: Large context window, pattern recognition
|
|
|
|
|
|
|
|
|
|
**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
|
|
|
|
|
**Best For**: Analysis, documentation generation, code exploration, architecture review
|
|
|
|
|
|
|
|
|
|
**write** - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
|
|
|
|
|
- Use for: generating documentation files, creating code files, modifying existing files
|
|
|
|
|
**Default MODE**: `analysis` (read-only)
|
|
|
|
|
|
|
|
|
|
#### Tool Selection
|
|
|
|
|
```bash
|
|
|
|
|
# Default: Use Gemini
|
|
|
|
|
gemini -p "analysis prompt"
|
|
|
|
|
**Priority**: Prefer Gemini; use Qwen as fallback when Gemini unavailable
|
|
|
|
|
|
|
|
|
|
# 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)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
**Error Handling**:
|
|
|
|
|
- **HTTP 429**: May show error but still return results - check if results exist (results present = success, no results = retry/fallback to Qwen)
|
|
|
|
|
- **HTTP 404**: If `gemini-3-pro-preview-11-2025` returns 404, fallback to `gemini-2.5-pro`
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
**Command**: `codex --full-auto exec`
|
|
|
|
|
|
|
|
|
|
#### MODE Options
|
|
|
|
|
**Strengths**: Autonomous development, mathematical reasoning
|
|
|
|
|
|
|
|
|
|
**auto** - ⚠️ Autonomous development with full file operations
|
|
|
|
|
- Requires explicit specification
|
|
|
|
|
- Enables `-s danger-full-access`
|
|
|
|
|
- Use for: feature implementation, bug fixes, autonomous development
|
|
|
|
|
**Best For**: Implementation, testing, automation
|
|
|
|
|
|
|
|
|
|
**write** - ⚠️ Test generation and file modification
|
|
|
|
|
- Requires explicit specification
|
|
|
|
|
- Use for: test generation, focused file modifications
|
|
|
|
|
**Default MODE**: No default, must be explicitly specified
|
|
|
|
|
|
|
|
|
|
#### Session Management
|
|
|
|
|
**Session Management**:
|
|
|
|
|
- `codex resume` - Resume previous session (picker)
|
|
|
|
|
- `codex resume --last` - Resume most recent session
|
|
|
|
|
- `codex -i <image_file>` - Attach image to prompt
|
|
|
|
|
|
|
|
|
|
**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**: MUST use full Standard Prompt Template with `exec` to establish complete context
|
|
|
|
|
- **Subsequent tasks**: Can use brief prompt with `exec "..." resume --last` (inherits context from session)
|
|
|
|
|
|
|
|
|
|
**Multi-task Pattern**: First task uses `exec`, subsequent tasks use `exec "..." resume --last` for context continuity
|
|
|
|
|
**Prompt Requirements**:
|
|
|
|
|
- **Without `resume --last`**: ALWAYS use full Standard Prompt Template
|
|
|
|
|
- **With `resume --last`**: Brief description sufficient (previous template context inherited)
|
|
|
|
|
|
|
|
|
|
**Parameter Position**: `resume --last` must be placed AFTER the prompt string at command END
|
|
|
|
|
|
|
|
|
|
**Example**:
|
|
|
|
|
```bash
|
|
|
|
|
# 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
|
|
|
|
|
**Auto-Resume Rules**:
|
|
|
|
|
- **Use `resume --last`**: Related tasks, extending previous work, multi-step workflow
|
|
|
|
|
- **Don't use**: First task, new independent work, different module
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
@@ -159,270 +161,374 @@ codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s
|
|
|
|
|
### Universal Template Structure
|
|
|
|
|
|
|
|
|
|
Every command MUST follow this structure:
|
|
|
|
|
|
|
|
|
|
- [ ] **PURPOSE** - Clear goal and intent
|
|
|
|
|
- State the high-level objective of this execution
|
|
|
|
|
- Explain why this task is needed
|
|
|
|
|
- Define success criteria
|
|
|
|
|
- Example: "Analyze authentication module to identify security vulnerabilities"
|
|
|
|
|
|
|
|
|
|
- [ ] **TASK** - Specific execution task (use list format: • Task item 1 • Task item 2 • Task item 3)
|
|
|
|
|
- Break down PURPOSE into concrete, actionable steps
|
|
|
|
|
- Use bullet points (•) for multiple sub-tasks
|
|
|
|
|
- Order tasks by execution sequence
|
|
|
|
|
- Example: "• Review auth implementation patterns • Identify potential security risks • Document findings with recommendations"
|
|
|
|
|
|
|
|
|
|
- [ ] **MODE** - Execution mode and permission level
|
|
|
|
|
- `analysis` (default): Read-only operations, no file modifications
|
|
|
|
|
- `write`: File creation/modification/deletion allowed (requires explicit specification)
|
|
|
|
|
- `auto`: Full autonomous development operations (Codex only, requires explicit specification)
|
|
|
|
|
- Example: "MODE: analysis" or "MODE: write"
|
|
|
|
|
|
|
|
|
|
- [ ] **CONTEXT** - File references and memory context from previous sessions
|
|
|
|
|
- **File Patterns**: Use @ syntax for file references (default: `@**/*` for all files)
|
|
|
|
|
- `@**/*` - All files in current directory tree
|
|
|
|
|
- `@src/**/*.ts` - TypeScript files in src directory
|
|
|
|
|
- `@../shared/**/*` - Files from sibling directory (requires `--include-directories`)
|
|
|
|
|
- **Memory Context**: Reference previous session findings and context
|
|
|
|
|
- Related tasks: `Building on previous analysis from [session/commit]`
|
|
|
|
|
- Tech stack: `Using patterns from [tech-stack-name] documentation`
|
|
|
|
|
- Cross-reference: `Related to implementation in [module/file]`
|
|
|
|
|
- **Memory Sources**: Include relevant memory sources
|
|
|
|
|
- Documentation: `CLAUDE.md`, module-specific docs
|
|
|
|
|
- Example: "CONTEXT: @src/auth/**/* @CLAUDE.md | Memory: Building on previous auth refactoring (commit abc123)"
|
|
|
|
|
|
|
|
|
|
- [ ] **EXPECTED** - Clear expected results
|
|
|
|
|
- Specify deliverable format (report, code, documentation, list)
|
|
|
|
|
- Define quality criteria
|
|
|
|
|
- State output structure requirements
|
|
|
|
|
- Example: "Comprehensive security report with categorized findings, risk levels, and actionable recommendations"
|
|
|
|
|
|
|
|
|
|
- [ ] **RULES** - Template reference and constraints (include mode constraints: analysis=READ-ONLY | write=CREATE/MODIFY/DELETE | auto=FULL operations)
|
|
|
|
|
- Reference templates: `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)`
|
|
|
|
|
- Specify constraints and boundaries
|
|
|
|
|
- Include mode-specific constraints:
|
|
|
|
|
- `analysis=READ-ONLY` - No file modifications
|
|
|
|
|
- `write=CREATE/MODIFY/DELETE` - File operations allowed
|
|
|
|
|
- `auto=FULL operations` - Autonomous development
|
|
|
|
|
- Example: "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt) | Focus on authentication flows only | analysis=READ-ONLY"
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
### Standard Prompt Template
|
|
|
|
|
|
|
|
|
|
### Standard Command Formats
|
|
|
|
|
|
|
|
|
|
#### Gemini & Qwen Commands
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 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)
|
|
|
|
|
```
|
|
|
|
|
PURPOSE: [clear goal - state objective, why needed, success criteria]
|
|
|
|
|
TASK:
|
|
|
|
|
• [specific task - actionable step 1]
|
|
|
|
|
• [specific task - actionable step 2]
|
|
|
|
|
• [specific task - actionable step 3]
|
|
|
|
|
MODE: [analysis|write|auto]
|
|
|
|
|
CONTEXT: @**/* | Memory: [previous session findings, related implementations, tech stack patterns, workflow context]
|
|
|
|
|
EXPECTED: [deliverable format, quality criteria, output structure, testing requirements (if applicable)]
|
|
|
|
|
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[0X-template-name].txt) | [additional constraints] | [MODE]=[READ-ONLY|CREATE/MODIFY/DELETE|FULL operations]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Codex Commands
|
|
|
|
|
**Template Selection Guide**:
|
|
|
|
|
- Choose template based on your specific task, not by sequence number
|
|
|
|
|
- `01-*` templates: General-purpose, broad applicability
|
|
|
|
|
- `02-*` templates: Common specialized scenarios
|
|
|
|
|
- `03-*` templates: Domain-specific needs
|
|
|
|
|
|
|
|
|
|
### Tool-Specific Configuration
|
|
|
|
|
|
|
|
|
|
Use the **[Standard Prompt Template](#standard-prompt-template)** for all tools. This section only covers tool-specific command syntax.
|
|
|
|
|
|
|
|
|
|
#### Gemini & Qwen
|
|
|
|
|
|
|
|
|
|
**Command Format**: `cd [directory] && [tool] -p "[Standard Prompt Template]" [options]`
|
|
|
|
|
|
|
|
|
|
**Syntax Elements**:
|
|
|
|
|
- **Directory**: `cd [directory] &&` (navigate to target directory)
|
|
|
|
|
- **Tool**: `gemini` (primary) | `qwen` (fallback)
|
|
|
|
|
- **Prompt**: `-p "[Standard Prompt Template]"` (prompt BEFORE options)
|
|
|
|
|
- **Model**: `-m [model-name]` (optional, placed AFTER prompt)
|
|
|
|
|
- Gemini: `gemini-3-pro-preview-11-2025` (default) | `gemini-2.5-pro` | `gemini-2.5-flash`
|
|
|
|
|
- Qwen: `coder-model` (default) | `vision-model`
|
|
|
|
|
- **Write Permission**: `--approval-mode yolo` (ONLY for MODE=write, placed AFTER prompt)
|
|
|
|
|
|
|
|
|
|
**Command Examples**:
|
|
|
|
|
```bash
|
|
|
|
|
# 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]
|
|
|
|
|
# Analysis Mode (default, read-only)
|
|
|
|
|
cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-3-pro-preview-11-2025
|
|
|
|
|
|
|
|
|
|
# Write Mode (requires MODE=write in template + --approval-mode yolo)
|
|
|
|
|
cd [directory] && gemini -p "[Standard Prompt Template with MODE: write]" -m gemini-2.5-flash --approval-mode yolo
|
|
|
|
|
|
|
|
|
|
# Fallback to Qwen
|
|
|
|
|
cd [directory] && qwen -p "[Standard Prompt Template]" -m coder-model
|
|
|
|
|
|
|
|
|
|
# Multi-directory support
|
|
|
|
|
cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-3-pro-preview-11-2025 --include-directories ../shared,../types
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Codex
|
|
|
|
|
|
|
|
|
|
**Command Format**: `codex -C [directory] --full-auto exec "[Standard Prompt Template]" [options]`
|
|
|
|
|
|
|
|
|
|
**Syntax Elements**:
|
|
|
|
|
- **Directory**: `-C [directory]` (target directory parameter)
|
|
|
|
|
- **Execution Mode**: `--full-auto exec` (required for autonomous execution)
|
|
|
|
|
- **Prompt**: `exec "[Standard Prompt Template]"` (prompt BEFORE options)
|
|
|
|
|
- **Model**: `-m [model-name]` (optional, placed AFTER prompt, BEFORE flags)
|
|
|
|
|
- `gpt-5` (default) | `gpt5-codex` (large context)
|
|
|
|
|
- **Write Permission**: `--skip-git-repo-check -s danger-full-access` (ONLY for MODE=auto or MODE=write, placed at command END)
|
|
|
|
|
- **Session Resume**: `resume --last` (placed AFTER prompt, BEFORE flags)
|
|
|
|
|
|
|
|
|
|
**Command Examples**:
|
|
|
|
|
```bash
|
|
|
|
|
# Auto Mode (requires MODE=auto in template + permission flags)
|
|
|
|
|
codex -C [directory] --full-auto exec "[Standard Prompt Template with MODE: auto]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
|
|
|
|
|
|
|
|
|
# Write Mode (requires MODE=write in template + permission flags)
|
|
|
|
|
codex -C [directory] --full-auto exec "[Standard Prompt Template with MODE: write]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
|
|
|
|
|
|
|
|
|
# Session continuity
|
|
|
|
|
# First task - MUST use full Standard Prompt Template to establish context
|
|
|
|
|
codex -C project --full-auto exec "[Standard Prompt Template with MODE: auto]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
|
|
|
|
|
|
|
|
|
# Subsequent tasks - Can use brief prompt ONLY when using 'resume --last'
|
|
|
|
|
# (inherits full context from previous session, no need to repeat template)
|
|
|
|
|
codex --full-auto exec "Add JWT refresh token validation" resume --last --skip-git-repo-check -s danger-full-access
|
|
|
|
|
|
|
|
|
|
# With image attachment
|
|
|
|
|
codex -C [directory] -i design.png --full-auto exec "[Standard Prompt Template]" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Complete Example (Codex with full template)**:
|
|
|
|
|
```bash
|
|
|
|
|
# First task - establish session with full template
|
|
|
|
|
codex -C project --full-auto exec "
|
|
|
|
|
PURPOSE: Implement authentication module
|
|
|
|
|
TASK: • Create auth service • Add user validation • Setup JWT tokens
|
|
|
|
|
MODE: auto
|
|
|
|
|
CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
|
|
|
|
|
EXPECTED: [expected deliverables]
|
|
|
|
|
RULES: [template reference and constraints]
|
|
|
|
|
CONTEXT: @**/* | Memory: Following security patterns from project standards
|
|
|
|
|
EXPECTED: Complete auth module with tests
|
|
|
|
|
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow existing patterns | auto=FULL operations
|
|
|
|
|
" -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
|
|
|
|
|
# Subsequent tasks - brief description with resume
|
|
|
|
|
codex --full-auto exec "Add JWT refresh token validation" resume --last --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
|
|
|
|
|
- **Gemini & Qwen**: `cd path/to/project && gemini -p "prompt"`
|
|
|
|
|
- **Codex**: `codex -C path/to/project --full-auto exec "task"`
|
|
|
|
|
- **Path types**: Supports both relative (`../project`) and absolute (`/full/path`)
|
|
|
|
|
|
|
|
|
|
#### ⚠️ Critical Directory Scope Rules
|
|
|
|
|
#### Critical Directory Scope Rules
|
|
|
|
|
|
|
|
|
|
**Once `cd` to a directory**:
|
|
|
|
|
- **@ references ONLY apply to current directory and its subdirectories**
|
|
|
|
|
- @ references ONLY apply to current directory and 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**
|
|
|
|
|
- `@src/**/*` = Files within src subdirectory
|
|
|
|
|
- CANNOT reference parent/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
|
|
|
|
|
1. Add `--include-directories` parameter to make external directories ACCESSIBLE
|
|
|
|
|
2. Explicitly reference external files in CONTEXT field with @ patterns
|
|
|
|
|
3. ⚠️ BOTH steps are MANDATORY
|
|
|
|
|
|
|
|
|
|
Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" -m gemini-3-pro-preview-11-2025 --include-directories ../shared`
|
|
|
|
|
|
|
|
|
|
**Rule**: If CONTEXT contains `@../dir/**/*`, command MUST include `--include-directories ../dir`
|
|
|
|
|
|
|
|
|
|
#### Multi-Directory Support (Gemini & Qwen)
|
|
|
|
|
|
|
|
|
|
**Purpose**: Reduce irrelevant file noise by focusing analysis on specific directories while maintaining necessary cross-directory context
|
|
|
|
|
|
|
|
|
|
**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
|
|
|
|
|
- Includes additional directories beyond current `cd` directory
|
|
|
|
|
- Can be specified multiple times or comma-separated
|
|
|
|
|
- Maximum 5 directories
|
|
|
|
|
- REQUIRED when working in subdirectory but needing parent/sibling context
|
|
|
|
|
|
|
|
|
|
**Syntax Options**:
|
|
|
|
|
**Syntax**:
|
|
|
|
|
```bash
|
|
|
|
|
# Comma-separated format
|
|
|
|
|
gemini -p "prompt" --include-directories /path/to/project1,/path/to/project2
|
|
|
|
|
gemini -p "prompt" -m gemini-3-pro-preview-11-2025 --include-directories /path/to/project1,/path/to/project2
|
|
|
|
|
|
|
|
|
|
# Multiple flags format
|
|
|
|
|
gemini -p "prompt" --include-directories /path/to/project1 --include-directories /path/to/project2
|
|
|
|
|
gemini -p "prompt" -m gemini-3-pro-preview-11-2025 --include-directories /path/to/project1 --include-directories /path/to/project2
|
|
|
|
|
|
|
|
|
|
# Combined with cd for focused analysis with extended context (RECOMMENDED)
|
|
|
|
|
# This pattern minimizes irrelevant files by focusing on src/auth while only including necessary dependencies
|
|
|
|
|
# Recommended: cd + --include-directories
|
|
|
|
|
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
|
|
|
|
|
# Result: Only src/auth/**, ../shared/**, ../types/** are analyzed, other project files excluded
|
|
|
|
|
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on integration patterns | analysis=READ-ONLY
|
|
|
|
|
" -m gemini-3-pro-preview-11-2025 --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: **Minimizes irrelevant file interference** (only includes specified directories), 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
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
- Use `cd` to navigate to primary focus directory
|
|
|
|
|
- Use `--include-directories` for additional context
|
|
|
|
|
- ⚠️ CONTEXT must explicitly list external files AND command must include `--include-directories`
|
|
|
|
|
- Benefits: Minimizes irrelevant file interference, more precise file references
|
|
|
|
|
- Pattern matching rule: `@../dir/**/*` in CONTEXT → `--include-directories ../dir` in command (MANDATORY)
|
|
|
|
|
|
|
|
|
|
### CONTEXT Field Configuration
|
|
|
|
|
|
|
|
|
|
CONTEXT field consists of: **File Patterns** + **Memory Context**
|
|
|
|
|
|
|
|
|
|
#### File Pattern Reference
|
|
|
|
|
|
|
|
|
|
**Default Pattern**:
|
|
|
|
|
- **All files (default)**: `@**/*` - Use this as default for comprehensive context
|
|
|
|
|
**Default**: `@**/*` (all files - use 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)
|
|
|
|
|
- TypeScript: `@*.ts @*.tsx`
|
|
|
|
|
- With docs: `@CLAUDE.md @**/*CLAUDE.md`
|
|
|
|
|
- Tests: `@src/**/*.test.*`
|
|
|
|
|
|
|
|
|
|
#### Memory Context Integration
|
|
|
|
|
|
|
|
|
|
**Purpose**: Leverage previous session findings, related implementations, and established patterns to provide continuity
|
|
|
|
|
|
|
|
|
|
**Format**: `CONTEXT: [file patterns] | Memory: [memory context]`
|
|
|
|
|
|
|
|
|
|
**Memory Sources**:
|
|
|
|
|
|
|
|
|
|
1. **Related Tasks** - Cross-task context
|
|
|
|
|
- Previous refactoring, task extensions, conflict resolution
|
|
|
|
|
|
|
|
|
|
2. **Tech Stack Patterns** - Framework and library conventions
|
|
|
|
|
- React hooks patterns, TypeScript utilities, security guidelines
|
|
|
|
|
|
|
|
|
|
3. **Cross-Module References** - Inter-module dependencies
|
|
|
|
|
- Integration points, shared utilities, type dependencies
|
|
|
|
|
|
|
|
|
|
**Memory Context Examples**:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Example 1: Building on related task
|
|
|
|
|
CONTEXT: @src/auth/**/* @CLAUDE.md | Memory: Building on previous auth refactoring (commit abc123), implementing refresh token mechanism following React hooks patterns
|
|
|
|
|
|
|
|
|
|
# Example 2: Cross-module integration
|
|
|
|
|
CONTEXT: @src/payment/**/* @src/shared/types/**/* | Memory: Integration with auth module from previous implementation, using shared error handling patterns from @shared/utils/errors.ts
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Best Practices**:
|
|
|
|
|
- **Always include memory context** when building on previous work
|
|
|
|
|
- **Reference commits/tasks**: Use commit hashes or task IDs for traceability
|
|
|
|
|
- **Document dependencies** with explicit file references
|
|
|
|
|
- **Cross-reference implementations** with file paths
|
|
|
|
|
- **Use consistent format**: `CONTEXT: [file patterns] | Memory: [memory context]`
|
|
|
|
|
|
|
|
|
|
#### 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
|
|
|
|
|
For complex file pattern requirements, use semantic discovery BEFORE CLI execution:
|
|
|
|
|
|
|
|
|
|
**Tools**:
|
|
|
|
|
- `rg (ripgrep)` - Content-based file discovery with regex
|
|
|
|
|
- `mcp__code-index__search_code_advanced` - Semantic file search
|
|
|
|
|
|
|
|
|
|
**Workflow**: Discover → Extract precise paths → Build CONTEXT field
|
|
|
|
|
|
|
|
|
|
**Example**:
|
|
|
|
|
```bash
|
|
|
|
|
# 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
|
|
|
|
|
rg "export.*Component" --files-with-matches --type ts
|
|
|
|
|
mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx")
|
|
|
|
|
|
|
|
|
|
# Step 2: Build precise CONTEXT from discovery results
|
|
|
|
|
CONTEXT: @src/components/Auth.tsx @src/types/auth.d.ts @src/hooks/useAuth.ts
|
|
|
|
|
# Step 2: Build precise CONTEXT with file patterns + memory
|
|
|
|
|
CONTEXT: @src/components/Auth.tsx @src/types/auth.d.ts @src/hooks/useAuth.ts | Memory: Previous refactoring identified type inconsistencies, following React hooks patterns
|
|
|
|
|
|
|
|
|
|
# Step 3: Execute CLI with precise file references
|
|
|
|
|
# cd to src/ reduces scope; specific files further minimize context to only relevant files
|
|
|
|
|
# Step 3: Execute CLI with precise references
|
|
|
|
|
cd src && gemini -p "
|
|
|
|
|
PURPOSE: Analyze authentication components
|
|
|
|
|
TASK: Review auth component patterns and props interfaces
|
|
|
|
|
PURPOSE: Analyze authentication components for type safety improvements
|
|
|
|
|
TASK:
|
|
|
|
|
• Review auth component patterns and props interfaces
|
|
|
|
|
• Identify type inconsistencies in auth components
|
|
|
|
|
• Recommend improvements following React best practices
|
|
|
|
|
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
|
|
|
|
|
"
|
|
|
|
|
# Result: Only 3 specific files analyzed instead of entire src/ tree
|
|
|
|
|
CONTEXT: @components/Auth.tsx @types/auth.d.ts @hooks/useAuth.ts | Memory: Previous refactoring identified type inconsistencies, following React hooks patterns, related implementation in @hooks/useAuth.ts (commit abc123)
|
|
|
|
|
EXPECTED: Comprehensive analysis report with type safety recommendations, code examples, and references to previous findings
|
|
|
|
|
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on type safety and component composition | analysis=READ-ONLY
|
|
|
|
|
" -m gemini-3-pro-preview-11-2025
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### RULES Field Configuration
|
|
|
|
|
|
|
|
|
|
#### Basic Format
|
|
|
|
|
```bash
|
|
|
|
|
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
|
|
|
|
|
```
|
|
|
|
|
**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
|
|
|
|
|
**⚠️ Command Substitution Rules**:
|
|
|
|
|
- **Template reference only, never read**: Use `$(cat ...)` directly, 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
|
|
|
|
|
- **In prompt context**: Path needs NO quotes (tilde expands correctly)
|
|
|
|
|
- **Correct**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)`
|
|
|
|
|
- **WRONG**: `RULES: \$(cat ...)` or `RULES: $(cat \"...\")`
|
|
|
|
|
- **Why**: Shell executes `$(...)` in subshell where path is safe
|
|
|
|
|
|
|
|
|
|
#### 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`
|
|
|
|
|
**Examples**:
|
|
|
|
|
- General template: `$(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Focus on authentication module`
|
|
|
|
|
- Specialized template: `$(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | React hooks only`
|
|
|
|
|
- Multiple: `$(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/`
|
|
|
|
|
**Base**: `~/.claude/workflows/cli-templates/`
|
|
|
|
|
|
|
|
|
|
#### Available Templates
|
|
|
|
|
**Naming Convention**:
|
|
|
|
|
- `01-*` - Universal, high-frequency templates
|
|
|
|
|
- `02-*` - Common specialized templates
|
|
|
|
|
- `03-*` - Domain-specific, less frequent templates
|
|
|
|
|
|
|
|
|
|
**Note**: Number prefix indicates category and frequency, not required usage order. Choose based on task needs.
|
|
|
|
|
|
|
|
|
|
**Available Templates**:
|
|
|
|
|
```
|
|
|
|
|
prompts/
|
|
|
|
|
├── analysis/
|
|
|
|
|
│ ├── pattern.txt - Code pattern analysis
|
|
|
|
|
│ ├── architecture.txt - System architecture review
|
|
|
|
|
│ ├── security.txt - Security assessment
|
|
|
|
|
│ └── quality.txt - Code quality review
|
|
|
|
|
│ ├── 01-trace-code-execution.txt
|
|
|
|
|
│ ├── 01-diagnose-bug-root-cause.txt
|
|
|
|
|
│ ├── 02-analyze-code-patterns.txt
|
|
|
|
|
│ ├── 02-review-architecture.txt
|
|
|
|
|
│ ├── 02-review-code-quality.txt
|
|
|
|
|
│ ├── 03-analyze-performance.txt
|
|
|
|
|
│ ├── 03-assess-security-risks.txt
|
|
|
|
|
│ └── 03-review-quality-standards.txt
|
|
|
|
|
├── development/
|
|
|
|
|
│ ├── feature.txt - Feature implementation
|
|
|
|
|
│ ├── refactor.txt - Refactoring tasks
|
|
|
|
|
│ └── testing.txt - Test generation
|
|
|
|
|
│ ├── 02-implement-feature.txt
|
|
|
|
|
│ ├── 02-refactor-codebase.txt
|
|
|
|
|
│ ├── 02-generate-tests.txt
|
|
|
|
|
│ ├── 02-implement-component-ui.txt
|
|
|
|
|
│ └── 03-debug-runtime-issues.txt
|
|
|
|
|
├── memory/
|
|
|
|
|
│ └── claude-module-unified.txt - Universal module/file documentation template
|
|
|
|
|
│ └── 02-document-module-structure.txt
|
|
|
|
|
└── 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
|
|
|
|
|
├── 01-plan-architecture-design.txt
|
|
|
|
|
├── 02-breakdown-task-steps.txt
|
|
|
|
|
├── 02-design-component-spec.txt
|
|
|
|
|
├── 03-evaluate-concept-feasibility.txt
|
|
|
|
|
└── 03-plan-migration-strategy.txt
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Task-Template Selection Matrix
|
|
|
|
|
**Task-Template 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` |
|
|
|
|
|
| Task Type | Tool | Template |
|
|
|
|
|
|-----------|------|----------|
|
|
|
|
|
| Execution Tracing | Gemini (Qwen fallback) | `analysis/01-trace-code-execution.txt` |
|
|
|
|
|
| Bug Diagnosis | Gemini (Qwen fallback) | `analysis/01-diagnose-bug-root-cause.txt` |
|
|
|
|
|
| Code Pattern Analysis | Gemini (Qwen fallback) | `analysis/02-analyze-code-patterns.txt` |
|
|
|
|
|
| Architecture Review | Gemini (Qwen fallback) | `analysis/02-review-architecture.txt` |
|
|
|
|
|
| Code Review | Gemini (Qwen fallback) | `analysis/02-review-code-quality.txt` |
|
|
|
|
|
| Performance Analysis | Gemini (Qwen fallback) | `analysis/03-analyze-performance.txt` |
|
|
|
|
|
| Security Assessment | Gemini (Qwen fallback) | `analysis/03-assess-security-risks.txt` |
|
|
|
|
|
| Quality Standards | Gemini (Qwen fallback) | `analysis/03-review-quality-standards.txt` |
|
|
|
|
|
| Architecture Planning | Gemini (Qwen fallback) | `planning/01-plan-architecture-design.txt` |
|
|
|
|
|
| Task Breakdown | Gemini (Qwen fallback) | `planning/02-breakdown-task-steps.txt` |
|
|
|
|
|
| Component Design | Gemini (Qwen fallback) | `planning/02-design-component-spec.txt` |
|
|
|
|
|
| Concept Evaluation | Gemini (Qwen fallback) | `planning/03-evaluate-concept-feasibility.txt` |
|
|
|
|
|
| Migration Planning | Gemini (Qwen fallback) | `planning/03-plan-migration-strategy.txt` |
|
|
|
|
|
| Feature Development | Codex | `development/02-implement-feature.txt` |
|
|
|
|
|
| Refactoring | Codex | `development/02-refactor-codebase.txt` |
|
|
|
|
|
| Test Generation | Codex | `development/02-generate-tests.txt` |
|
|
|
|
|
| Component Implementation | Codex | `development/02-implement-component-ui.txt` |
|
|
|
|
|
| Debugging | Codex | `development/03-debug-runtime-issues.txt` |
|
|
|
|
|
| Module Documentation | Gemini (Qwen fallback) | `memory/02-document-module-structure.txt` |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
@@ -431,83 +537,69 @@ tech-stacks/
|
|
|
|
|
### 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)
|
|
|
|
|
- **Simple** (analysis, search): 20-40min (1200000-2400000ms)
|
|
|
|
|
- **Medium** (refactoring, documentation): 40-60min (2400000-3600000ms)
|
|
|
|
|
- **Complex** (implementation, migration): 60-120min (3600000-7200000ms)
|
|
|
|
|
|
|
|
|
|
**Codex Multiplier**: Codex commands use 1.5x of allocated time
|
|
|
|
|
**Codex Multiplier**: 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
|
|
|
|
|
bash(gemini -p "prompt") # Simple analysis: 20-40min
|
|
|
|
|
bash(codex -C directory --full-auto exec "task") # Complex implementation: 90-180min
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
**Auto-detection**: Analyze PURPOSE and TASK fields to determine timeout
|
|
|
|
|
|
|
|
|
|
### Permission Framework
|
|
|
|
|
|
|
|
|
|
#### Write Operation Protection
|
|
|
|
|
|
|
|
|
|
**⚠️ CRITICAL: Single-Use Explicit Authorization**: Each CLI execution (Gemini/Qwen/Codex) requires explicit user command instruction - one command authorizes ONE execution only. Analysis does NOT authorize write operations. Previous authorization does NOT carry over to subsequent actions. Each operation needs NEW explicit user directive.
|
|
|
|
|
**⚠️ Single-Use Explicit Authorization**: Each CLI execution requires explicit user command instruction - one command authorizes ONE execution only. Analysis does NOT authorize write operations. Previous authorization does NOT carry over. Each operation needs NEW explicit user directive.
|
|
|
|
|
|
|
|
|
|
**Mode Hierarchy**:
|
|
|
|
|
- **Analysis Mode (default)**: Read-only, safe for auto-execution
|
|
|
|
|
- **Write Mode**: Requires user explicitly states MODE=write or MODE=auto in prompt
|
|
|
|
|
- **analysis** (default): Read-only, safe for auto-execution
|
|
|
|
|
- **write**: Requires explicit MODE=write specification
|
|
|
|
|
- **auto**: Requires explicit MODE=auto specification
|
|
|
|
|
- **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
|
|
|
|
|
**Tool-Specific Permissions**:
|
|
|
|
|
- **Gemini/Qwen**: Use `--approval-mode yolo` ONLY when MODE=write (placed AFTER prompt)
|
|
|
|
|
- **Codex**: Use `--skip-git-repo-check -s danger-full-access` ONLY when MODE=auto or MODE=write (placed at command END)
|
|
|
|
|
- **Default**: All tools default to analysis/read-only mode
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🔧 Best Practices
|
|
|
|
|
|
|
|
|
|
### General Guidelines
|
|
|
|
|
### Workflow Principles
|
|
|
|
|
|
|
|
|
|
**Workflow Principles**:
|
|
|
|
|
- **Start with templates** - Use predefined templates for consistency
|
|
|
|
|
- **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields
|
|
|
|
|
- **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields with detailed descriptions
|
|
|
|
|
- **Include constraints** - File patterns, scope, requirements in RULES
|
|
|
|
|
- **Leverage memory context** - ALWAYS include Memory field when building on previous work
|
|
|
|
|
- Cross-reference tasks with file paths and commit hashes
|
|
|
|
|
- Document dependencies with explicit file references
|
|
|
|
|
- Reference related implementations and patterns
|
|
|
|
|
- **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)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
- **Build precise CONTEXT** - Convert discovery to explicit file references with memory
|
|
|
|
|
- Format: `CONTEXT: [file patterns] | Memory: [memory context]`
|
|
|
|
|
- File patterns: `@**/*` (default) or specific patterns
|
|
|
|
|
- Memory: Previous sessions, tech stack patterns, cross-references
|
|
|
|
|
- **Document context** - Always reference CLAUDE.md and relevant documentation
|
|
|
|
|
- **Default to full context** - Use `@**/*` unless specific files needed
|
|
|
|
|
- **⚠️ No escape characters** - NEVER use `\$`, `\"`, `\'` in CLI commands
|
|
|
|
|
|
|
|
|
|
### Context Optimization Strategy
|
|
|
|
|
|
|
|
|
|
**Directory Navigation**: Use `cd [directory] &&` pattern when analyzing specific areas to reduce irrelevant context
|
|
|
|
|
**Directory Navigation**: Use `cd [directory] &&` pattern 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
|
|
|
|
|
- Specific directory mentioned → Use `cd directory &&`
|
|
|
|
|
- Focused analysis needed → Target specific directory
|
|
|
|
|
- Multi-directory scope → Use `cd` + `--include-directories`
|
|
|
|
|
|
|
|
|
|
**When to use `--include-directories`**:
|
|
|
|
|
- Working in subdirectory but need parent/sibling context
|
|
|
|
|
- Cross-directory dependency analysis required
|
|
|
|
|
- Multiple related modules need simultaneous access
|
|
|
|
|
- **Key benefit**: Excludes unrelated directories, reducing token usage and improving analysis precision
|
|
|
|
|
- **Key benefit**: Excludes unrelated directories, reduces token usage
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### Workflow Integration (REQUIRED)
|
|
|
|
|
### Workflow Integration
|
|
|
|
|
|
|
|
|
|
When planning any coding task, **ALWAYS** integrate CLI tools:
|
|
|
|
|
|
|
|
|
|
@@ -516,8 +608,6 @@ When planning any coding task, **ALWAYS** integrate CLI tools:
|
|
|
|
|
3. **Implementation Phase**: Use Codex for development
|
|
|
|
|
4. **Quality Phase**: Use Codex for testing and validation
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### Planning Checklist
|
|
|
|
|
|
|
|
|
|
For every development task:
|
|
|
|
|
@@ -526,6 +616,6 @@ For every development task:
|
|
|
|
|
- [ ] **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
|
|
|
|
|
- [ ] **Template applied** - Use Standard Prompt Template (universal for all tools)
|
|
|
|
|
- [ ] **Constraints specified** - File patterns, scope, requirements
|
|
|
|
|
- [ ] **Implementation approach** - Tool selection and workflow
|
|
|
|
|
|