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

## 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

View File

@@ -174,7 +174,7 @@ score = 0
**2. Context Assembly**: **2. Context Assembly**:
```bash ```bash
CONTEXT: @{CLAUDE.md} @{discovered_file1} @{discovered_file2} ... CONTEXT: @CLAUDE.md @{discovered_file1} @{discovered_file2} ...
## Discovered Context ## Discovered Context
- **Project Structure**: {module_summary} - **Project Structure**: {module_summary}

View File

@@ -53,8 +53,7 @@ You are an expert technical documentation specialist. Your responsibility is to
{ {
"step": "analyze_module_structure", "step": "analyze_module_structure",
"action": "Deep analysis of module structure and API", "action": "Deep analysis of module structure and API",
"command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @{**/*} "command": "bash(cd src/auth && gemini \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @**/* System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
"output_to": "module_analysis", "output_to": "module_analysis",
"on_error": "fail" "on_error": "fail"
} }

View File

@@ -67,24 +67,24 @@ The agent handles all phases internally (understanding, discovery, enhancement,
## File Pattern Auto-Detection ## File Pattern Auto-Detection
Keywords trigger specific file patterns: Keywords trigger specific file patterns (each @ references one pattern):
- "auth" → `@{**/*auth*,**/*user*}` - "auth" → `@**/*auth* @**/*user*`
- "component" → `@{src/components/**/*,**/*.component.*}` - "component" → `@src/components/**/* @**/*.component.*`
- "API" → `@{**/api/**/*,**/routes/**/*}` - "API" → `@**/api/**/* @**/routes/**/*`
- "test" → `@{**/*.test.*,**/*.spec.*}` - "test" → `@**/*.test.* @**/*.spec.*`
- "config" → `@{*.config.*,**/config/**/*}` - "config" → `@*.config.* @**/config/**/*`
- Generic → `@{src/**/*}` - Generic → `@src/**/*`
For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references. For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
## Command Template ## Command Template
```bash ```bash
cd . && ~/.claude/scripts/gemini-wrapper -p " cd . && gemini -p "
PURPOSE: [analysis goal from target] PURPOSE: [analysis goal from target]
TASK: [auto-detected analysis type] TASK: [auto-detected analysis type]
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md} [auto-detected file patterns] CONTEXT: @CLAUDE.md [auto-detected file patterns]
EXPECTED: Insights, patterns, recommendations (NO code modification) EXPECTED: Insights, patterns, recommendations (NO code modification)
RULES: [auto-selected template] | Focus on [analysis aspect] RULES: [auto-selected template] | Focus on [analysis aspect]
" "
@@ -112,7 +112,7 @@ RULES: [auto-selected template] | Focus on [analysis aspect]
**Architecture Analysis**: **Architecture Analysis**:
```bash ```bash
/cli:analyze --tool qwen "component architecture" /cli:analyze --tool qwen -p "component architecture"
# Executes: Qwen with component file patterns # Executes: Qwen with component file patterns
# Returns: Architecture review, design patterns, improvement suggestions # Returns: Architecture review, design patterns, improvement suggestions
``` ```

View File

@@ -27,7 +27,6 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - d
- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode) - `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode) - `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode)
- `--enhance` - Enhance inquiry with `/enhance-prompt` first - `--enhance` - Enhance inquiry with `/enhance-prompt` first
- `--all-files` - Include entire codebase in context
- `--save-session` - Save interaction to workflow session - `--save-session` - Save interaction to workflow session
## Execution Flow ## Execution Flow
@@ -36,7 +35,7 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - d
1. Parse tool selection (default: gemini) 1. Parse tool selection (default: gemini)
2. If `--enhance`: Execute `/enhance-prompt` to expand user intent 2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files` 3. Assemble context: `@CLAUDE.md` + user-specified files or `@**/*` for entire codebase
4. Execute CLI tool with assembled context (read-only, analysis mode) 4. Execute CLI tool with assembled context (read-only, analysis mode)
5. Return explanations and insights (NO code changes) 5. Return explanations and insights (NO code changes)
6. Optionally save to workflow session 6. Optionally save to workflow session
@@ -54,7 +53,6 @@ Task(
Task: ${inquiry} Task: ${inquiry}
Mode: analyze (Q&A) Mode: analyze (Q&A)
Tool Preference: ${tool_flag || 'auto-select'} Tool Preference: ${tool_flag || 'auto-select'}
${all_files_flag ? 'Scope: all-files' : ''}
Agent will autonomously: Agent will autonomously:
- Discover files relevant to the question - Discover files relevant to the question
@@ -69,20 +67,20 @@ The agent handles all phases internally.
## Context Assembly ## Context Assembly
**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines) **Always included**: `@CLAUDE.md @**/*CLAUDE.md` (project guidelines)
**Optional**: **Optional**:
- User-explicit files from inquiry keywords - User-explicit files from inquiry keywords
- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter) - Use `@**/*` in CONTEXT for entire codebase
For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field. For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
## Command Template ## Command Template
```bash ```bash
cd . && ~/.claude/scripts/gemini-wrapper -p " cd . && gemini -p "
INQUIRY: [user question] INQUIRY: [user question]
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files] CONTEXT: @CLAUDE.md,**/*CLAUDE.md [inferred files or @**/* for all files]
MODE: analysis MODE: analysis
RESPONSE: Direct answer, explanation, insights (NO code modification) RESPONSE: Direct answer, explanation, insights (NO code modification)
" "
@@ -110,7 +108,7 @@ RESPONSE: Direct answer, explanation, insights (NO code modification)
**Architecture Question**: **Architecture Question**:
```bash ```bash
/cli:chat --tool qwen "how does React component optimization work here" /cli:chat --tool qwen -p "how does React component optimization work here"
# Executes: Qwen architecture analysis # Executes: Qwen architecture analysis
# Returns: Component structure explanation, optimization patterns used # Returns: Component structure explanation, optimization patterns used
``` ```
@@ -130,13 +128,6 @@ RESPONSE: Direct answer, explanation, insights (NO code modification)
# Returns: Detailed explanation of login flow and potential issues # Returns: Detailed explanation of login flow and potential issues
``` ```
**Broad Context**:
```bash
/cli:chat --all-files "find all API endpoints"
# Executes: Analysis across entire codebase
# Returns: List and explanation of API endpoints (NO code generation)
```
## Output Routing ## Output Routing
**Output Destination Logic**: **Output Destination Logic**:

View File

@@ -130,7 +130,7 @@ git status --short
codex -C [dir] --full-auto exec " codex -C [dir] --full-auto exec "
PURPOSE: [group goal] PURPOSE: [group goal]
TASK: [subtask description - first in group] TASK: [subtask description - first in group]
CONTEXT: @{relevant_files} @{CLAUDE.md} CONTEXT: @{relevant_files} @CLAUDE.md
EXPECTED: [specific deliverables] EXPECTED: [specific deliverables]
RULES: [constraints] RULES: [constraints]
Group [X]: [group name] - Subtask 1 of N in this group Group [X]: [group name] - Subtask 1 of N in this group
@@ -164,7 +164,7 @@ git add -A
codex -C [dir] --full-auto exec " codex -C [dir] --full-auto exec "
PURPOSE: [new group goal] PURPOSE: [new group goal]
TASK: [subtask description - first in new group] TASK: [subtask description - first in new group]
CONTEXT: @{different_files} @{CLAUDE.md} CONTEXT: @{different_files} @CLAUDE.md
EXPECTED: [specific deliverables] EXPECTED: [specific deliverables]
RULES: [constraints] RULES: [constraints]
Group [Y]: [new group name] - Subtask 1 of N in this group Group [Y]: [new group name] - Subtask 1 of N in this group

View File

@@ -69,11 +69,11 @@ Gemini analyzes the topic and proposes preliminary plan.
```bash ```bash
# Round 1: CONTEXT_INPUT is the initial topic # Round 1: CONTEXT_INPUT is the initial topic
# Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round # Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round
~/.claude/scripts/gemini-wrapper -p " gemini -p "
PURPOSE: Analyze and propose a plan for '[topic]' PURPOSE: Analyze and propose a plan for '[topic]'
TASK: Provide initial analysis, identify key modules, and draft implementation plan TASK: Provide initial analysis, identify key modules, and draft implementation plan
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md} [auto-detected files] CONTEXT: @CLAUDE.md [auto-detected files]
INPUT: [CONTEXT_INPUT] INPUT: [CONTEXT_INPUT]
EXPECTED: Structured analysis and draft plan for discussion EXPECTED: Structured analysis and draft plan for discussion
RULES: Focus on technical depth and practical considerations RULES: Focus on technical depth and practical considerations
@@ -90,7 +90,7 @@ codex --full-auto exec "
PURPOSE: Critically review technical plan PURPOSE: Critically review technical plan
TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md} [relevant files] CONTEXT: @CLAUDE.md [relevant files]
INPUT_PLAN: [Output from Gemini's analysis] INPUT_PLAN: [Output from Gemini's analysis]
EXPECTED: Critical review with alternative ideas and risk analysis EXPECTED: Critical review with alternative ideas and risk analysis
RULES: Focus on architectural soundness and implementation feasibility RULES: Focus on architectural soundness and implementation feasibility

View File

@@ -45,11 +45,11 @@ Auto-approves: file pattern inference, execution, **file modifications**, summar
### Context Inference ### Context Inference
Auto-selects files based on keywords and technology: Auto-selects files based on keywords and technology (each @ references one pattern):
- "auth" → `@{**/*auth*,**/*user*}` - "auth" → `@**/*auth* @**/*user*`
- "React" → `@{src/**/*.{jsx,tsx}}` - "React" → `@src/**/*.jsx @src/**/*.tsx`
- "api" → `@{**/api/**/*,**/routes/**/*}` - "api" → `@**/api/**/* @**/routes/**/*`
- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}` - Always includes: `@CLAUDE.md @**/*CLAUDE.md`
For precise file targeting, use `rg` or MCP tools to discover files first. For precise file targeting, use `rg` or MCP tools to discover files first.
@@ -111,11 +111,11 @@ Use `resume --last` when current task extends/relates to previous execution. See
### Standard Mode (Default) ### Standard Mode (Default)
```bash ```bash
# Gemini/Qwen: MODE=write with --approval-mode yolo # Gemini/Qwen: MODE=write with --approval-mode yolo
cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p " cd . && gemini --approval-mode yolo "
PURPOSE: [implementation goal] PURPOSE: [implementation goal]
TASK: [specific implementation] TASK: [specific implementation]
MODE: write MODE: write
CONTEXT: @{CLAUDE.md} [auto-detected files] CONTEXT: @CLAUDE.md [auto-detected files]
EXPECTED: Working implementation with code changes EXPECTED: Working implementation with code changes
RULES: [constraints] | Auto-approve all changes RULES: [constraints] | Auto-approve all changes
" "

View File

@@ -79,11 +79,11 @@ The agent handles all phases internally.
## Command Template ## Command Template
```bash ```bash
cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p " cd [directory] && gemini -p "
PURPOSE: [bug analysis goal] PURPOSE: [bug analysis goal]
TASK: Systematic bug analysis and fix recommendations TASK: Systematic bug analysis and fix recommendations
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description] RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
" "
@@ -111,11 +111,11 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
**Standard Template Example**: **Standard Template Example**:
```bash ```bash
cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " cd . && gemini -p "
PURPOSE: Debug authentication null pointer error PURPOSE: Debug authentication null pointer error
TASK: Identify root cause and provide fix recommendations TASK: Identify root cause and provide fix recommendations
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
" "
@@ -123,11 +123,11 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login
**Directory-Specific**: **Directory-Specific**:
```bash ```bash
cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p " cd src/auth && gemini -p "
PURPOSE: Fix token validation failure PURPOSE: Fix token validation failure
TASK: Analyze token validation bug in auth module TASK: Analyze token validation bug in auth module
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Validation logic analysis, fix recommendation with minimal changes EXPECTED: Validation logic analysis, fix recommendation with minimal changes
RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
" "
@@ -161,4 +161,4 @@ mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*
- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory) - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
- Scratchpad directory details: see workflow-architecture.md - Scratchpad directory details: see workflow-architecture.md
- Template path: `~/.claude/prompt-templates/bug-fix.md` - Template path: `~/.claude/prompt-templates/bug-fix.md`
- Always uses `--all-files` for comprehensive codebase context - Uses `@**/*` for in CONTEXT field for comprehensive codebase context

View File

@@ -82,11 +82,11 @@ The agent handles all phases internally.
## Command Template ## Command Template
```bash ```bash
cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p " cd [directory] && gemini -p "
PURPOSE: [analysis goal] PURPOSE: [analysis goal]
TASK: Systematic code analysis and execution path tracing TASK: Systematic code analysis and execution path tracing
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
EXPECTED: Execution trace, call flow diagram, debugging insights EXPECTED: Execution trace, call flow diagram, debugging insights
RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect] RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
" "
@@ -114,11 +114,11 @@ RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
**Standard Template Example**: **Standard Template Example**:
```bash ```bash
cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " cd . && gemini -p "
PURPOSE: Trace authentication execution flow PURPOSE: Trace authentication execution flow
TASK: Analyze complete auth flow from request to response TASK: Analyze complete auth flow from request to response
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Step-by-step execution trace with call diagram, variable states EXPECTED: Step-by-step execution trace with call diagram, variable states
RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
" "
@@ -126,11 +126,11 @@ RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flo
**Directory-Specific Analysis**: **Directory-Specific Analysis**:
```bash ```bash
cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p " cd src/auth && gemini -p "
PURPOSE: Understand JWT token validation logic PURPOSE: Understand JWT token validation logic
TASK: Trace JWT validation from middleware to service layer TASK: Trace JWT validation from middleware to service layer
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Validation flow diagram, token lifecycle analysis EXPECTED: Validation flow diagram, token lifecycle analysis
RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
" "
@@ -167,4 +167,4 @@ mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern
- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory) - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
- Scratchpad directory details: see workflow-architecture.md - Scratchpad directory details: see workflow-architecture.md
- Template path: `~/.claude/prompt-templates/code-analysis.md` - Template path: `~/.claude/prompt-templates/code-analysis.md`
- Always uses `--all-files` for comprehensive code context - Uses `@**/*` for in CONTEXT field for comprehensive code context

View File

@@ -80,11 +80,11 @@ The agent handles all phases internally.
## Command Template ## Command Template
```bash ```bash
cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p " cd [directory] && gemini -p "
PURPOSE: [planning goal from topic] PURPOSE: [planning goal from topic]
TASK: Comprehensive planning and architecture analysis TASK: Comprehensive planning and architecture analysis
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
EXPECTED: Strategic insights, implementation recommendations, key decisions EXPECTED: Strategic insights, implementation recommendations, key decisions
RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area] RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
" "
@@ -112,11 +112,11 @@ RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
**Standard Template Example**: **Standard Template Example**:
```bash ```bash
cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " cd . && gemini -p "
PURPOSE: Design user dashboard architecture PURPOSE: Design user dashboard architecture
TASK: Plan dashboard component structure and data flow TASK: Plan dashboard component structure and data flow
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Architecture recommendations, component design, data flow diagram EXPECTED: Architecture recommendations, component design, data flow diagram
RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
" "
@@ -124,11 +124,11 @@ RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
**Directory-Specific Planning**: **Directory-Specific Planning**:
```bash ```bash
cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p " cd src/api && gemini -p "
PURPOSE: Plan API refactoring strategy PURPOSE: Plan API refactoring strategy
TASK: Analyze current API structure and recommend improvements TASK: Analyze current API structure and recommend improvements
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Refactoring roadmap, breaking change analysis, migration plan EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
" "
@@ -165,4 +165,4 @@ rg "architecture|design" --files-with-matches
- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory) - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
- Scratchpad directory details: see workflow-architecture.md - Scratchpad directory details: see workflow-architecture.md
- Template path: `~/.claude/prompt-templates/plan.md` - Template path: `~/.claude/prompt-templates/plan.md`
- Always uses `--all-files` for comprehensive project context - Uses `@**/*` for in CONTEXT field for comprehensive project context

View File

@@ -394,7 +394,7 @@ bash(
}, },
{ {
"step": "analyze_module_tree", "step": "analyze_module_tree",
"command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")", "command": "bash(cd src/modules && gemini \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @**/* [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")",
"output_to": "tree_outline", "output_to": "tree_outline",
"note": "CLI for analysis only" "note": "CLI for analysis only"
} }
@@ -490,7 +490,7 @@ bash(
"CLI writes documentation to .workflow/docs/src/modules/", "CLI writes documentation to .workflow/docs/src/modules/",
"Maintains directory structure mirroring" "Maintains directory structure mirroring"
], ],
"command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @{**/*} [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")", "command": "bash(cd src/modules && gemini --approval-mode yolo \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @**/* [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")",
"depends_on": [1], "depends_on": [1],
"output": "generated_docs" "output": "generated_docs"
} }
@@ -533,7 +533,7 @@ bash(
}, },
{ {
"step": "analyze_project", "step": "analyze_project",
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")", "command": "bash(gemini \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
"output_to": "project_outline" "output_to": "project_outline"
} }
], ],
@@ -583,7 +583,7 @@ bash(
}, },
{ {
"step": "analyze_architecture_and_examples", "step": "analyze_architecture_and_examples",
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze system architecture and generate examples\\nTASK: Synthesize architectural overview and usage patterns\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline + Examples outline\")", "command": "bash(gemini \"PURPOSE: Analyze system architecture and generate examples\\nTASK: Synthesize architectural overview and usage patterns\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline + Examples outline\")",
"output_to": "arch_examples_outline" "output_to": "arch_examples_outline"
} }
], ],
@@ -645,7 +645,7 @@ bash(
}, },
{ {
"step": "analyze_api", "step": "analyze_api",
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @{src/api/**/*} [endpoint_discovery]\\nEXPECTED: API outline\")", "command": "bash(gemini \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\")",
"output_to": "api_outline" "output_to": "api_outline"
} }
], ],

View File

@@ -5,7 +5,7 @@ argument-hint: "[--tool gemini|qwen] \"task context description\""
allowed-tools: Task(*), Bash(*) allowed-tools: Task(*), Bash(*)
examples: examples:
- /memory:load "在当前前端基础上开发用户认证功能" - /memory:load "在当前前端基础上开发用户认证功能"
- /memory:load --tool qwen "重构支付模块API" - /memory:load --tool qwen -p "重构支付模块API"
--- ---
# Memory Load Command (/memory:load) # Memory Load Command (/memory:load)
@@ -140,7 +140,7 @@ cd . && ~/.claude/scripts/${tool}-wrapper -p "
PURPOSE: Extract project core context for task: ${task_description} PURPOSE: Extract project core context for task: ${task_description}
TASK: Analyze project architecture, tech stack, key patterns, relevant files TASK: Analyze project architecture, tech stack, key patterns, relevant files
MODE: analysis MODE: analysis
CONTEXT: @{CLAUDE.md,README.md,${discovered_files}} CONTEXT: @CLAUDE.md,README.md @${discovered_files}
EXPECTED: Structured project summary and integration point analysis EXPECTED: Structured project summary and integration point analysis
RULES: RULES:
- Focus on task-relevant core information - Focus on task-relevant core information
@@ -212,7 +212,7 @@ Before returning:
### Example 2: Using Qwen Tool ### Example 2: Using Qwen Tool
```bash ```bash
/memory:load --tool qwen "重构支付模块API" /memory:load --tool qwen -p "重构支付模块API"
``` ```
Agent uses Qwen CLI for analysis, returns same structured package. Agent uses Qwen CLI for analysis, returns same structured package.

View File

@@ -99,10 +99,10 @@ After bash validation, the model takes control to:
``` ```
- Use Gemini for security analysis: - Use Gemini for security analysis:
```bash ```bash
cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p " cd .workflow/${sessionId} && gemini -p "
PURPOSE: Security audit of completed implementation PURPOSE: Security audit of completed implementation
TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md} CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED: Security findings report with severity levels EXPECTED: Security findings report with severity levels
RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks
" --approval-mode yolo " --approval-mode yolo
@@ -111,10 +111,10 @@ After bash validation, the model takes control to:
**Architecture Review** (`--type=architecture`): **Architecture Review** (`--type=architecture`):
- Use Qwen for architecture analysis: - Use Qwen for architecture analysis:
```bash ```bash
cd .workflow/${sessionId} && ~/.claude/scripts/qwen-wrapper -p " cd .workflow/${sessionId} && qwen -p "
PURPOSE: Architecture compliance review PURPOSE: Architecture compliance review
TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md} CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED: Architecture assessment with recommendations EXPECTED: Architecture assessment with recommendations
RULES: Check for patterns, separation of concerns, modularity, scalability RULES: Check for patterns, separation of concerns, modularity, scalability
" --approval-mode yolo " --approval-mode yolo
@@ -123,10 +123,10 @@ After bash validation, the model takes control to:
**Quality Review** (`--type=quality`): **Quality Review** (`--type=quality`):
- Use Gemini for code quality: - Use Gemini for code quality:
```bash ```bash
cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p " cd .workflow/${sessionId} && gemini -p "
PURPOSE: Code quality and best practices review PURPOSE: Code quality and best practices review
TASK: Assess code readability, maintainability, adherence to best practices TASK: Assess code readability, maintainability, adherence to best practices
CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md} CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED: Quality assessment with improvement suggestions EXPECTED: Quality assessment with improvement suggestions
RULES: Check for code smells, duplication, complexity, naming conventions RULES: Check for code smells, duplication, complexity, naming conventions
" --approval-mode yolo " --approval-mode yolo
@@ -143,10 +143,10 @@ After bash validation, the model takes control to:
' {} \; ' {} \;
# Check implementation summaries against requirements # Check implementation summaries against requirements
cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p " cd .workflow/${sessionId} && gemini -p "
PURPOSE: Verify all requirements and acceptance criteria are met PURPOSE: Verify all requirements and acceptance criteria are met
TASK: Cross-check implementation summaries against original requirements TASK: Cross-check implementation summaries against original requirements
CONTEXT: @{.task/IMPL-*.json,.summaries/IMPL-*.md,../..,../../CLAUDE.md} CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED: EXPECTED:
- Requirements coverage matrix - Requirements coverage matrix
- Acceptance criteria verification - Acceptance criteria verification

View File

@@ -3,7 +3,7 @@ name: tdd-verify
description: Verify TDD workflow compliance and generate quality report description: Verify TDD workflow compliance and generate quality report
argument-hint: "[optional: WFS-session-id]" argument-hint: "[optional: WFS-session-id]"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*) allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
--- ---
# TDD Verification Command (/workflow:tdd-verify) # TDD Verification Command (/workflow:tdd-verify)
@@ -94,7 +94,7 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
**Gemini analysis for comprehensive TDD compliance report** **Gemini analysis for comprehensive TDD compliance report**
```bash ```bash
cd project-root && ~/.claude/scripts/gemini-wrapper -p " cd project-root && gemini -p "
PURPOSE: Generate TDD compliance report PURPOSE: Generate TDD compliance report
TASK: Analyze TDD workflow execution and generate quality report TASK: Analyze TDD workflow execution and generate quality report
CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md} CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}

View File

@@ -226,11 +226,11 @@ Iteration N (managed by test-cycle-execute orchestrator):
#### CLI Analysis Command (executed by orchestrator) #### CLI Analysis Command (executed by orchestrator)
```bash ```bash
cd {project_root} && ~/.claude/scripts/gemini-wrapper -p " cd {project_root} && gemini -p "
PURPOSE: Analyze test failures and generate fix strategy PURPOSE: Analyze test failures and generate fix strategy
TASK: Review test failures and identify root causes TASK: Review test failures and identify root causes
MODE: analysis MODE: analysis
CONTEXT: @{test files, implementation files} CONTEXT: @test files @ implementation files
[Test failure context and requirements...] [Test failure context and requirements...]

View File

@@ -2,7 +2,7 @@
name: task-generate-tdd name: task-generate-tdd
description: Generate TDD task chains with Red-Green-Refactor dependencies description: Generate TDD task chains with Red-Green-Refactor dependencies
argument-hint: "--session WFS-session-id [--agent]" argument-hint: "--session WFS-session-id [--agent]"
allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*) allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
--- ---
# TDD Task Generation Command # TDD Task Generation Command

View File

@@ -256,7 +256,7 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
"action": "Analyze existing code patterns and identify modification targets", "action": "Analyze existing code patterns and identify modification targets",
"commands": [ "commands": [
"bash(cd \"[focus_paths]\")", "bash(cd \"[focus_paths]\")",
"bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")" "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
], ],
"output_to": "task_context_with_targets", "output_to": "task_context_with_targets",
"on_error": "fail" "on_error": "fail"

View File

@@ -48,7 +48,7 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
**Tool Configuration**: **Tool Configuration**:
```bash ```bash
cd .workflow/{test_session_id}/.process && ~/.claude/scripts/gemini-wrapper -p " cd .workflow/{test_session_id}/.process && gemini -p "
PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
TASK: Study implementation context, existing tests, and generate test requirements for missing coverage TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
MODE: analysis MODE: analysis

View File

@@ -198,7 +198,7 @@ Generate **TWO task JSON files**:
"Codex generates comprehensive test suite", "Codex generates comprehensive test suite",
"Codex validates test syntax and executability" "Codex validates test syntax and executability"
], ],
"command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @{.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md,.workflow/WFS-test-[session]/.process/test-context-package.json} EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)", "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
"depends_on": [], "depends_on": [],
"output": "test_generation" "output": "test_generation"
}], }],
@@ -323,7 +323,7 @@ Generate **TWO task JSON files**:
"cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest", "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
"tools": { "tools": {
"test_execution": "bash(test_command)", "test_execution": "bash(test_command)",
"diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)", "diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
"fix_application": "manual (default) or codex exec resume --last (if explicitly needed)", "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
"verification": "bash(test_command) + regression_check" "verification": "bash(test_command) + regression_check"
}, },
@@ -354,11 +354,11 @@ Generate **TWO task JSON files**:
" * Source files from focus_paths", " * Source files from focus_paths",
" * Implementation summaries from source session", " * Implementation summaries from source session",
" - Execute Gemini analysis with bug-fix template:", " - Execute Gemini analysis with bug-fix template:",
" bash(cd .workflow/WFS-test-[session]/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"", " bash(cd .workflow/WFS-test-[session]/.process && gemini \"",
" PURPOSE: Diagnose test failure iteration [N] and propose minimal fix", " PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
" TASK: Systematic bug analysis and fix recommendations for test failure", " TASK: Systematic bug analysis and fix recommendations for test failure",
" MODE: analysis", " MODE: analysis",
" CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}", " CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
" Test output: [test_failures]", " Test output: [test_failures]",
" Source files: [focus_paths]", " Source files: [focus_paths]",
" Implementation: [implementation_context]", " Implementation: [implementation_context]",

View File

@@ -88,8 +88,7 @@ update_module_claude() {
# Use unified template for all modules # Use unified template for all modules
local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt" local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt"
local analysis_strategy="--all-files"
# Prepare logging info # Prepare logging info
local module_name=$(basename "$module_path") local module_name=$(basename "$module_path")
@@ -131,8 +130,10 @@ update_module_claude() {
$template_content $template_content
$update_context" $update_context
CONTEXT: @**/*"
# Execute update # Execute update
local start_time=$(date +%s) local start_time=$(date +%s)
echo " 🔄 Starting update..." echo " 🔄 Starting update..."
@@ -146,10 +147,11 @@ update_module_claude() {
- Path: $module_path - Path: $module_path
- Tool: $tool" - Tool: $tool"
# Execute with selected tool (always use --all-files) # Execute with selected tool
# NOTE: Prompt is passed via -p flag for gemini/qwen, first parameter for codex
case "$tool" in case "$tool" in
qwen) qwen)
qwen --all-files --yolo -p "$final_prompt" 2>&1 qwen -p "$final_prompt" --yolo 2>&1
tool_result=$? tool_result=$?
;; ;;
codex) codex)
@@ -157,7 +159,7 @@ update_module_claude() {
tool_result=$? tool_result=$?
;; ;;
gemini|*) gemini|*)
gemini --all-files --yolo -p "$final_prompt" 2>&1 gemini -p "$final_prompt" --yolo 2>&1
tool_result=$? tool_result=$?
;; ;;
esac esac

View File

@@ -1,124 +0,0 @@
---
name: Prompt Enhancer
description: Transform vague prompts into actionable specs using intelligent analysis and session memory. Use when user input contains -e or --enhance flag.
allowed-tools: (none)
---
# Prompt Enhancer
**Transform**: Vague intent → Structured specification (Memory-based, Direct Output)
**Languages**: English + Chinese (中英文语义识别)
## Process (Internal → Direct Output)
**Internal Analysis**: Intelligently extract session context, identify tech stack, and structure into actionable format.
**Output**: Direct structured prompt (no intermediate steps shown)
## Output Format
**Dynamic Structure**: Adapt fields based on task type and context needs. Not all fields are required.
**Core Fields** (always present):
- **INTENT**: One-sentence technical goal
- **ACTION**: Concrete steps with technical details
**Optional Fields** (include when relevant):
- **TECH STACK**: Relevant technologies (when tech-specific)
- **CONTEXT**: Session memory findings (when context matters)
- **ATTENTION**: Critical constraints (when risks/requirements exist)
- **SCOPE**: Affected modules/files (for multi-module tasks)
- **METRICS**: Success criteria (for optimization/performance tasks)
- **DEPENDENCIES**: Related components (for integration tasks)
**Example (Simple Task)**:
```
📋 ENHANCED PROMPT
INTENT: Fix authentication token validation in JWT middleware
ACTION:
1. Review token expiration logic in auth middleware
2. Add proper error handling for expired tokens
3. Test with valid/expired/malformed tokens
```
**Example (Complex Task)**:
```
📋 ENHANCED PROMPT
INTENT: Optimize API performance with caching and database indexing
TECH STACK:
- Redis: Response caching
- PostgreSQL: Query optimization
CONTEXT:
- API response times >2s mentioned in previous conversation
- PostgreSQL slow query logs show N+1 problems
ACTION:
1. Profile endpoints to identify slow queries
2. Add PostgreSQL indexes on frequently queried columns
3. Implement Redis caching for read-heavy endpoints
4. Add cache invalidation on data updates
METRICS:
- Target: <500ms API response time
- Cache hit ratio: >80%
ATTENTION:
- Maintain backward compatibility with existing API contracts
- Handle cache invalidation correctly to avoid stale data
```
## Workflow
```
Trigger (-e/--enhance) → Internal Analysis → Dynamic Output
↓ ↓ ↓
User Input Assess Task Type Select Fields
Extract Memory Context Structure Prompt
```
1. **Detect**: User input contains `-e` or `--enhance`
2. **Analyze**:
- Determine task type (fix/optimize/implement/refactor)
- Extract relevant session context
- Identify tech stack and constraints
3. **Structure**:
- Always include: INTENT + ACTION
- Conditionally add: TECH STACK, CONTEXT, ATTENTION, METRICS, etc.
4. **Output**: Present dynamically structured prompt
## Enhancement Guidelines (Internal)
**Always Include**:
- Clear, actionable INTENT
- Concrete ACTION steps with technical details
**Add When Relevant**:
- TECH STACK: Task involves specific technologies
- CONTEXT: Session memory provides useful background
- ATTENTION: Security/compatibility/performance concerns exist
- SCOPE: Multi-module or cross-component changes
- METRICS: Performance/optimization goals need measurement
- DEPENDENCIES: Integration points matter
**Quality Checks**:
- Make vague intent explicit
- Resolve ambiguous references
- Add testing/validation steps
- Include constraints from memory
## Best Practices
- ✅ Trigger only on `-e`/`--enhance` flags
- ✅ Use **dynamic field selection** based on task type
- ✅ Extract **memory context ONLY** (no file reading)
- ✅ Always include INTENT + ACTION as core fields
- ✅ Add optional fields only when relevant to task
- ✅ Direct output (no intermediate steps shown)
- ❌ NO tool calls
- ❌ NO file operations (Bash, Read, Glob, Grep)
- ❌ NO fixed template - adapt to task needs

View File

@@ -148,10 +148,10 @@ bash(codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-
### Gemini/Qwen Commands (Analysis/Documentation) ### Gemini/Qwen Commands (Analysis/Documentation)
```bash ```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 # 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 ## 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 5. **Step Dependencies**: Use `depends_on: [1, 2]` to specify execution order
6. **Parameter Position**: 6. **Parameter Position**:
- Codex: `--skip-git-repo-check -s danger-full-access` at END - 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

View File

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

View File

@@ -7,67 +7,77 @@ type: strategic-guideline
# Intelligent Tools Selection Strategy # Intelligent Tools Selection Strategy
## 📋 Table of Contents ## 📋 Table of Contents
1. [Core Framework](#-core-framework) 1. [Quick Start](#-quick-start)
2. [Tool Specifications](#-tool-specifications) 2. [Tool Specifications](#-tool-specifications)
3. [Command Templates](#-command-templates) 3. [Command Templates](#-command-templates)
4. [Tool Selection Guide](#-tool-selection-guide) 4. [Execution Configuration](#-execution-configuration)
5. [Usage Patterns](#-usage-patterns) 5. [Best Practices](#-best-practices)
6. [Best Practices](#-best-practices)
--- ---
## ⚡ Core Framework ## ⚡ Quick Start
### Tool Overview ### Tool Overview
- **Gemini**: Analysis, understanding, exploration & documentation (primary) - **Gemini**: Analysis, understanding, exploration & documentation (primary)
- **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini) - **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
- **Codex**: Development, implementation & automation - **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 - **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 - **When in doubt, use both** - Parallel usage provides comprehensive coverage
- **Default to tools** - Use specialized tools for most coding tasks, no matter how small - **Default to tools** - Use specialized tools for most coding tasks, no matter how small
- **Lower barriers** - Engage tools immediately when encountering any complexity - **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 - **⚠️ 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 ## 🎯 Tool Specifications
### Gemini ### Gemini & Qwen
- **Command**: `~/.claude/scripts/gemini-wrapper`
#### Overview
- **Commands**: `gemini` (primary) | `qwen` (fallback)
- **Strengths**: Large context window, pattern recognition - **Strengths**: Large context window, pattern recognition
- **Best For**: Analysis, documentation generation, code exploration - **Best For**: Analysis, documentation generation, code exploration, architecture review
- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo) - **Permissions**: Default read-only analysis, MODE=write requires explicit specification
- **Default MODE**: `analysis` (read-only) - **Default MODE**: `analysis` (read-only)
- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write - **⚠️ 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 #### MODE Options
- `analysis` (default) - Read-only analysis and documentation generation
- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
### Qwen **analysis** (default) - Read-only analysis and documentation generation
- **Command**: `~/.claude/scripts/qwen-wrapper` - **⚠️ CRITICAL CONSTRAINT**: Absolutely NO file creation, modification, or deletion operations
- **Strengths**: Large context window, pattern recognition (same as Gemini) - Analysis output should be returned as text response only
- **Best For**: Analysis, documentation generation, code exploration (fallback option when Gemini unavailable) - Use for: code review, architecture analysis, pattern discovery, documentation reading
- **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
#### MODE Options **write** - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
- `analysis` (default) - Read-only analysis and documentation generation (same as Gemini) - Use for: generating documentation files, creating code files, modifying existing files
- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
#### Tool Selection
```bash
# Default: Use Gemini
gemini "analysis prompt"
# Fallback: Use Qwen if Gemini unavailable
qwen "analysis prompt"
```
---
### Codex ### Codex
#### Overview
- **Command**: `codex --full-auto exec` - **Command**: `codex --full-auto exec`
- **Strengths**: Autonomous development, mathematical reasoning - **Strengths**: Autonomous development, mathematical reasoning
- **Best For**: Implementation, testing, automation - **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 - **⚠️ Write Trigger**: Only when user explicitly requests "implement", "modify", "generate code" AND specifies MODE
#### MODE Options #### 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) **auto** - ⚠️ Autonomous development with full file operations
- **Default**: No default mode, MODE must be explicitly specified - 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 #### 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 **Basic Commands**:
codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access - `codex resume` - Resume previous interactive session (picker by default)
codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s danger-full-access - `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 #### Auto-Resume Decision Rules
**When to use `resume --last`**: **When to use `resume --last`**:
- Current task is related to/extends previous Codex task in conversation memory - Current task is related to/extends previous Codex task in conversation memory
- Current task requires context from previous implementation - Current task requires context from previous implementation
@@ -114,6 +136,7 @@ type: strategic-guideline
## 🎯 Command Templates ## 🎯 Command Templates
### Universal Template Structure ### Universal Template Structure
Every command MUST follow this structure: Every command MUST follow this structure:
- [ ] **PURPOSE** - Clear goal and intent - [ ] **PURPOSE** - Clear goal and intent
- [ ] **TASK** - Specific execution task - [ ] **TASK** - Specific execution task
@@ -122,57 +145,41 @@ Every command MUST follow this structure:
- [ ] **EXPECTED** - Clear expected results - [ ] **EXPECTED** - Clear expected results
- [ ] **RULES** - Template reference and constraints - [ ] **RULES** - Template reference and constraints
---
### Standard Command Formats ### Standard Command Formats
#### Gemini Commands #### Gemini & Qwen Commands
```bash ```bash
# Gemini Analysis (read-only, default) # Analysis Mode (read-only, default)
cd [directory] && ~/.claude/scripts/gemini-wrapper -p " # Use 'gemini' (primary) or 'qwen' (fallback)
cd [directory] && gemini "
PURPOSE: [clear analysis goal] PURPOSE: [clear analysis goal]
TASK: [specific analysis task] TASK: [specific analysis task]
MODE: analysis MODE: analysis
CONTEXT: [file references and memory context] CONTEXT: @**/* [default: all files, or specify file patterns]
EXPECTED: [expected output] EXPECTED: [expected output]
RULES: [template reference and constraints] RULES: [template reference and constraints]
" "
# Gemini Write Mode (requires explicit MODE=write) # Write Mode (requires explicit MODE=write)
# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p # NOTE: --approval-mode yolo must be placed AFTER the prompt
cd [directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p " cd [directory] && gemini "
PURPOSE: [clear goal] PURPOSE: [clear goal]
TASK: [specific task] TASK: [specific task]
MODE: write MODE: write
CONTEXT: [file references and memory context] CONTEXT: @**/* [default: all files, or specify file patterns]
EXPECTED: [expected output] EXPECTED: [expected output]
RULES: [template reference and constraints] RULES: [template reference and constraints]
" " --approval-mode yolo
```
#### Qwen Commands # Fallback: Replace 'gemini' with 'qwen' if Gemini unavailable
```bash cd [directory] && qwen "..." # Same syntax as gemini
# 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]
"
``` ```
#### Codex Commands #### Codex Commands
```bash ```bash
# Codex Development (requires explicit MODE=auto) # Codex Development (requires explicit MODE=auto)
# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END # 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] PURPOSE: [clear development goal]
TASK: [specific development task] TASK: [specific development task]
MODE: auto MODE: auto
CONTEXT: [file references and memory context] CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
EXPECTED: [expected deliverables] EXPECTED: [expected deliverables]
RULES: [template reference and constraints] RULES: [template reference and constraints]
" --skip-git-repo-check -s danger-full-access " --skip-git-repo-check -s danger-full-access
@@ -191,48 +198,79 @@ codex -C [directory] --full-auto exec "
PURPOSE: [clear goal] PURPOSE: [clear goal]
TASK: [specific task] TASK: [specific task]
MODE: write MODE: write
CONTEXT: [file references and memory context] CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
EXPECTED: [expected deliverables] EXPECTED: [expected deliverables]
RULES: [template reference and constraints] RULES: [template reference and constraints]
" --skip-git-repo-check -s danger-full-access " --skip-git-repo-check -s danger-full-access
``` ```
---
### Directory Context Configuration ### Directory Context Configuration
Tools execute in current working directory:
- **Gemini**: `cd path/to/project && ~/.claude/scripts/gemini-wrapper -p "prompt"` **Tool Directory Navigation**:
- **Qwen**: `cd path/to/project && ~/.claude/scripts/qwen-wrapper -p "prompt"` - **Gemini & Qwen**: `cd path/to/project && gemini "prompt"` (or `qwen`)
- **Codex**: `codex -C path/to/project --full-auto exec "task"` (Codex still supports -C) - **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 - **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 ```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** **Best Practices**:
When using `$(cat ...)` for template loading in actual CLI commands: - **Recommended Pattern**: Use `cd` to navigate to primary focus directory, then use `--include-directories` for additional context
- **Template reference only, never read**: When user specifies template name, use `$(cat ...)` directly in RULES field, do NOT read template content first - Example: `cd src/auth && gemini "..." --include-directories ../shared,../types`
- **NEVER use escape characters**: `\$`, `\"`, `\'` will break command substitution - Benefits: More precise file references (relative to current directory), clearer intent, better context control
- **In -p "..." context**: Path in `$(cat ...)` needs NO quotes (tilde expands correctly) - Use when `cd` alone limits necessary context visibility
- **Correct**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)` - Keep directory count ≤ 5 for optimal performance
- **WRONG**: `RULES: \$(cat ...)` or `RULES: $(cat \"...\")` or `RULES: $(cat '...')` - Combine with specific file patterns in CONTEXT for precision
- **Why**: Shell executes `$(...)` in subshell where path is safe without quotes - 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 ### CONTEXT Field Configuration
- All files: `@{**/*}`
- Source files: `@{src/**/*}` #### File Pattern Reference
- TypeScript: `@{*.ts,*.tsx}`
- With docs: `@{CLAUDE.md,**/*CLAUDE.md}` **Default Pattern**:
- Tests: `@{src/**/*.test.*}` - **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: For complex file pattern requirements, use semantic discovery tools BEFORE CLI execution:
- **rg (ripgrep)**: Content-based file discovery with regex patterns - **rg (ripgrep)**: Content-based file discovery with regex patterns
- **Code Index MCP**: Semantic file search based on task requirements - **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 mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx") # Find interface files
# Step 2: Build precise CONTEXT from discovery results # 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 # Step 3: Execute CLI with precise file references
cd src && ~/.claude/scripts/gemini-wrapper -p " cd src && gemini "
PURPOSE: Analyze authentication components PURPOSE: Analyze authentication components
TASK: Review auth component patterns and props interfaces TASK: Review auth component patterns and props interfaces
MODE: analysis 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 EXPECTED: Pattern analysis and improvement suggestions
RULES: Focus on type safety and component composition 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 | #### ⚠️ CRITICAL: Command Substitution Rules
|-----------|------|----------|-----------|
| **Analysis** | Gemini (Qwen fallback) | Code exploration, architecture review, patterns | `analysis/pattern.txt` | When using `$(cat ...)` for template loading in actual CLI commands:
| **Architecture** | Gemini (Qwen fallback) | System design, architectural analysis | `analysis/architecture.txt` | - **Template reference only, never read**: When user specifies template name, use `$(cat ...)` directly in RULES field, do NOT read template content first
| **Documentation** | Gemini (Qwen fallback) | Code docs, API specs, guides | `analysis/quality.txt` | - **NEVER use escape characters**: `\$`, `\"`, `\'` will break command substitution
| **Development** | Codex | Feature implementation, bug fixes, testing | `development/feature.txt` | - **In prompt context**: Path in `$(cat ...)` needs NO quotes (tilde expands correctly)
| **Planning** | Gemini/Qwen | Task breakdown, migration planning | `planning/task-breakdown.txt` | - **Correct**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)`
| **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` | - **WRONG**: `RULES: \$(cat ...)` or `RULES: $(cat \"...\")` or `RULES: $(cat '...')`
| **Refactoring** | Multiple | Gemini/Qwen for analysis, Codex for execution | `development/refactor.txt` | - **Why**: Shell executes `$(...)` in subshell where path is safe without quotes
| **Module Documentation** | Gemini (Qwen fallback) | Universal module/file documentation for all levels | `memory/claude-module-unified.txt` |
#### 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 ### Template System
**Base Structure**: `~/.claude/workflows/cli-templates/` #### Base Structure
`~/.claude/workflows/cli-templates/`
#### Available Templates #### Available Templates
``` ```
prompts/ prompts/
├── analysis/ ├── analysis/
@@ -307,11 +357,103 @@ tech-stacks/
└── react-dev.md - React architecture └── 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) ### Workflow Integration (REQUIRED)
When planning any coding task, **ALWAYS** integrate CLI tools: When planning any coding task, **ALWAYS** integrate CLI tools:
1. **Understanding Phase**: Use Gemini for analysis (Qwen as fallback) 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 3. **Implementation Phase**: Use Codex for development
4. **Quality Phase**: Use Codex for testing and validation 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 ### Planning Checklist
For every development task: For every development task:
- [ ] **Purpose defined** - Clear goal and intent - [ ] **Purpose defined** - Clear goal and intent
- [ ] **Mode selected** - Execution mode and permission level determined - [ ] **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 - [ ] **Gemini analysis** completed for understanding
- [ ] **Template selected** - Appropriate template chosen - [ ] **Template selected** - Appropriate template chosen
- [ ] **Constraints specified** - File patterns, scope, requirements - [ ] **Constraints specified** - File patterns, scope, requirements
- [ ] **Implementation approach** - Tool selection and workflow - [ ] **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

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") mcp__exa__get_code_context_exa(query="TypeScript async patterns", tokensNum="dynamic")
# 3. Analyze with Gemini # 3. Analyze with Gemini
cd "src/async" && ~/.claude/scripts/gemini-wrapper -p " cd "src/async" && gemini "
PURPOSE: Understand async patterns PURPOSE: Understand async patterns
CONTEXT: Code index results + Exa context + @{src/async/**/*} CONTEXT: Code index results + Exa context + @src/async/**/*
EXPECTED: Pattern analysis EXPECTED: Pattern analysis
RULES: Focus on TypeScript best practices 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__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__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) 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 ### Debugging
@@ -153,7 +153,7 @@ mcp__code-index__refresh_index() # 刷新索引
mcp__code-index__find_files(pattern="*auth*") # Find auth-related files 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__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 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 ### Project Setup Workflow

View File

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