From 467963eee216fd917eebf1726a483862179dd3b3 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 5 Oct 2025 10:35:27 +0800 Subject: [PATCH] docs: refactor CLI command docs to eliminate redundancy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Streamlined 7 CLI command documentation files by removing duplicate content that's already comprehensively covered in intelligent-tools-strategy.md (loaded in memory). Established single source of truth (SSOT) pattern. Changes: - Removed duplicate command templates (→ strategy lines 51-118) - Removed file pattern reference lists (→ strategy lines 324-329) - Removed complex pattern discovery steps (→ strategy lines 331-355) - Removed MODE field definitions (→ strategy lines 128-143) - Removed tool feature descriptions (→ strategy lines 283-322) Files streamlined: - analyze.md: 117→61 lines (48% reduction) - chat.md: 118→62 lines (47% reduction) - execute.md: 180→100 lines (44% reduction) - codex-execute.md: 481→473 lines (2% - preserved unique content) - mode/bug-index.md: 144→75 lines (48% reduction) - mode/code-analysis.md: 188→76 lines (60% reduction) - mode/plan.md: 100→76 lines (24% reduction) Total reduction: 681 lines removed across all files Each doc now contains only: - Unique purpose and parameters - Command-specific execution flow - Practical examples - Brief reference to intelligent-tools-strategy.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/commands/cli/analyze.md | 102 ++------- .claude/commands/cli/chat.md | 103 ++------- .claude/commands/cli/codex-execute.md | 23 +- .claude/commands/cli/execute.md | 132 +++-------- .claude/commands/cli/mode/bug-index.md | 148 ++++--------- .claude/commands/cli/mode/code-analysis.md | 243 ++++----------------- .claude/commands/cli/mode/plan.md | 142 ++++-------- 7 files changed, 203 insertions(+), 690 deletions(-) diff --git a/.claude/commands/cli/analyze.md b/.claude/commands/cli/analyze.md index 18d6692a..331aa2fd 100644 --- a/.claude/commands/cli/analyze.md +++ b/.claude/commands/cli/analyze.md @@ -14,62 +14,27 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*) ## Purpose -Execute CLI tool analysis on codebase patterns, architecture, or code quality. +Quick codebase analysis using CLI tools. Automatically detects analysis type and selects appropriate template. **Supported Tools**: codex, gemini (default), qwen +## Parameters + +- `--tool ` - Tool selection (default: gemini) +- `--enhance` - Use `/enhance-prompt` for context-aware enhancement +- `` - Description of what to analyze + ## Execution Flow 1. Parse tool selection (default: gemini) -2. If `--enhance`: Execute `/enhance-prompt` first -3. Detect analysis type and select template -4. Build and execute command -5. Return results +2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent +3. Auto-detect analysis type from keywords → select template +4. Build command with auto-detected file patterns +5. Execute and return results -## Enhancement Integration +## File Pattern Auto-Detection -**When `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) to build the analysis command. - - -## Command Template - -**Gemini/Qwen**: -```bash -cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper -p " -PURPOSE: [analysis goal] -TASK: [specific task] -CONTEXT: @{[file-patterns]} @{CLAUDE.md} -EXPECTED: [output format] -RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints] -" -``` - -**Codex**: -```bash -codex -C [dir] --full-auto exec " -PURPOSE: [analysis goal] -TASK: [specific task] -CONTEXT: @{[file-patterns]} @{CLAUDE.md} -EXPECTED: [output format] -RULES: [constraints] -" --skip-git-repo-check -s danger-full-access - -# With image attachment (e.g., UI screenshots, diagrams) -codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access -``` - -## Examples - -```bash -/cli:analyze "authentication patterns" # Gemini (default) -/cli:analyze --tool qwen "component architecture" # Qwen architecture -/cli:analyze --tool codex "performance bottlenecks" # Codex deep analysis -/cli:analyze --enhance "fix auth issues" # Enhanced prompt first -``` - -## File Pattern Logic - -### Auto-Detection from Keywords +Keywords trigger specific file patterns: - "auth" → `@{**/*auth*,**/*user*}` - "component" → `@{src/components/**/*,**/*.component.*}` - "API" → `@{**/api/**/*,**/routes/**/*}` @@ -77,40 +42,19 @@ codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s - "config" → `@{*.config.*,**/config/**/*}` - Generic → `@{src/**/*}` -### Common File Patterns -- All files: `@{**/*}` -- Source files: `@{src/**/*}` -- TypeScript: `@{*.ts,*.tsx}` -- JavaScript: `@{*.js,*.jsx}` -- With docs: `@{CLAUDE.md,**/*CLAUDE.md}` -- Tests: `@{**/*.test.*,**/*.spec.*}` +For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references. -### Complex Pattern Discovery -For complex file pattern requirements, use semantic discovery BEFORE CLI execution: - -**Workflow**: Discover → Extract precise paths → Build CONTEXT field +## Examples ```bash -# Step 1: Discover files semantically -rg "export.*Component" --files-with-matches --type ts -mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx") - -# Step 2: Build precise CONTEXT from discovery results -CONTEXT: @{src/components/Auth.tsx,src/types/auth.d.ts,src/hooks/useAuth.ts} - -# Step 3: Execute CLI with precise file references -cd src && ~/.claude/scripts/gemini-wrapper -p " -PURPOSE: Analyze authentication components -TASK: Review auth component patterns and props interfaces -MODE: analysis -CONTEXT: @{components/Auth.tsx,types/auth.d.ts,hooks/useAuth.ts} -EXPECTED: Pattern analysis and improvement suggestions -RULES: Focus on type safety and component composition -" +/cli:analyze "authentication patterns" # Auto: gemini + auth patterns +/cli:analyze --tool qwen "component architecture" # Qwen architecture analysis +/cli:analyze --tool codex "performance bottlenecks" # Codex deep analysis +/cli:analyze --enhance "fix auth issues" # Enhanced prompt → analysis ``` -## Session Integration - -- **Active Session**: Save results to `.workflow/WFS-[id]/.chat/analysis-[timestamp].md` -- **No Session**: Return results directly to user +## Notes +- Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory) +- Active workflow session: results saved to `.workflow/WFS-[id]/.chat/` +- No session: results returned directly diff --git a/.claude/commands/cli/chat.md b/.claude/commands/cli/chat.md index 80786467..6b163db4 100644 --- a/.claude/commands/cli/chat.md +++ b/.claude/commands/cli/chat.md @@ -1,6 +1,5 @@ --- name: chat - description: Simple CLI interaction command for direct codebase analysis usage: /cli:chat [--tool ] [--enhance] "inquiry" argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry" @@ -11,96 +10,39 @@ examples: allowed-tools: SlashCommand(*), Bash(*) --- +# CLI Chat Command (/cli:chat) + ## Purpose -Direct interaction with CLI tools for codebase analysis and Q&A. +Direct Q&A interaction with CLI tools for codebase analysis. **Supported Tools**: codex, gemini (default), qwen ## Parameters -- `` (Required): Question or analysis request -- `--tool ` (Optional): Select CLI tool (default: gemini) -- `--enhance` (Optional): Enhance inquiry with `/enhance-prompt` first -- `--all-files` (Optional): Include entire codebase in context -- `--save-session` (Optional): Save interaction to workflow session +- `` (Required) - Question or analysis request +- `--tool ` - Select CLI tool (default: gemini) +- `--enhance` - Enhance inquiry with `/enhance-prompt` first +- `--all-files` - Include entire codebase in context +- `--save-session` - Save interaction to workflow session ## Execution Flow 1. Parse tool selection (default: gemini) -2. If `--enhance`: Execute `/enhance-prompt` first -3. Assemble context (files + CLAUDE.md) -4. Execute CLI tool -5. Optional: Save to session - -## Enhancement Integration - -**When `--enhance` flag present**: Execute `/enhance-prompt "[inquiry]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) to build the chat command. +2. If `--enhance`: Execute `/enhance-prompt` to expand user intent +3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files` +4. Execute CLI tool with assembled context +5. Optionally save to workflow session ## Context Assembly -Context gathered from: -1. **Project Guidelines**: `@{CLAUDE.md,**/*CLAUDE.md}` (always) -2. **User-Explicit Files**: Files specified by user -3. **All Files Flag**: `--all-files` includes entire codebase +**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines) -### File Pattern Reference -- All files: `@{**/*}` -- Source files: `@{src/**/*}` -- TypeScript: `@{*.ts,*.tsx}` -- JavaScript: `@{*.js,*.jsx}` -- With docs: `@{CLAUDE.md,**/*CLAUDE.md}` -- Tests: `@{**/*.test.*,**/*.spec.*}` -- Config files: `@{*.config.*,**/config/**/*}` +**Optional**: +- User-explicit files from inquiry keywords +- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter) -### Complex Pattern Discovery -For targeted analysis, use semantic discovery BEFORE CLI execution: - -```bash -# Step 1: Discover relevant files -rg "specific_pattern" --files-with-matches --type ts -mcp__code-index__search_code_advanced(pattern="target_code", file_pattern="*.ts") - -# Step 2: Build CONTEXT with discovered files -CONTEXT: @{CLAUDE.md} @{src/file1.ts,src/file2.ts} - -# Step 3: Execute chat command -cd src && ~/.claude/scripts/gemini-wrapper -p " -PURPOSE: Answer specific inquiry -CONTEXT: @{CLAUDE.md,file1.ts,file2.ts} -EXPECTED: Detailed response -" -``` - -## Command Template - -**Gemini/Qwen**: -```bash -cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper -p " -PURPOSE: [inquiry goal] -TASK: [specific question] -CONTEXT: @{CLAUDE.md} @{target_files} -EXPECTED: [response format] -RULES: [constraints] -" - -# With --all-files -cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper --all-files -p "..." -``` - -**Codex**: -```bash -codex -C [dir] --full-auto exec " -PURPOSE: [inquiry goal] -TASK: [specific question] -CONTEXT: @{CLAUDE.md} @{target_files} -EXPECTED: [response format] -RULES: [constraints] -" --skip-git-repo-check -s danger-full-access - -# With image attachment -codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access -``` +For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field. ## Examples @@ -108,11 +50,12 @@ codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s /cli:chat "analyze the authentication flow" # Gemini (default) /cli:chat --tool qwen "optimize React component" # Qwen /cli:chat --tool codex "review security vulnerabilities" # Codex -/cli:chat --enhance "fix the login" # Enhanced prompt -/cli:chat --all-files "find all API endpoints" # Full codebase +/cli:chat --enhance "fix the login" # Enhanced prompt first +/cli:chat --all-files "find all API endpoints" # Full codebase context ``` -## Session Persistence +## Notes -- **Active Session**: Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md` -- **No Session**: Return results directly \ No newline at end of file +- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory) +- Active workflow session: results saved to `.workflow/WFS-[id]/.chat/` +- No session: results returned directly diff --git a/.claude/commands/cli/codex-execute.md b/.claude/commands/cli/codex-execute.md index eaa49827..31d99726 100644 --- a/.claude/commands/cli/codex-execute.md +++ b/.claude/commands/cli/codex-execute.md @@ -98,34 +98,27 @@ For Each Subtask Group: - Focused file scope (1-5 files per subtask) - **Group coherence**: Subtasks in same group share context/files -### File Pattern Reference -- All files: `@{**/*}` -- Source files: `@{src/**/*}` -- TypeScript: `@{*.ts,*.tsx}` -- JavaScript: `@{*.js,*.jsx}` -- Python: `@{*.py}` -- Tests: `@{**/*.test.*,**/*.spec.*}` -- Config files: `@{*.config.*,**/config/**/*}` +### File Discovery for Task Decomposition -### Complex Pattern Discovery -For task decomposition, use semantic discovery to identify relevant files: +Use `rg` or MCP tools to discover relevant files, then group by domain: -**Workflow**: Discover → Analyze scope → Group by files → Decompose +**Workflow**: Discover → Analyze scope → Group by files → Create task flow +**Example**: ```bash -# Step 1: Discover all relevant files +# Discover files rg "authentication" --files-with-matches --type ts -mcp__code-index__search_code_advanced(pattern="auth|login", file_pattern="*.ts") -# Step 2: Analyze scope and group files +# Group by domain # Group A: src/auth/model.ts, src/auth/schema.ts # Group B: src/api/auth.ts, src/middleware/auth.ts # Group C: tests/auth/*.test.ts -# Step 3: Create task flow based on file groups # Each group becomes a session with related subtasks ``` +File patterns: see intelligent-tools-strategy.md (loaded in memory) + ### Phase 2: Group-Based Execution **Pre-Execution Git Staging** (if valid git repository): diff --git a/.claude/commands/cli/execute.md b/.claude/commands/cli/execute.md index 0bc2461a..7cc67606 100644 --- a/.claude/commands/cli/execute.md +++ b/.claude/commands/cli/execute.md @@ -15,7 +15,7 @@ allowed-tools: SlashCommand(*), Bash(*) ## Purpose -Execute implementation tasks with YOLO permissions (auto-approves all confirmations). +Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations). **Supported Tools**: codex, gemini (default), qwen **Key Feature**: Automatic context inference and file pattern detection @@ -37,131 +37,47 @@ Auto-approves: file pattern inference, execution, file modifications, summary ge ### Context Inference -Auto-selects files based on: -- **Keywords**: "auth" → `@{**/*auth*,**/*user*}` -- **Technology**: "React" → `@{src/**/*.{jsx,tsx}}` -- **Task Type**: "api" → `@{**/api/**/*,**/routes/**/*}` -- **Always**: `@{CLAUDE.md,**/*CLAUDE.md}` +Auto-selects files based on keywords and technology: +- "auth" → `@{**/*auth*,**/*user*}` +- "React" → `@{src/**/*.{jsx,tsx}}` +- "api" → `@{**/api/**/*,**/routes/**/*}` +- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}` -### File Pattern Reference -- All files: `@{**/*}` -- Source files: `@{src/**/*}` -- TypeScript: `@{*.ts,*.tsx}` -- JavaScript: `@{*.js,*.jsx}` -- Python: `@{*.py}` -- Tests: `@{**/*.test.*,**/*.spec.*}` -- Config files: `@{*.config.*,**/config/**/*}` +For precise file targeting, use `rg` or MCP tools to discover files first. -### Complex Pattern Discovery -For precise file targeting, use semantic discovery BEFORE CLI execution: +### Codex Session Continuity -**Workflow**: Discover → Extract precise paths → Build CONTEXT field - -```bash -# Step 1: Discover files semantically -rg "target_pattern" --files-with-matches --type ts -mcp__code-index__find_files(pattern="*auth*") - -# Step 2: Build precise CONTEXT from discovery results -CONTEXT: @{src/auth/module.ts,src/middleware/auth.ts,CLAUDE.md} - -# Step 3: Execute with precise file references -codex -C src --full-auto exec " -PURPOSE: Implement authentication -TASK: Add JWT validation -MODE: auto -CONTEXT: @{auth/module.ts,middleware/auth.ts,CLAUDE.md} -EXPECTED: Complete implementation -RULES: Follow security best practices -" --skip-git-repo-check -s danger-full-access -``` - -## Command Templates - -### Gemini/Qwen (with YOLO approval) -```bash -cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper --approval-mode yolo -p " -PURPOSE: [implementation goal] -TASK: [specific task] -MODE: write -CONTEXT: @{inferred_patterns} @{CLAUDE.md} -EXPECTED: Implementation with file:line references -RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints] -" -``` - -### Codex -```bash -codex -C [dir] --full-auto exec " -PURPOSE: [implementation goal] -TASK: [specific task] -MODE: auto -CONTEXT: @{inferred_patterns} @{CLAUDE.md} -EXPECTED: Implementation with file:line references -RULES: [constraints] -" --skip-git-repo-check -s danger-full-access - -# With image attachment -codex -C [dir] -i design.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access -``` - -### Codex with Resume (for related tasks) +**Resume Pattern** for related tasks: ```bash # First task - establish session -codex -C [dir] --full-auto exec " -PURPOSE: [implementation goal] -TASK: [specific task] -MODE: auto -CONTEXT: @{inferred_patterns} @{CLAUDE.md} -EXPECTED: Implementation with file:line references -RULES: [constraints] -" --skip-git-repo-check -s danger-full-access +codex -C [dir] --full-auto exec "[task]" --skip-git-repo-check -s danger-full-access -# Related follow-up task - continue session -codex --full-auto exec " -PURPOSE: [continuation goal] -TASK: [related task] -MODE: auto -CONTEXT: Previous implementation from session -EXPECTED: Enhanced/extended implementation -RULES: Maintain consistency with previous work -" resume --last --skip-git-repo-check -s danger-full-access +# Related task - continue session +codex --full-auto exec "[related-task]" resume --last --skip-git-repo-check -s danger-full-access ``` -**Resume Decision**: Use `resume --last` when current task extends/relates to previous execution in conversation memory. See intelligent-tools-strategy.md for auto-resume rules. +Use `resume --last` when current task extends/relates to previous execution. See intelligent-tools-strategy.md for auto-resume rules. -## Enhancement Integration +## Parameters -**When `--enhance` flag present** (Description Mode only): -1. Execute `/enhance-prompt "[description]"` first -2. Use enhanced output (INTENT/CONTEXT/ACTION) for execution -3. Build command with enhanced context - -**Note**: Task ID Mode uses task JSON directly (no enhancement). - -## Options - -- `--tool `: Select CLI tool (default: gemini) -- `--enhance`: Enhance input with `/enhance-prompt` first -- `--debug`: Verbose logging -- `--save-session`: Save execution to workflow session +- `--tool ` - Select CLI tool (default: gemini) +- `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only) +- `` - Natural language description or task identifier +- `--debug` - Verbose logging +- `--save-session` - Save execution to workflow session ## Workflow Integration **Session Management**: Auto-detects `.workflow/.active-*` marker -- **Active**: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md` -- **None**: Create new session +- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md` +- No session: Create new session **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary -**Auto-Generated Outputs**: -- **Summary**: `.summaries/[TASK-ID]-summary.md` -- **Session**: `.chat/execute-[timestamp].md` - ## Examples ```bash -# Description mode (default: gemini) +# Description mode with auto-detection /cli:execute "implement JWT authentication with middleware" # Enhanced prompt @@ -177,3 +93,7 @@ RULES: Maintain consistency with previous work /cli:execute --tool qwen --enhance "refactor auth module" ``` +## Notes + +- Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory) +- Auto-generated outputs: `.summaries/[TASK-ID]-summary.md`, `.chat/execute-[timestamp].md` diff --git a/.claude/commands/cli/mode/bug-index.md b/.claude/commands/cli/mode/bug-index.md index aae17f88..85676d47 100644 --- a/.claude/commands/cli/mode/bug-index.md +++ b/.claude/commands/cli/mode/bug-index.md @@ -14,131 +14,61 @@ allowed-tools: SlashCommand(*), Bash(*) ## Purpose -Execute systematic bug analysis and fix suggestions using CLI tools with diagnostic template. +Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bug-fix.md`). **Supported Tools**: codex, gemini (default), qwen +**Key Feature**: `--cd` flag for directory-scoped analysis + +## Parameters + +- `--tool ` - Tool selection (default: gemini) +- `--enhance` - Enhance bug description with `/enhance-prompt` first +- `--cd "path"` - Target directory for focused analysis +- `` (Required) - Bug description or error message ## Execution Flow -1. **Parse tool selection**: Extract `--tool` flag (default: gemini) -2. **If `--enhance` flag present**: Execute `/enhance-prompt "[bug-description]"` first -3. Parse bug description (original or enhanced) -4. Detect target directory (from `--cd` or auto-infer) -5. Build command for selected tool with bug-fix template -6. Execute analysis -7. Save to session (if active) +1. Parse tool and directory options +2. If `--enhance`: Execute `/enhance-prompt` to expand bug context +3. Use bug-fix template: `~/.claude/prompt-templates/bug-fix.md` +4. Execute with `--all-files` in target directory +5. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md` -## Core Rules +## Analysis Focus (via Template) -1. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis -2. **Directory Context**: Use `cd` when `--cd` provided or auto-detected -3. **Template Required**: Always use bug-fix template -4. **Session Output**: Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md` - -## Command Template - -```bash -cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: [bug analysis goal] -TASK: Systematic bug analysis and fix recommendations -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] -EXPECTED: Root cause analysis, code path tracing, targeted fixes -RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description] -" -``` +- Root cause investigation +- Code path tracing +- Targeted minimal fixes +- Impact assessment ## Examples -**Basic Bug Analysis**: ```bash -cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Debug authentication null pointer error -TASK: Identify root cause and provide fix -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} -EXPECTED: Root cause, code path, minimal fix, impact assessment -RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow -" +# Basic bug analysis +/cli:mode:bug-index "null pointer in authentication" + +# Directory-specific +/cli:mode:bug-index --cd "src/auth" "token validation fails" + +# Enhanced description +/cli:mode:bug-index --enhance "login broken" + +# Qwen for architecture-related bugs +/cli:mode:bug-index --tool qwen "circular dependency in modules" ``` -**Directory-Specific**: -```bash -cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Fix token validation failure -TASK: Analyze token validation bug in auth module -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} -EXPECTED: Validation logic analysis, fix recommendation -RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently -" -``` - -**With Enhancement**: -```bash -# User: /gemini:mode:bug-index --enhance "login broken" - -# Step 1: Enhance -/enhance-prompt "login broken" -# Returns: -# INTENT: Debug login authentication failure -# CONTEXT: Known session state issue -# ACTION: Check session management → verify token → test flow - -# Step 2: Analyze with enhanced context -cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Debug login authentication failure -TASK: Analyze session management, token handling, auth flow -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} Known: session state issue -EXPECTED: Root cause in session/token, targeted fix -RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Focus on session management -" -``` - -## Analysis Focus - -**Template provides**: -- **Root Cause Analysis**: Systematic investigation -- **Code Path Tracing**: Execution flow analysis -- **Targeted Solutions**: Minimal, specific fixes -- **Impact Assessment**: Side effect evaluation - -## File Pattern Reference - -### Common Patterns -- All files: `@{**/*}` -- Source files: `@{src/**/*}` -- TypeScript: `@{*.ts,*.tsx}` -- JavaScript: `@{*.js,*.jsx}` -- Python: `@{*.py}` -- With docs: `@{CLAUDE.md,**/*CLAUDE.md}` -- Tests: `@{**/*.test.*,**/*.spec.*}` - -### Complex Pattern Discovery -For bug investigation, use semantic discovery to find relevant code: +## Bug Investigation Workflow ```bash -# Step 1: Find bug-related files -rg "error_keyword|exception_pattern" --files-with-matches -mcp__code-index__search_code_advanced(pattern="throw|catch|error", file_pattern="*.ts") +# 1. Find bug-related files +rg "error_keyword" --files-with-matches -# Step 2: Trace error propagation path -# Identify: origin → propagation → handler - -# Step 3: Execute bug analysis with focused context -cd src && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Debug null pointer error in authentication -TASK: Identify root cause and provide fix -MODE: analysis -CONTEXT: @{CLAUDE.md,auth/service.ts,middleware/auth.ts} -EXPECTED: Root cause, execution trace, minimal fix -RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in token validation -" +# 2. Execute bug analysis with focused context +/cli:mode:bug-index --cd "src/module" "specific error description" ``` -## Session Output +## Notes -**Location**: `.workflow/WFS-[topic]/.chat/bug-index-[timestamp].md` - -**Includes**: -- Bug description -- Template used -- Analysis results -- Recommended actions \ No newline at end of file +- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory) +- Template path: `~/.claude/prompt-templates/bug-fix.md` +- Always uses `--all-files` for comprehensive codebase context diff --git a/.claude/commands/cli/mode/code-analysis.md b/.claude/commands/cli/mode/code-analysis.md index c72b73f7..43441f07 100644 --- a/.claude/commands/cli/mode/code-analysis.md +++ b/.claude/commands/cli/mode/code-analysis.md @@ -14,221 +14,62 @@ allowed-tools: SlashCommand(*), Bash(*) ## Purpose -Execute systematic code analysis and debugging using CLI tools with specialized code analysis template. +Systematic code analysis with execution path tracing template (`~/.claude/prompt-templates/code-analysis.md`). **Supported Tools**: codex, gemini (default), qwen +**Key Feature**: `--cd` flag for directory-scoped analysis + +## Parameters + +- `--tool ` - Tool selection (default: gemini) +- `--enhance` - Enhance analysis target with `/enhance-prompt` first +- `--cd "path"` - Target directory for focused analysis +- `` (Required) - Code analysis target or question ## Execution Flow -1. **Parse tool selection**: Extract `--tool` flag (default: gemini) -2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first -3. Parse analysis target (original or enhanced) -4. Detect target directory (from `--cd` or auto-infer) -5. Build command for selected tool with code-analysis template -6. Execute deep analysis -7. Save to session (if active) +1. Parse tool and directory options +2. If `--enhance`: Execute `/enhance-prompt` to expand analysis intent +3. Use code-analysis template: `~/.claude/prompt-templates/code-analysis.md` +4. Execute with `--all-files` in target directory +5. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md` -## Core Rules +## Analysis Capabilities (via Template) -1. **Tool Selection**: Use `--tool` value or default to gemini -2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis -3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected -4. **Template Required**: Always use code-analysis template -5. **Session Output**: Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md` - -## Analysis Capabilities - -The code-analysis template provides: -- **Systematic Code Analysis**: Break down complex code into manageable parts -- **Execution Path Tracing**: Track variable states and call stacks -- **Control & Data Flow**: Understand code logic and data transformations -- **Call Flow Visualization**: Diagram function calling sequences -- **Logical Reasoning**: Explain "why" behind code behavior -- **Debugging Insights**: Identify potential bugs or inefficiencies - -## File Pattern Reference - -### Common Patterns -- All files: `@{**/*}` -- Source files: `@{src/**/*}` -- TypeScript: `@{*.ts,*.tsx}` -- JavaScript: `@{*.js,*.jsx}` -- Python: `@{*.py}` -- With docs: `@{CLAUDE.md,**/*CLAUDE.md}` -- Tests: `@{**/*.test.*,**/*.spec.*}` - -### Complex Pattern Discovery -For deep code analysis, use semantic discovery to trace execution paths: - -```bash -# Step 1: Find entry points and related files -rg "function.*authenticate|class.*AuthService" --files-with-matches -mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern="*.ts") - -# Step 2: Trace execution flow through discovered files -# Build call graph: entry → middleware → service → repository - -# Step 3: Execute analysis with focused context -cd src && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Trace authentication execution flow -TASK: Analyze complete auth flow from request to response -MODE: analysis -CONTEXT: @{CLAUDE.md,api/auth.ts,middleware/auth.ts,services/auth.ts} -EXPECTED: Step-by-step execution trace with call diagram -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow -" -``` - -## Command Templates - -### Gemini (Default) -```bash -cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: [analysis goal from target] -TASK: Deep code analysis with execution path tracing -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] -EXPECTED: Systematic analysis, call flow diagram, data transformations, logical explanation -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect] -" -``` - -### Qwen -```bash -cd [directory] && ~/.claude/scripts/qwen-wrapper --all-files -p " -PURPOSE: [analysis goal from target] -TASK: Architecture-level code analysis and pattern recognition -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] -EXPECTED: Architectural insights, design patterns, code structure analysis -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect] -" -``` - -### Codex -```bash -codex -C [directory] --full-auto exec " -PURPOSE: [analysis goal from target] -TASK: Deep code inspection with debugging insights -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] -EXPECTED: Execution trace, bug identification, optimization opportunities -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect] -" --skip-git-repo-check -s danger-full-access -``` +- Execution path tracing with variable states +- Call flow visualization and diagrams +- Control & data flow analysis +- Logical reasoning ("why" behind code behavior) +- Debugging insights and inefficiency detection ## Examples -**Basic Code Analysis (Gemini)**: ```bash -cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Analyze authentication flow logic -TASK: Trace authentication execution path and identify key functions -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} -EXPECTED: Step-by-step flow, call diagram, data passing between functions -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow and security -" +# Basic code analysis +/cli:mode:code-analysis "trace authentication flow" + +# Directory-specific with enhancement +/cli:mode:code-analysis --cd "src/auth" --enhance "how does JWT work" + +# Qwen for architecture analysis +/cli:mode:code-analysis --tool qwen "explain microservices communication" + +# Codex for deep tracing +/cli:mode:code-analysis --tool codex --cd "src/api" "trace request lifecycle" ``` -**Architecture Analysis (Qwen)**: -```bash -# User: /cli:mode:code-analysis --tool qwen "explain data transformation pipeline" +## Code Tracing Workflow -cd . && ~/.claude/scripts/qwen-wrapper --all-files -p " -PURPOSE: Explain data transformation pipeline architecture -TASK: Analyze data flow and transformation patterns -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} -EXPECTED: Pipeline structure, transformation stages, data format changes -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on data flow and patterns -" +```bash +# 1. Find entry points +rg "function.*main|export.*handler" --files-with-matches + +# 2. Execute deep analysis +/cli:mode:code-analysis --cd "src" "trace execution from entry point" ``` -**Deep Debugging (Codex)**: -```bash -# User: /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration" +## Notes -codex -C src/core --full-auto exec " -PURPOSE: Trace execution path for user registration -TASK: Deep analysis of registration flow with debugging insights -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} -EXPECTED: Complete execution trace, variable states, potential issues -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on edge cases and error handling -" --skip-git-repo-check -s danger-full-access -``` - -**With Enhancement**: -```bash -# User: /cli:mode:code-analysis --enhance "why is login slow" - -# Step 1: Enhance -/enhance-prompt "why is login slow" -# Returns: -# INTENT: Identify performance bottlenecks in login flow -# CONTEXT: Authentication module, database queries -# ACTION: Trace execution path → identify slow operations → suggest optimizations - -# Step 2: Analyze with enhanced context -cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Identify performance bottlenecks in login flow -TASK: Trace login execution path and measure operation costs -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} @{**/*auth*,**/*login*} -EXPECTED: Performance analysis, bottleneck identification, optimization recommendations -RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on performance and database queries -" -``` - -## Analysis Output Structure - -Based on code-analysis.md template, output includes: - -### 1. 思考过程 (Thinking Process) -- Analysis strategy and approach -- Key assumptions about code behavior - -### 2. 对问题的理解 (Understanding) -- Restate analysis target -- Confirm understanding of requirements - -### 3. 核心解答 (Core Answer) -- Direct, concise answer to analysis question - -### 4. 详细分析与调用逻辑 (Detailed Analysis) -- **代码段识别**: Relevant code sections -- **执行流程**: Step-by-step execution flow -- **调用图**: Visual call flow diagram with symbols: - - `───►` Function call - - `◄───` Return - - `│` Continuation - - `├─` Intermediate step - - `└─` Last step in block -- **数据传递**: Data passing and state changes -- **逻辑解释**: Why code behaves this way - -### 5. 总结 (Summary) -- Key findings and recommendations - -## Session Output - -**Location**: `.workflow/WFS-[topic]/.chat/code-analysis-[timestamp].md` - -**Includes**: -- Analysis target -- Template used -- Complete structured analysis -- Call flow diagrams -- Debugging insights -- Recommendations - -## Use Cases - -| Use Case | Best Tool | Focus | -|----------|-----------|-------| -| **Understand execution flow** | gemini | Call sequences, data flow | -| **Architectural patterns** | qwen | Design patterns, structure | -| **Performance debugging** | codex | Bottlenecks, optimizations | -| **Bug investigation** | codex | Error paths, edge cases | -| **Code review** | gemini | Logic correctness, clarity | -| **Refactoring planning** | qwen | Structure improvements | - -## Tool Selection Guide - -- **Gemini**: Best for general code understanding and tracing -- **Qwen**: Best for architectural analysis and pattern recognition -- **Codex**: Best for deep debugging and performance analysis \ No newline at end of file +- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory) +- Template path: `~/.claude/prompt-templates/code-analysis.md` +- Always uses `--all-files` for comprehensive code context diff --git a/.claude/commands/cli/mode/plan.md b/.claude/commands/cli/mode/plan.md index 165ebf04..8f30473d 100644 --- a/.claude/commands/cli/mode/plan.md +++ b/.claude/commands/cli/mode/plan.md @@ -14,120 +14,62 @@ allowed-tools: SlashCommand(*), Bash(*) ## Purpose -Execute planning and architecture analysis using CLI tools with specialized template. +Comprehensive planning and architecture analysis with strategic planning template (`~/.claude/prompt-templates/plan.md`). **Supported Tools**: codex, gemini (default), qwen +**Key Feature**: `--cd` flag for directory-scoped planning + +## Parameters + +- `--tool ` - Tool selection (default: gemini) +- `--enhance` - Enhance topic with `/enhance-prompt` first +- `--cd "path"` - Target directory for focused planning +- `` (Required) - Planning topic or architectural question ## Execution Flow -1. **Parse tool selection**: Extract `--tool` flag (default: gemini) -2. **If `--enhance` flag present**: Execute `/enhance-prompt "[topic]"` first -3. Parse topic (original or enhanced) -4. Detect target directory (from `--cd` or auto-infer) -5. Build command for selected tool with planning template -6. Execute analysis -7. Save to session (if active) +1. Parse tool and directory options +2. If `--enhance`: Execute `/enhance-prompt` to expand planning context +3. Use planning template: `~/.claude/prompt-templates/plan.md` +4. Execute with `--all-files` in target directory +5. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md` -## Core Rules +## Planning Capabilities (via Template) -1. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning -2. **Directory Context**: Use `cd` when `--cd` provided or auto-detected -3. **Template Required**: Always use planning template -4. **Session Output**: Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md` - -## Command Template - -```bash -cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: [planning goal from topic] -TASK: Comprehensive planning and architecture analysis -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory] -EXPECTED: Strategic insights, implementation roadmap, key decisions -RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area] -" -``` - -## File Pattern Reference - -### Common Patterns -- All files: `@{**/*}` -- Source files: `@{src/**/*}` -- TypeScript: `@{*.ts,*.tsx}` -- JavaScript: `@{*.js,*.jsx}` -- With docs: `@{CLAUDE.md,**/*CLAUDE.md}` -- Tests: `@{**/*.test.*,**/*.spec.*}` -- Config files: `@{*.config.*,**/config/**/*}` - -### Complex Pattern Discovery -For comprehensive planning, use semantic discovery to understand project scope: - -```bash -# Step 1: Discover project structure -~/.claude/scripts/get_modules_by_depth.sh -mcp__code-index__find_files(pattern="*.ts") - -# Step 2: Identify key architectural files -rg "export.*class|export.*interface" --files-with-matches -mcp__code-index__search_code_advanced(pattern="class.*Service|interface.*Config") - -# Step 3: Execute planning with full context -cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Plan feature implementation -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} Full project context -EXPECTED: Architecture design and implementation roadmap -RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability -" -``` +- Strategic architecture insights +- Implementation roadmaps +- Key technical decisions +- Risk assessment +- Resource planning ## Examples -**Basic Planning**: ```bash -cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Design user dashboard feature architecture -TASK: Comprehensive architecture planning for dashboard -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} -EXPECTED: Architecture design, component structure, implementation roadmap -RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability and UX -" +# Basic planning +/cli:mode:plan "design user dashboard" + +# Enhanced with directory scope +/cli:mode:plan --cd "src/api" --enhance "plan API refactoring" + +# Qwen for architecture planning +/cli:mode:plan --tool qwen "plan microservices migration" + +# Codex for technical planning +/cli:mode:plan --tool codex "plan testing strategy" ``` -**Directory-Specific**: +## Planning Workflow + ```bash -cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: Plan authentication system redesign -TASK: Analyze current auth and plan improvements -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} -EXPECTED: Migration strategy, security improvements, timeline -RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on security and backward compatibility -" +# 1. Gather existing architecture info +rg "architecture|design" --files-with-matches + +# 2. Execute planning analysis +/cli:mode:plan "topic for strategic planning" ``` -**With Enhancement**: -```bash -# User: /gemini:mode:plan --enhance "fix auth issues" +## Notes -# Step 1: Enhance -/enhance-prompt "fix auth issues" -# Returns structured planning context - -# Step 2: Plan with enhanced input -cd . && ~/.claude/scripts/gemini-wrapper --all-files -p " -PURPOSE: [enhanced goal] -TASK: [enhanced task description] -CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [enhanced context] -EXPECTED: Strategic plan with enhanced requirements -RULES: $(cat ~/.claude/prompt-templates/plan.md) | [enhanced constraints] -" -``` - -## Session Output - -**Location**: `.workflow/WFS-[topic]/.chat/plan-[timestamp].md` - -**Includes**: -- Planning topic -- Template used -- Analysis results -- Implementation roadmap -- Key decisions \ No newline at end of file +- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory) +- Template path: `~/.claude/prompt-templates/plan.md` +- Always uses `--all-files` for comprehensive project context