catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: migrate to Gemini CLI v0.11.0-nightly with native prompt support

Browse Source 
## Major Changes

### Gemini CLI Integration (google-gemini/gemini-cli#11228)
- Migrate from wrapper scripts to native Gemini CLI v0.11.0-nightly
- Remove `-p` flag requirement for prompt strings
- Deprecate `gemini-wrapper` and `qwen-wrapper` scripts
- Update all commands and workflows to use direct CLI syntax

### Command Syntax Updates
- **Before**: `gemini -p "CONTEXT: @**/* prompt"`
- **After**: `gemini "CONTEXT: @**/* prompt"`
- Apply to all 70+ command files and workflow templates
- Maintain backward compatibility for Qwen fallback

### File Pattern Migration
- Replace `@{CLAUDE.md}` with `@CLAUDE.md`
- Replace `@{**/*}` with `@**/*`
- Update all file references to use direct @ notation
- Remove legacy brace syntax across all documentation

### Documentation Improvements
- Reorganize `intelligent-tools-strategy.md` structure
- Add Quick Start section with decision matrix
- Enhance `--include-directories` best practices
- Add comprehensive command templates and examples
- Improve navigation with clearer section hierarchy

### Files Modified (75+ files)
- Commands: All CLI commands updated (cli/, workflow/, task/, memory/)
- Workflows: Core strategy files and templates
- Agents: CLI execution agent and doc generator
- Templates: Planning roles and tech stack guides

## Breaking Changes
- Gemini CLI v0.11.0-nightly or later required
- Old wrapper scripts no longer supported
- Legacy `@{pattern}` syntax deprecated

## Migration Guide
Users should:
1. Update Gemini CLI to v0.11.0-nightly or later
2. Remove `-p` flag from existing commands
3. Update file patterns from `@{pattern}` to `@pattern`

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-21 14:46:16 +08:00
parent 360a2b9edc
commit 83664cb777
26 changed files with 375 additions and 534 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt
View File

@@ -148,10 +148,10 @@ bash(codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-
### Gemini/Qwen Commands (Analysis/Documentation)
```bash
bash(~/.claude/scripts/gemini-wrapper -p "PURPOSE: {purpose} TASK: {task} MODE: analysis CONTEXT: @{{synthesis_spec_path}} EXPECTED: {expected} RULES: {rules}")
bash(gemini "PURPOSE: {purpose} TASK: {task} MODE: analysis CONTEXT: @{synthesis_spec_path} EXPECTED: {expected} RULES: {rules}")
# With write permission
bash(~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "PURPOSE: {purpose} TASK: {task} MODE: write CONTEXT: @{{context}} EXPECTED: {expected} RULES: {rules}")
bash(gemini --approval-mode yolo "PURPOSE: {purpose} TASK: {task} MODE: write CONTEXT: @{context} EXPECTED: {expected} RULES: {rules}")
```
## Field Descriptions
@@ -175,4 +175,4 @@ bash(~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "PURPOSE: {purpose
5. **Step Dependencies**: Use `depends_on: [1, 2]` to specify execution order
6. **Parameter Position**:
- Codex: `--skip-git-repo-check -s danger-full-access` at END
- Gemini/Qwen: `--approval-mode yolo` AFTER wrapper command, BEFORE -p
- Gemini/Qwen: `--approval-mode yolo` BEFORE the prompt

6
.claude/workflows/context-search-strategy.md
View File

@@ -40,8 +40,8 @@ type: search-guideline
### Quick Command Reference
```bash
# Semantic File Discovery (codebase-retrieval)
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [task/feature description]"
bash(~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [task/feature description]")
gemini "CONTEXT: @**/* List all files relevant to: [task/feature description]"
bash(gemini "CONTEXT: @**/* List all files relevant to: [task/feature description]")
# Program Architecture Analysis (MANDATORY FIRST)
~/.claude/scripts/get_modules_by_depth.sh # Discover program architecture
@@ -65,7 +65,7 @@ grep -n -i "pattern" file.txt # Line numbers, case-insensitive
### Workflow Integration Examples
```bash
# Semantic Discovery → Content Search → Analysis (Recommended Pattern)
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [task/feature]" # Get relevant files
gemini "CONTEXT: @**/* List all files relevant to: [task/feature]" # Get relevant files
rg "[pattern]" --type [filetype] # Then search within discovered files
# Program Architecture Analysis (MANDATORY BEFORE PLANNING)

563
.claude/workflows/intelligent-tools-strategy.md
View File

@@ -7,67 +7,77 @@ type: strategic-guideline
# Intelligent Tools Selection Strategy
## 📋 Table of Contents
1. [Core Framework](#-core-framework)
1. [Quick Start](#-quick-start)
2. [Tool Specifications](#-tool-specifications)
3. [Command Templates](#-command-templates)
4. [Tool Selection Guide](#-tool-selection-guide)
5. [Usage Patterns](#-usage-patterns)
6. [Best Practices](#-best-practices)
4. [Execution Configuration](#-execution-configuration)
5. [Best Practices](#-best-practices)
---
## ⚡ Core Framework
## ⚡ Quick Start
### Tool Overview
- **Gemini**: Analysis, understanding, exploration & documentation (primary)
- **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
- **Codex**: Development, implementation & automation
### Decision Principles
### Quick Decision Matrix
| Scenario | Tool | Command Pattern |
|----------|------|-----------------|
| **Exploring/Understanding** | Gemini → Qwen | `cd [dir] && gemini "PURPOSE:... CONTEXT: @**/*"` |
| **Architecture/Analysis** | Gemini → Qwen | `cd [dir] && gemini "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
- **Context optimization** - Based on user intent, determine whether to use `-C [directory]` parameter for focused analysis to reduce irrelevant context import
- **⚠️ Write operation protection** - For local codebase write/modify operations, require EXPLICIT user confirmation unless user provides clear instructions containing MODE=write or MODE=auto
### Quick Decision Rules
1. **Exploring/Understanding?** → Start with Gemini (fallback to Qwen if needed)
2. **Architecture/Analysis?** → Start with Gemini (fallback to Qwen if needed)
3. **Building/Fixing?** → Start with Codex
4. **Not sure?** → Use multiple tools in parallel
5. **Small task?** → Still use tools - they're faster than manual work
---
## 🎯 Tool Specifications
### Gemini
- **Command**: `~/.claude/scripts/gemini-wrapper`
### Gemini & Qwen
#### Overview
- **Commands**: `gemini` (primary) | `qwen` (fallback)
- **Strengths**: Large context window, pattern recognition
- **Best For**: Analysis, documentation generation, code exploration
- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
- **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
- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
### Qwen
- **Command**: `~/.claude/scripts/qwen-wrapper`
- **Strengths**: Large context window, pattern recognition (same as Gemini)
- **Best For**: Analysis, documentation generation, code exploration (fallback option when Gemini unavailable)
- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
- **Default MODE**: `analysis` (read-only)
- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
- **Priority**: Secondary to Gemini - use as fallback for same tasks
**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
#### MODE Options
- `analysis` (default) - Read-only analysis and documentation generation (same as Gemini)
- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
**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
```bash
# Default: Use Gemini
gemini "analysis prompt"
# Fallback: Use Qwen if Gemini unavailable
qwen "analysis prompt"
```
---
### Codex
#### Overview
- **Command**: `codex --full-auto exec`
- **Strengths**: Autonomous development, mathematical reasoning
- **Best For**: Implementation, testing, automation
@@ -76,27 +86,39 @@ type: strategic-guideline
- **⚠️ 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)
- `write` - ⚠️ Test generation and file modification (requires explicit specification)
- **Default**: No default mode, MODE must be explicitly specified
**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
- `codex resume` - Resume previous interactive session (picker by default)
- `codex exec "task" resume --last` - Continue most recent session with new task (maintains context)
- `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**:
```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
```
**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**:
```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
@@ -114,6 +136,7 @@ type: strategic-guideline
## 🎯 Command Templates
### Universal Template Structure
Every command MUST follow this structure:
- [ ] **PURPOSE** - Clear goal and intent
- [ ] **TASK** - Specific execution task
@@ -122,57 +145,41 @@ Every command MUST follow this structure:
- [ ] **EXPECTED** - Clear expected results
- [ ] **RULES** - Template reference and constraints
---
### Standard Command Formats
#### Gemini Commands
#### Gemini & Qwen Commands
```bash
# Gemini Analysis (read-only, default)
cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
# Analysis Mode (read-only, default)
# Use 'gemini' (primary) or 'qwen' (fallback)
cd [directory] && gemini "
PURPOSE: [clear analysis goal]
TASK: [specific analysis task]
MODE: analysis
CONTEXT: [file references and memory context]
CONTEXT: @**/* [default: all files, or specify file patterns]
EXPECTED: [expected output]
RULES: [template reference and constraints]
"
# Gemini Write Mode (requires explicit MODE=write)
# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
cd [directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
# Write Mode (requires explicit MODE=write)
# NOTE: --approval-mode yolo must be placed AFTER the prompt
cd [directory] && gemini "
PURPOSE: [clear goal]
TASK: [specific task]
MODE: write
CONTEXT: [file references and memory context]
CONTEXT: @**/* [default: all files, or specify file patterns]
EXPECTED: [expected output]
RULES: [template reference and constraints]
"
```
" --approval-mode yolo
#### Qwen Commands
```bash
# Qwen Analysis (read-only, default) - Same as Gemini, use as fallback
cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
PURPOSE: [clear analysis goal]
TASK: [specific analysis task]
MODE: analysis
CONTEXT: [file references and memory context]
EXPECTED: [expected output]
RULES: [template reference and constraints]
"
# Qwen Write Mode (requires explicit MODE=write)
# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
cd [directory] && ~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "
PURPOSE: [clear goal]
TASK: [specific task]
MODE: write
CONTEXT: [file references and memory context]
EXPECTED: [expected output]
RULES: [template reference and constraints]
"
# Fallback: Replace 'gemini' with 'qwen' if Gemini unavailable
cd [directory] && qwen "..." # Same syntax as gemini
```
#### Codex Commands
```bash
# Codex Development (requires explicit MODE=auto)
# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END
@@ -180,7 +187,7 @@ codex -C [directory] --full-auto exec "
PURPOSE: [clear development goal]
TASK: [specific development task]
MODE: auto
CONTEXT: [file references and memory context]
CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
EXPECTED: [expected deliverables]
RULES: [template reference and constraints]
" --skip-git-repo-check -s danger-full-access
@@ -191,48 +198,79 @@ codex -C [directory] --full-auto exec "
PURPOSE: [clear goal]
TASK: [specific task]
MODE: write
CONTEXT: [file references and memory context]
CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
EXPECTED: [expected deliverables]
RULES: [template reference and constraints]
" --skip-git-repo-check -s danger-full-access
```
---
### Directory Context Configuration
Tools execute in current working directory:
- **Gemini**: `cd path/to/project && ~/.claude/scripts/gemini-wrapper -p "prompt"`
- **Qwen**: `cd path/to/project && ~/.claude/scripts/qwen-wrapper -p "prompt"`
**Tool Directory Navigation**:
- **Gemini & Qwen**: `cd path/to/project && gemini "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-wrapper and qwen-wrapper, token counting happens in current directory
- **Token analysis**: For Gemini/Qwen, token counting happens in current directory
### RULES Field Format
#### Multi-Directory Support (Gemini & Qwen)
**Purpose**: For large projects requiring fine-grained access across multiple directories
**Use Case**: When `cd` limits global visibility but you need to reference files from other folders
**Parameter**: `--include-directories <dir1,dir2,...>`
- Includes additional directories in the workspace
- Can be specified multiple times or as comma-separated values
- Maximum 5 directories can be added
- Particularly useful when working in a subdirectory but needing context from parent or sibling directories
**Syntax Options**:
```bash
RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].txt") | [constraints]
# Comma-separated format
gemini "prompt" --include-directories /path/to/project1,/path/to/project2
# Multiple flags format
gemini "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 "
PURPOSE: Analyze authentication with shared utilities context
TASK: Review auth implementation and its dependencies
MODE: analysis
CONTEXT: @**/* (includes current dir + shared + types directories)
EXPECTED: Complete analysis with cross-directory dependencies
RULES: Focus on integration patterns
" --include-directories ../shared,../types
```
**⚠️ 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 -p "..." 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
**Best Practices**:
- **Recommended Pattern**: Use `cd` to navigate to primary focus directory, then use `--include-directories` for additional context
- Example: `cd src/auth && gemini "..." --include-directories ../shared,../types`
- Benefits: More precise file references (relative to current directory), clearer intent, better context control
- Use when `cd` alone limits necessary context visibility
- Keep directory count ≤ 5 for optimal performance
- Combine with specific file patterns in CONTEXT for precision
- Prefer `cd + --include-directories` over multiple `cd` commands for cross-directory analysis
**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`
---
### File Pattern Reference
- All files: `@{**/*}`
- Source files: `@{src/**/*}`
- TypeScript: `@{*.ts,*.tsx}`
- With docs: `@{CLAUDE.md,**/*CLAUDE.md}`
- Tests: `@{src/**/*.test.*}`
### 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
**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
@@ -245,14 +283,14 @@ 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}
CONTEXT: @src/components/Auth.tsx @src/types/auth.d.ts @src/hooks/useAuth.ts
# Step 3: Execute CLI with precise file references
cd src && ~/.claude/scripts/gemini-wrapper -p "
cd src && gemini "
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}
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
"
@@ -260,26 +298,38 @@ RULES: Focus on type safety and component composition
---
## 📊 Tool Selection Guide
### RULES Field Configuration
### Selection Matrix
#### Basic Format
```bash
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
```
| 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` |
#### ⚠️ 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/`
#### Base Structure
`~/.claude/workflows/cli-templates/`
#### Available Templates
```
prompts/
├── analysis/
@@ -307,11 +357,103 @@ tech-stacks/
└── 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` |
---
## 🚀 Usage Patterns
## ⚙️ 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
bash(gemini "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 "..." --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)
@@ -319,185 +461,16 @@ 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
### Common Scenarios
#### Code Analysis
```bash
~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Understand codebase architecture
TASK: Analyze project structure and identify patterns
MODE: analysis
CONTEXT: @{src/**/*.ts,CLAUDE.md} Previous analysis of auth system
EXPECTED: Architecture overview and integration points
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on integration points
"
```
#### Documentation Generation
```bash
~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Generate API documentation
TASK: Create comprehensive API reference from code
MODE: write
CONTEXT: @{src/api/**/*}
EXPECTED: API.md with all endpoints documented
RULES: Follow project documentation standards
"
```
#### Architecture Analysis (Qwen as Gemini fallback)
```bash
# Prefer Gemini for architecture analysis
cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Analyze authentication system architecture
TASK: Review JWT-based auth system design
MODE: analysis
CONTEXT: @{src/auth/**/*} Existing patterns and requirements
EXPECTED: Architecture analysis report with recommendations
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on security
"
# Use Qwen only if Gemini unavailable
cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
PURPOSE: Analyze authentication system architecture
TASK: Review JWT-based auth system design
MODE: analysis
CONTEXT: @{src/auth/**/*} Existing patterns and requirements
EXPECTED: Architecture analysis report with recommendations
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on security
"
```
#### Feature Development (Multi-task with Resume)
```bash
# First task - establish session
codex -C path/to/project --full-auto exec "
PURPOSE: Implement user authentication
TASK: Create JWT-based authentication system
MODE: auto
CONTEXT: @{src/auth/**/*} Database schema from session memory
EXPECTED: Complete auth module with tests
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) | Follow security best practices
" --skip-git-repo-check -s danger-full-access
# Continue in same session - Add JWT validation
codex --full-auto exec "
PURPOSE: Enhance authentication security
TASK: Add JWT token validation and refresh logic
MODE: auto
CONTEXT: Previous auth implementation from current session
EXPECTED: JWT validation middleware and token refresh endpoints
RULES: Follow JWT best practices, maintain session context
" resume --last --skip-git-repo-check -s danger-full-access
# Continue in same session - Add tests
codex --full-auto exec "
PURPOSE: Increase test coverage
TASK: Generate comprehensive tests for auth module
MODE: write
CONTEXT: Auth implementation from current session
EXPECTED: Complete test suite with 80%+ coverage
RULES: Use Jest, follow existing patterns
" resume --last --skip-git-repo-check -s danger-full-access
```
#### Interactive Session Resume
```bash
# Resume previous session with picker
codex resume
# Or resume most recent session directly
codex resume --last
```
---
## 🔧 Best Practices
### General Guidelines
- **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
- **⚠️ 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 → Stay in root, use explicit paths or multiple commands
**Example**:
```bash
# Gemini - Focused analysis
cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Understand authentication patterns
TASK: Analyze auth implementation
MODE: analysis
CONTEXT: @{**/*.ts}
EXPECTED: Pattern documentation
RULES: Focus on security best practices
"
# Qwen - Analysis (fallback option, same as Gemini)
cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
PURPOSE: Analyze auth architecture
TASK: Review auth system design and patterns
MODE: analysis
CONTEXT: @{**/*}
EXPECTED: Architecture analysis report
RULES: Focus on modularity and security
"
# Codex - Implementation
codex -C src/auth --full-auto exec "
PURPOSE: Improve auth implementation
TASK: Review and enhance auth code
MODE: auto
CONTEXT: @{**/*.ts}
EXPECTED: Code improvements and fixes
RULES: Maintain backward compatibility
" --skip-git-repo-check -s danger-full-access
```
### 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
- [ ] **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
- [ ] **Quality measures** - Testing and validation plan
- [ ] **Tool configuration** - Review `.gemini/CLAUDE.md` or `.codex/Agent.md` if needed
---
## ⚙️ Execution Configuration
### Core Execution Rules
- **Dynamic Timeout (20-120min)**: Allocate execution time based on task complexity
- 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
- **Apply to All Tools**: All bash() wrapped commands including Gemini, Qwen wrapper and Codex executions
- **Command Examples**: `bash(~/.claude/scripts/gemini-wrapper -p "prompt")`, `bash(codex -C directory --full-auto exec "task")`
- **Auto-detect**: Analyze PURPOSE and TASK fields to determine appropriate timeout
### Permission Framework
- **⚠️ WRITE PROTECTION**: Local codebase write/modify requires EXPLICIT user confirmation
- **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"
- **Gemini/Qwen Write Access**: Use `--approval-mode yolo` ONLY when MODE=write explicitly specified
- **Parameter Position**: Place AFTER the wrapper command: `gemini-wrapper --approval-mode yolo -p "..."`
- **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

8
.claude/workflows/mcp-tool-strategy.md
View File

@@ -86,9 +86,9 @@ mcp__code-index__search_code_advanced(pattern="async.*function", file_pattern="*
mcp__exa__get_code_context_exa(query="TypeScript async patterns", tokensNum="dynamic")
# 3. Analyze with Gemini
cd "src/async" && ~/.claude/scripts/gemini-wrapper -p "
cd "src/async" && gemini "
PURPOSE: Understand async patterns
CONTEXT: Code index results + Exa context + @{src/async/**/*}
CONTEXT: Code index results + Exa context + @src/async/**/*
EXPECTED: Pattern analysis
RULES: Focus on TypeScript best practices
"
@@ -134,7 +134,7 @@ codex -C src/async --full-auto exec "Apply modern async patterns" -s danger-full
mcp__code-index__search_code_advanced(pattern="router|routing", file_pattern="*.ts")
mcp__exa__get_code_context_exa(query="Next.js 14 app router", tokensNum="dynamic")
mcp__exa__web_search_exa(query="Next.js 14 best practices 2024", numResults=3)
cd "src/app" && ~/.claude/scripts/gemini-wrapper -p "Learn Next.js patterns"
cd "src/app" && gemini "Learn Next.js patterns"
```
### Debugging
@@ -153,7 +153,7 @@ mcp__code-index__refresh_index() # 刷新索引
mcp__code-index__find_files(pattern="*auth*") # Find auth-related files
mcp__code-index__search_code_advanced(pattern="function.*auth", file_pattern="*.ts") # Find auth functions
mcp__code-index__get_file_summary(file_path="src/auth/index.ts") # Understand structure
cd "src/auth" && ~/.claude/scripts/gemini-wrapper -p "Analyze auth architecture"
cd "src/auth" && gemini "Analyze auth architecture"
```
### Project Setup Workflow

20
.claude/workflows/workflow-architecture.md
View File

@@ -152,7 +152,7 @@ All task files use this unified 5-field schema with optional artifacts enhanceme
{
"step": "analyze_architecture",
"action": "Review system architecture",
"command": "~/.claude/scripts/gemini-wrapper -p \"analyze patterns: [patterns]\"",
"command": "gemini \"analyze patterns: [patterns]\"",
"output_to": "design"
},
{
@@ -416,7 +416,7 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro
- **Bash commands**: `bash(command)` - Any shell command
- **Tool calls**: `Read(file)`, `Glob(pattern)`, `Grep(pattern)`
- **MCP tools**: `mcp__code-index__find_files()`, `mcp__exa__get_code_context_exa()`
- **CLI wrappers**: `~/.claude/scripts/gemini-wrapper`, `codex --full-auto exec`
- **CLI commands**: `gemini`, `qwen`, `codex --full-auto exec`
**Example**:
```json
@@ -477,10 +477,10 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro
"command": "codex --full-auto exec \"task\" resume --last --skip-git-repo-check -s danger-full-access"
// Gemini (user requested)
"command": "~/.claude/scripts/gemini-wrapper -p \"analyze [context]\""
"command": "gemini \"analyze [context]\""
// Qwen (fallback for Gemini)
"command": "~/.claude/scripts/qwen-wrapper -p \"analyze [context]\""
"command": "qwen \"analyze [context]\""
```
**Example Step**:
@@ -517,14 +517,14 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro
**Gemini CLI**:
```bash
~/.claude/scripts/gemini-wrapper -p "prompt"
~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "prompt" # For write mode
gemini "prompt"
gemini --approval-mode yolo "prompt" # For write mode
```
**Qwen CLI** (Gemini fallback):
```bash
~/.claude/scripts/qwen-wrapper -p "prompt"
~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "prompt" # For write mode
qwen "prompt"
qwen --approval-mode yolo "prompt" # For write mode
```
**Codex CLI**:
@@ -892,13 +892,13 @@ fi
- **Examples**: New features, API endpoints with integration, database schema changes
- **Task Decomposition**: Two-level hierarchy when decomposition is needed
- **Agent Coordination**: Context coordination between related tasks
- **Tool Strategy**: `gemini-wrapper` for pattern analysis, `codex --full-auto` for implementation
- **Tool Strategy**: `gemini` for pattern analysis, `codex --full-auto` for implementation
#### Complex Workflows
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
- **Agent Coordination**: Multi-agent orchestration with deep context analysis
- **Tool Strategy**: `gemini-wrapper` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis
- **Tool Strategy**: `gemini` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis
### Assessment & Upgrades
- **During Creation**: System evaluates requirements and assigns complexity