diff --git a/.claude/commands/codex/analyze.md b/.claude/commands/codex/analyze.md new file mode 100644 index 00000000..9c3808ef --- /dev/null +++ b/.claude/commands/codex/analyze.md @@ -0,0 +1,155 @@ +--- +name: analyze +description: Quick analysis of codebase patterns, architecture, and code quality using Codex CLI +usage: /codex:analyze +argument-hint: "analysis target or type" +examples: + - /codex:analyze "React hooks patterns" + - /codex:analyze "authentication security" + - /codex:analyze "performance bottlenecks" + - /codex:analyze "API design patterns" +model: haiku +--- + +# Codex Analysis Command (/codex:analyze) + +## Overview +Quick analysis tool for codebase insights using intelligent pattern detection and template-driven analysis with Codex CLI. + +**Core Guidelines**: @~/.claude/workflows/codex-unified.md + +⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. + +## Analysis Types + +| Type | Purpose | Example | +|------|---------|---------| +| **pattern** | Code pattern detection | "React hooks usage patterns" | +| **architecture** | System structure analysis | "component hierarchy structure" | +| **security** | Security vulnerabilities | "authentication vulnerabilities" | +| **performance** | Performance bottlenecks | "rendering performance issues" | +| **quality** | Code quality assessment | "testing coverage analysis" | +| **dependencies** | Third-party analysis | "outdated package dependencies" | + +## Quick Usage + +### Basic Analysis +```bash +/codex:analyze "authentication patterns" +``` +**Executes**: `codex exec "@{**/*auth*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)"` + +### Targeted Analysis +```bash +/codex:analyze "React component architecture" +``` +**Executes**: `codex exec "@{src/components/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt)"` + +### Security Focus +```bash +/codex:analyze "API security vulnerabilities" +``` +**Executes**: `codex exec "@{**/api/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt)"` + +## Codex-Specific Patterns + +**Essential File Patterns** (Required for Codex): +```bash +@{**/*} # All files recursively +@{src/**/*} # All source files +@{*.ts,*.js} # Specific file types +@{CLAUDE.md,**/*CLAUDE.md} # Documentation hierarchy +@{package.json,*.config.*} # Configuration files +``` + +## Templates Used + +Templates are automatically selected based on analysis type: +- **Pattern Analysis**: `~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt` +- **Architecture Analysis**: `~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt` +- **Security Analysis**: `~/.claude/workflows/cli-templates/prompts/analysis/security.txt` +- **Performance Analysis**: `~/.claude/workflows/cli-templates/prompts/analysis/performance.txt` + +## Workflow Integration + +⚠️ **Session Check**: Automatically detects active workflow session via `.workflow/.active-*` marker file. + +**Analysis results saved to:** +- Active session: `.workflow/WFS-[topic]/.chat/analysis-[timestamp].md` +- No session: Temporary analysis output + +## Common Patterns + +### Technology Stack Analysis +```bash +/codex:analyze "project technology stack" +# Executes: codex exec "@{package.json,*.config.*,CLAUDE.md} [analysis prompt]" +``` + +### Code Quality Review +```bash +/codex:analyze "code quality and standards" +# Executes: codex exec "@{src/**/*,test/**/*,CLAUDE.md} [analysis prompt]" +``` + +### Migration Planning +```bash +/codex:analyze "legacy code modernization" +# Executes: codex exec "@{**/*.{js,jsx,ts,tsx},CLAUDE.md} [analysis prompt]" +``` + +### Module-Specific Analysis +```bash +/codex:analyze "authentication module patterns" +# Executes: codex exec "@{src/auth/**/*,**/*auth*,CLAUDE.md} [analysis prompt]" +``` + +## Output Format + +Analysis results include: +- **File References**: Specific file:line locations +- **Code Examples**: Relevant code snippets +- **Patterns Found**: Common patterns and anti-patterns +- **Recommendations**: Actionable improvements +- **Integration Points**: How components connect + +## Execution Templates + +### Basic Analysis Template +```bash +codex exec "@{inferred_patterns} @{CLAUDE.md,**/*CLAUDE.md} + +Analysis Type: [analysis_type] + +Provide: +- Pattern identification and analysis +- Code quality assessment +- Architecture insights +- Specific recommendations with file:line references" +``` + +### Template-Enhanced Analysis +```bash +codex exec "@{inferred_patterns} @{CLAUDE.md,**/*CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/[template].txt) + +Focus: [analysis_type] +Context: [user_description]" +``` + +## Error Prevention + +- **Always include @ patterns**: Commands without file references will fail +- **Test patterns first**: Validate @ patterns match existing files +- **Use comprehensive patterns**: `@{**/*}` when unsure of file structure +- **Include documentation**: Always add `@{CLAUDE.md,**/*CLAUDE.md}` for context + +## Codex vs Gemini + +| Feature | Codex | Gemini | +|---------|-------|--------| +| File Loading | `@` patterns **required** | `--all-files` available | +| Command Structure | `codex exec "@{patterns}"` | `gemini --all-files -p` | +| Pattern Flexibility | Must be explicit | Auto-includes with flag | + +For detailed syntax, patterns, and advanced usage see: +**@~/.claude/workflows/codex-unified.md** \ No newline at end of file diff --git a/.claude/commands/codex/chat.md b/.claude/commands/codex/chat.md new file mode 100644 index 00000000..bc03f304 --- /dev/null +++ b/.claude/commands/codex/chat.md @@ -0,0 +1,189 @@ +--- +name: chat + +description: Simple Codex CLI interaction command for direct codebase analysis and development +usage: /codex:chat "inquiry" +argument-hint: "your question or development request" +examples: + - /codex:chat "analyze the authentication flow" + - /codex:chat "how can I optimize this React component performance?" + - /codex:chat "implement user profile editing functionality" +allowed-tools: Bash(codex:*) +model: sonnet +--- + +### 🚀 **Command Overview: `/codex:chat`** + +- **Type**: Basic Codex CLI Wrapper +- **Purpose**: Direct interaction with the `codex` CLI for simple codebase analysis and development +- **Core Tool**: `Bash(codex:*)` - Executes the external Codex CLI tool + +⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. + +### 📥 **Parameters & Usage** + +- **`` (Required)**: Your question or development request +- **`@{patterns}` (Required)**: File patterns must be explicitly specified +- **`--save-session` (Optional)**: Saves the interaction to current workflow session directory +- **`--full-auto` (Optional)**: Enable autonomous development mode + +### 🔄 **Execution Workflow** + +`Parse Input` **->** `Infer File Patterns` **->** `Construct Prompt` **->** `Execute Codex CLI` **->** `(Optional) Save Session` + +### 📚 **Context Assembly** + +Context is gathered from: +1. **Project Guidelines**: Always includes `@{CLAUDE.md,**/*CLAUDE.md}` +2. **Inferred Patterns**: Auto-detects relevant files based on inquiry keywords +3. **Comprehensive Fallback**: Uses `@{**/*}` when pattern inference unclear + +### 📝 **Prompt Format** + +``` +=== CONTEXT === +@{CLAUDE.md,**/*CLAUDE.md} [Project guidelines] +@{inferred_patterns} [Auto-detected or comprehensive patterns] + +=== USER INPUT === +[The user inquiry text] +``` + +### ⚙️ **Execution Implementation** + +```pseudo +FUNCTION execute_codex_chat(user_inquiry, flags): + // Always include project guidelines + patterns = "@{CLAUDE.md,**/*CLAUDE.md}" + + // Infer relevant file patterns from inquiry keywords + inferred_patterns = infer_file_patterns(user_inquiry) + IF inferred_patterns: + patterns += "," + inferred_patterns + ELSE: + patterns += ",@{**/*}" // Fallback to all files + + // Construct prompt + prompt = "=== CONTEXT ===\n" + patterns + "\n" + prompt += "\n=== USER INPUT ===\n" + user_inquiry + + // Execute codex CLI + IF flags contain "--full-auto": + result = execute_tool("Bash(codex:*)", "--full-auto", prompt) + ELSE: + result = execute_tool("Bash(codex:*)", "exec", prompt) + + // Save session if requested + IF flags contain "--save-session": + save_chat_session(user_inquiry, patterns, result) + + RETURN result +END FUNCTION +``` + +### 🎯 **Pattern Inference Logic** + +**Auto-detects file patterns based on keywords:** + +| Keywords | Inferred Pattern | Purpose | +|----------|-----------------|---------| +| "auth", "login", "user" | `@{**/*auth*,**/*user*}` | Authentication code | +| "React", "component" | `@{src/**/*.{jsx,tsx}}` | React components | +| "API", "endpoint", "route" | `@{**/api/**/*,**/routes/**/*}` | API code | +| "test", "spec" | `@{test/**/*,**/*.test.*,**/*.spec.*}` | Test files | +| "config", "setup" | `@{*.config.*,package.json}` | Configuration | +| "database", "db", "model" | `@{**/models/**/*,**/db/**/*}` | Database code | +| "style", "css" | `@{**/*.{css,scss,sass}}` | Styling files | + +**Fallback**: If no keywords match, uses `@{**/*}` for comprehensive analysis. + +### 💾 **Session Persistence** + +When `--save-session` flag is used: +- Check for existing active session (`.workflow/.active-*` markers) +- Save to existing session's `.chat/` directory or create new session +- File format: `chat-YYYYMMDD-HHMMSS.md` +- Include query, context patterns, and response in saved file + +**Session Template:** +```markdown +# Chat Session: [Timestamp] + +## Query +[Original user inquiry] + +## Context Patterns +[File patterns used in analysis] + +## Codex Response +[Complete response from Codex CLI] + +## Pattern Inference +[How file patterns were determined] +``` + +### 🔧 **Usage Examples** + +#### Basic Development Chat +```bash +/codex:chat "implement password reset functionality" +# Executes: codex exec "@{CLAUDE.md,**/*CLAUDE.md,**/*auth*,**/*user*} implement password reset functionality" +``` + +#### Architecture Discussion +```bash +/codex:chat "how should I structure the user management module?" +# Executes: codex exec "@{CLAUDE.md,**/*CLAUDE.md,**/*user*,src/**/*} how should I structure the user management module?" +``` + +#### Performance Optimization +```bash +/codex:chat "optimize React component rendering performance" +# Executes: codex exec "@{CLAUDE.md,**/*CLAUDE.md,src/**/*.{jsx,tsx}} optimize React component rendering performance" +``` + +#### Full Auto Mode +```bash +/codex:chat "create a complete user dashboard with charts" --full-auto +# Executes: codex --full-auto "@{CLAUDE.md,**/*CLAUDE.md,**/*user*,**/*dashboard*} create a complete user dashboard with charts" +``` + +### ⚠️ **Error Prevention** + +- **Pattern validation**: Ensures @ patterns match existing files +- **Fallback patterns**: Uses comprehensive `@{**/*}` when inference fails +- **Context verification**: Always includes project guidelines +- **Session handling**: Graceful handling of missing workflow directories + +### 📊 **Codex vs Gemini Chat** + +| Feature | Codex Chat | Gemini Chat | +|---------|------------|-------------| +| File Loading | `@` patterns **required** | `--all-files` available | +| Pattern Inference | Automatic keyword-based | Manual or --all-files | +| Development Focus | Code generation & implementation | Analysis & exploration | +| Automation | `--full-auto` mode available | Interactive only | +| Command Structure | `codex exec "@{patterns}"` | `gemini --all-files -p` | + +### 🚀 **Advanced Features** + +#### Multi-Pattern Inference +```bash +/codex:chat "implement React authentication with API integration" +# Infers: @{CLAUDE.md,**/*CLAUDE.md,src/**/*.{jsx,tsx},**/*auth*,**/api/**/*} +``` + +#### Context-Aware Development +```bash +/codex:chat "add unit tests for the payment processing module" +# Infers: @{CLAUDE.md,**/*CLAUDE.md,**/*payment*,test/**/*,**/*.test.*} +``` + +#### Configuration Analysis +```bash +/codex:chat "review and optimize build configuration" +# Infers: @{CLAUDE.md,**/*CLAUDE.md,*.config.*,package.json,webpack.*,vite.*} +``` + +For detailed syntax, patterns, and advanced usage see: +**@~/.claude/workflows/codex-unified.md** \ No newline at end of file diff --git a/.claude/commands/codex/execute.md b/.claude/commands/codex/execute.md new file mode 100644 index 00000000..4a1b621d --- /dev/null +++ b/.claude/commands/codex/execute.md @@ -0,0 +1,223 @@ +--- +name: execute +description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference using Codex CLI +usage: /codex:execute +argument-hint: "implementation description or task-id" +examples: + - /codex:execute "implement user authentication system" + - /codex:execute "optimize React component performance" + - /codex:execute IMPL-001 + - /codex:execute "fix API performance issues" +allowed-tools: Bash(codex:*) +model: sonnet +--- + +# Codex Execute Command (/codex:execute) + +## Overview + +**⚡ YOLO-enabled execution**: Auto-approves all confirmations for streamlined implementation workflow. + +**Purpose**: Execute implementation tasks using intelligent context inference and Codex CLI with full permissions. + +**Core Guidelines**: @~/.claude/workflows/codex-unified.md + +⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. + +## 🚨 YOLO Permissions + +**All confirmations auto-approved by default:** +- ✅ File pattern inference confirmation +- ✅ Codex execution confirmation +- ✅ File modification confirmation +- ✅ Implementation summary generation + +## Execution Modes + +### 1. Description Mode +**Input**: Natural language description +```bash +/codex:execute "implement JWT authentication with middleware" +``` +**Process**: Keyword analysis → Pattern inference → Context collection → Execution + +### 2. Task ID Mode +**Input**: Workflow task identifier +```bash +/codex:execute IMPL-001 +``` +**Process**: Task JSON parsing → Scope analysis → Context integration → Execution + +### 3. Full Auto Mode +**Input**: Complex development tasks +```bash +/codex:execute "create complete todo application with React and TypeScript" +``` +**Process**: Uses `codex --full-auto` for autonomous implementation + +## Context Inference Logic + +**Auto-selects relevant files based on:** +- **Keywords**: "auth" → `@{**/*auth*,**/*user*}` +- **Technology**: "React" → `@{src/**/*.{jsx,tsx}}` +- **Task Type**: "api" → `@{**/api/**/*,**/routes/**/*}` +- **Always includes**: `@{CLAUDE.md,**/*CLAUDE.md}` + +## Essential Codex Patterns + +**Required File Patterns** (No --all-files available): +```bash +@{**/*} # All files recursively (equivalent to --all-files) +@{src/**/*} # All source files +@{*.ts,*.js} # Specific file types +@{CLAUDE.md,**/*CLAUDE.md} # Documentation hierarchy +@{package.json,*.config.*} # Configuration files +``` + +## Command Options + +| Option | Purpose | +|--------|---------| +| `--debug` | Verbose execution logging | +| `--save-session` | Save complete execution session to workflow | +| `--full-auto` | Enable autonomous development mode | + +## Workflow Integration + +### Session Management +⚠️ **Auto-detects active session**: Checks `.workflow/.active-*` marker file + +**Session storage:** +- **Active session exists**: Saves to `.workflow/WFS-[topic]/.chat/execute-[timestamp].md` +- **No active session**: Creates new session directory + +### Task Integration +```bash +# Execute specific workflow task +/codex:execute IMPL-001 + +# Loads from: .task/impl-001.json +# Uses: task context, brainstorming refs, scope definitions +# Updates: workflow status, generates summary +``` + +## Execution Templates + +### User Description Template +```bash +codex exec "@{inferred_patterns} @{CLAUDE.md,**/*CLAUDE.md} + +Implementation Task: [user_description] + +Provide: +- Specific implementation code +- File modification locations (file:line) +- Test cases +- Integration guidance" +``` + +### Task ID Template +```bash +codex exec "@{task_files} @{brainstorming_refs} @{CLAUDE.md,**/*CLAUDE.md} + +Task: [task_title] (ID: [task-id]) +Type: [task_type] +Scope: [task_scope] + +Execute implementation following task acceptance criteria." +``` + +### Full Auto Template +```bash +codex --full-auto "@{**/*} @{CLAUDE.md,**/*CLAUDE.md} + +Development Task: [user_description] + +Autonomous implementation with: +- Architecture decisions +- Code generation +- Testing +- Documentation" +``` + +## Auto-Generated Outputs + +### 1. Implementation Summary +**Location**: `.summaries/[TASK-ID]-summary.md` or auto-generated ID + +```markdown +# Task Summary: [Task-ID] [Description] + +## Implementation +- **Files Modified**: [file:line references] +- **Features Added**: [specific functionality] +- **Context Used**: [inferred patterns] + +## Integration +- [Links to workflow documents] +``` + +### 2. Execution Session +**Location**: `.chat/execute-[timestamp].md` + +```markdown +# Execution Session: [Timestamp] + +## Input +[User description or Task ID] + +## Context Inference +[File patterns used with rationale] + +## Implementation Results +[Generated code and modifications] + +## Status Updates +[Workflow integration updates] +``` + +## Development Templates Used + +Based on task type, automatically selects: +- **Feature Development**: `~/.claude/workflows/cli-templates/prompts/development/feature.txt` +- **Component Creation**: `~/.claude/workflows/cli-templates/prompts/development/component.txt` +- **Code Refactoring**: `~/.claude/workflows/cli-templates/prompts/development/refactor.txt` +- **Bug Fixing**: `~/.claude/workflows/cli-templates/prompts/development/debugging.txt` +- **Test Generation**: `~/.claude/workflows/cli-templates/prompts/development/testing.txt` + +## Error Handling + +- **Task ID not found**: Lists available tasks +- **Pattern inference failure**: Uses generic `@{src/**/*}` pattern +- **Execution failure**: Attempts fallback with simplified context +- **File modification errors**: Reports specific file/permission issues +- **Missing @ patterns**: Auto-adds `@{**/*}` for comprehensive context + +## Performance Features + +- **Smart caching**: Frequently used pattern mappings +- **Progressive inference**: Precise → broad pattern fallback +- **Parallel execution**: When multiple contexts needed +- **Directory optimization**: Uses `--cd` flag when beneficial + +## Integration Workflow + +**Typical sequence:** +1. `workflow:plan` → Creates tasks +2. `/codex:execute IMPL-001` → Executes with YOLO permissions +3. Auto-updates workflow status and generates summaries +4. `workflow:review` → Final validation + +**vs. `/codex:analyze`**: Execute performs analysis **and implementation**, analyze is read-only. + +## Codex vs Gemini Execution + +| Feature | Codex | Gemini | +|---------|-------|--------| +| File Loading | `@` patterns **required** | `--all-files` available | +| Automation Level | Full autonomous with `--full-auto` | Manual implementation | +| Command Structure | `codex exec "@{patterns}"` | `gemini --all-files -p` | +| Development Focus | Code generation & implementation | Analysis & planning | + +For detailed patterns, syntax, and templates see: +**@~/.claude/workflows/codex-unified.md** \ No newline at end of file diff --git a/.claude/commands/codex/mode/auto.md b/.claude/commands/codex/mode/auto.md new file mode 100644 index 00000000..f806f5ba --- /dev/null +++ b/.claude/commands/codex/mode/auto.md @@ -0,0 +1,285 @@ +--- +name: auto +description: Full autonomous development mode with intelligent template selection and execution +usage: /codex:mode:auto "description of development task" +argument-hint: "description of what you want to develop or implement" +examples: + - /codex:mode:auto "create user authentication system with JWT" + - /codex:mode:auto "build real-time chat application with React" + - /codex:mode:auto "implement payment processing with Stripe integration" + - /codex:mode:auto "develop REST API with user management features" +allowed-tools: Bash(ls:*), Bash(codex:*) +model: sonnet +--- + +# Full Auto Development Mode (/codex:mode:auto) + +## Overview +Leverages Codex's `--full-auto` mode for autonomous development with intelligent template selection and comprehensive context gathering. + +**Process**: Analyze Input → Select Templates → Gather Context → Execute Autonomous Development + +⚠️ **Critical Feature**: Uses `codex --full-auto` for maximum autonomous capability with mandatory `@` pattern requirements. + +## Usage + +### Autonomous Development Examples +```bash +# Complete application development +/codex:mode:auto "create todo application with React and TypeScript" + +# Feature implementation +/codex:mode:auto "implement user authentication with JWT and refresh tokens" + +# System integration +/codex:mode:auto "add payment processing with Stripe to existing e-commerce system" + +# Architecture implementation +/codex:mode:auto "build microservices API with user management and notification system" +``` + +## Template Selection Logic + +### Dynamic Template Discovery +**Templates auto-discovered from**: `~/.claude/workflows/cli-templates/prompts/` + +Templates are dynamically read from development-focused directories: +- `development/` - Feature implementation, component creation, refactoring +- `automation/` - Project scaffolding, migration, deployment +- `analysis/` - Architecture analysis, pattern detection +- `integration/` - API design, database operations + +### Template Metadata Parsing + +Each template contains YAML frontmatter with: +```yaml +--- +name: template-name +description: Template purpose description +category: development|automation|analysis|integration +keywords: [keyword1, keyword2, keyword3] +development_type: feature|component|refactor|debug|testing +--- +``` + +**Auto-selection based on:** +- **Development keywords**: Matches user input against development-specific keywords +- **Template type**: Direct matching for development types +- **Architecture patterns**: Semantic matching for system design +- **Technology stack**: Framework and library detection + +## Command Execution + +### Step 1: Template Discovery +```bash +# Dynamically discover development templates +cd ~/.claude/workflows/cli-templates/prompts && echo "Discovering development templates..." && for dir in development automation analysis integration; do if [ -d "$dir" ]; then echo "=== $dir templates ==="; for template_file in "$dir"/*.txt; do if [ -f "$template_file" ]; then echo "Template: $(basename "$template_file")"; head -10 "$template_file" 2>/dev/null | grep -E "^(name|description|keywords):" || echo "No metadata"; echo; fi; done; fi; done +``` + +### Step 2: Dynamic Template Analysis & Selection +```pseudo +FUNCTION select_development_template(user_input): + template_dirs = ["development", "automation", "analysis", "integration"] + template_metadata = {} + + # Parse all development templates for metadata + FOR each dir in template_dirs: + templates = list_files("~/.claude/workflows/cli-templates/prompts/" + dir + "/*.txt") + FOR each template_file in templates: + content = read_file(template_file) + yaml_front = extract_yaml_frontmatter(content) + template_metadata[template_file] = { + "name": yaml_front.name, + "description": yaml_front.description, + "keywords": yaml_front.keywords || [], + "category": yaml_front.category || dir, + "development_type": yaml_front.development_type || "general" + } + + input_lower = user_input.toLowerCase() + best_match = null + highest_score = 0 + + # Score each template against user input + FOR each template, metadata in template_metadata: + score = 0 + + # Development keyword matching (highest weight) + development_keywords = ["implement", "create", "build", "develop", "add", "generate"] + FOR each dev_keyword in development_keywords: + IF input_lower.contains(dev_keyword): + score += 5 + + # Template-specific keyword matching + FOR each keyword in metadata.keywords: + IF input_lower.contains(keyword.toLowerCase()): + score += 3 + + # Development type matching + IF input_lower.contains(metadata.development_type.toLowerCase()): + score += 4 + + # Technology stack detection + tech_keywords = ["react", "vue", "angular", "node", "express", "api", "database", "auth"] + FOR each tech in tech_keywords: + IF input_lower.contains(tech): + score += 2 + + IF score > highest_score: + highest_score = score + best_match = template + + # Default to feature.txt for development tasks + RETURN best_match || "development/feature.txt" +END FUNCTION +``` + +### Step 3: Execute with Full Auto Mode +```bash +# Autonomous development execution with comprehensive context +codex --full-auto "@{**/*} @{CLAUDE.md,**/*CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/[selected_template]) + +Development Task: [user_input] + +Autonomous Implementation Requirements: +- Complete feature development +- Code generation with best practices +- Automatic testing integration +- Documentation updates +- Error handling and validation" +``` + +## Essential Codex Auto Patterns + +**Required File Patterns** (Comprehensive context for autonomous development): +```bash +@{**/*} # All files for full context understanding +@{src/**/*} # Source code for pattern detection +@{package.json,*.config.*} # Configuration and dependencies +@{CLAUDE.md,**/*CLAUDE.md} # Project guidelines and standards +@{test/**/*,**/*.test.*} # Existing tests for pattern matching +@{docs/**/*,README.*} # Documentation for context +``` + +## Development Template Categories + +### Feature Development Templates +- **feature.txt**: Complete feature implementation with integration +- **component.txt**: Reusable component creation with props and state +- **refactor.txt**: Code improvement and optimization + +### Automation Templates +- **scaffold.txt**: Project structure and boilerplate generation +- **migration.txt**: System upgrades and data migrations +- **deployment.txt**: CI/CD and deployment automation + +### Analysis Templates (for context) +- **architecture.txt**: System structure understanding +- **pattern.txt**: Code pattern detection for consistency +- **security.txt**: Security analysis for safe development + +### Integration Templates +- **api-design.txt**: RESTful API development +- **database.txt**: Database schema and operations + +## Options + +| Option | Purpose | +|--------|---------| +| `--list-templates` | Show available development templates and exit | +| `--template ` | Force specific template (overrides auto-selection) | +| `--debug` | Show template selection reasoning and context patterns | +| `--save-session` | Save complete development session to workflow | +| `--no-auto` | Use `codex exec` instead of `--full-auto` mode | + +### Manual Template Override +```bash +# Force specific development template +/codex:mode:auto "user authentication" --template component.txt +/codex:mode:auto "fix login issues" --template debugging.txt +``` + +### Development Template Listing +```bash +# List all available development templates +/codex:mode:auto --list-templates +# Output: +# Development templates in ~/.claude/workflows/cli-templates/prompts/: +# - development/feature.txt (Complete feature implementation) [Keywords: implement, feature, integration] +# - development/component.txt (Reusable component creation) [Keywords: component, react, vue] +# - automation/scaffold.txt (Project structure generation) [Keywords: scaffold, setup, boilerplate] +# - [any-new-template].txt (Auto-discovered from any category) +``` + +## Auto-Selection Examples + +### Development Task Detection +```bash +# Feature development → development/feature.txt +"implement user dashboard with analytics charts" + +# Component creation → development/component.txt +"create reusable button component with multiple variants" + +# System architecture → automation/scaffold.txt +"build complete e-commerce platform with React and Node.js" + +# API development → integration/api-design.txt +"develop REST API for user management with authentication" + +# Performance optimization → development/refactor.txt +"optimize React application performance and bundle size" +``` + +## Autonomous Development Workflow + +### Full Context Gathering +1. **Project Analysis**: `@{**/*}` provides complete codebase context +2. **Pattern Detection**: Understands existing code patterns and conventions +3. **Dependency Analysis**: Reviews package.json and configuration files +4. **Test Pattern Recognition**: Follows existing test structures + +### Intelligent Implementation +1. **Architecture Decisions**: Makes informed choices based on existing patterns +2. **Code Generation**: Creates code matching project style and conventions +3. **Integration**: Ensures new code integrates seamlessly with existing system +4. **Quality Assurance**: Includes error handling, validation, and testing + +### Autonomous Features +- **Smart File Creation**: Creates necessary files and directories +- **Dependency Management**: Adds required packages automatically +- **Test Generation**: Creates comprehensive test suites +- **Documentation Updates**: Updates relevant documentation files +- **Configuration Updates**: Modifies config files as needed + +## Session Integration + +When `--save-session` used, saves to: +`.workflow/WFS-[topic]/.chat/auto-[template]-[timestamp].md` + +**Session includes:** +- Original development request +- Template selection reasoning +- Complete context patterns used +- Autonomous development results +- Files created/modified +- Integration guidance + +## Performance Features + +- **Parallel Context Loading**: Loads multiple file patterns simultaneously +- **Smart Caching**: Caches template selections for similar requests +- **Progressive Development**: Builds features incrementally with validation +- **Rollback Capability**: Can revert changes if issues detected + +## Codex vs Gemini Auto Mode + +| Feature | Codex Auto | Gemini Auto | +|---------|------------|-------------| +| Primary Purpose | Autonomous development | Analysis and planning | +| File Loading | `@{**/*}` required | `--all-files` available | +| Output | Complete implementations | Analysis and recommendations | +| Template Focus | Development-oriented | Analysis-oriented | +| Execution Mode | `--full-auto` autonomous | Interactive guidance | + +This command maximizes Codex's autonomous development capabilities while ensuring comprehensive context and intelligent template selection for optimal results. \ No newline at end of file diff --git a/.claude/commands/codex/mode/bug-index.md b/.claude/commands/codex/mode/bug-index.md new file mode 100644 index 00000000..77308c3d --- /dev/null +++ b/.claude/commands/codex/mode/bug-index.md @@ -0,0 +1,269 @@ +--- +name: bug-index +description: Bug analysis, debugging, and automated fix implementation using Codex +usage: /codex:mode:bug-index "bug description" +argument-hint: "description of the bug or error you're experiencing" +examples: + - /codex:mode:bug-index "authentication null pointer error in login flow" + - /codex:mode:bug-index "React component not re-rendering after state change" + - /codex:mode:bug-index "database connection timeout in production" + - /codex:mode:bug-index "API endpoints returning 500 errors randomly" +allowed-tools: Bash(codex:*) +model: sonnet +--- + +# Bug Analysis & Fix Command (/codex:mode:bug-index) + +## Overview +Systematic bug analysis, debugging, and automated fix implementation using expert diagnostic templates with Codex CLI. + +**Core Guidelines**: @~/.claude/workflows/codex-unified.md + +⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. + +**Enhancement over Gemini**: Codex can **analyze AND implement fixes**, not just provide recommendations. + +## Usage + +### Basic Bug Analysis & Fix +```bash +/codex:mode:bug-index "authentication error during login" +``` +**Executes**: `codex exec "@{**/*auth*,**/*login*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt)"` + +### Comprehensive Bug Investigation +```bash +/codex:mode:bug-index "React state not updating in dashboard" +``` +**Executes**: `codex exec "@{src/**/*.{jsx,tsx},**/*dashboard*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt)"` + +### Production Error Analysis +```bash +/codex:mode:bug-index "API timeout issues in production environment" +``` +**Executes**: `codex exec "@{**/api/**/*,*.config.*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt)"` + +## Codex-Specific Debugging Patterns + +**Essential File Patterns** (Required for effective debugging): +```bash +@{**/*error*,**/*bug*} # Error-related files +@{src/**/*} # Source code for bug analysis +@{**/logs/**/*} # Log files for error traces +@{test/**/*,**/*.test.*} # Tests to understand expected behavior +@{CLAUDE.md,**/*CLAUDE.md} # Project guidelines +@{*.config.*,package.json} # Configuration for environment issues +``` + +## Command Execution + +**Debugging Template Used**: `~/.claude/workflows/cli-templates/prompts/development/debugging.txt` + +**Executes**: +```bash +codex exec "@{inferred_bug_patterns} @{CLAUDE.md,**/*CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/debugging.txt) + +Context: Comprehensive codebase analysis for bug investigation +Bug Description: [user_description] +Fix Implementation: Provide working code solutions" +``` + +## Bug Pattern Inference + +**Auto-detects relevant files based on bug description:** + +| Bug Keywords | Inferred Patterns | Focus Area | +|-------------|------------------|------------| +| "auth", "login", "token" | `@{**/*auth*,**/*user*,**/*login*}` | Authentication code | +| "React", "component", "render" | `@{src/**/*.{jsx,tsx}}` | React components | +| "API", "endpoint", "server" | `@{**/api/**/*,**/routes/**/*}` | Backend code | +| "database", "db", "query" | `@{**/models/**/*,**/db/**/*}` | Database code | +| "timeout", "connection" | `@{*.config.*,**/*config*}` | Configuration issues | +| "test", "spec" | `@{test/**/*,**/*.test.*}` | Test-related bugs | +| "build", "compile" | `@{*.config.*,package.json,webpack.*}` | Build issues | +| "style", "css", "layout" | `@{**/*.{css,scss,sass}}` | Styling bugs | + +## Analysis & Fix Focus + +### Comprehensive Bug Analysis Provides: +- **Root Cause Analysis**: Systematic investigation with file:line references +- **Code Path Tracing**: Following execution flow through the codebase +- **Error Pattern Detection**: Identifying similar issues across the codebase +- **Context Understanding**: Leveraging existing code patterns +- **Impact Assessment**: Understanding potential side effects of fixes + +### Codex Enhancement - Automated Fixes: +- **Working Code Solutions**: Actual implementation fixes +- **Multiple Fix Options**: Different approaches with trade-offs +- **Test Case Generation**: Tests to prevent regression +- **Configuration Updates**: Environment and config fixes +- **Documentation Updates**: Updated comments and documentation + +## Debugging Templates & Approaches + +### Error Investigation +```bash +# Uses: debugging.txt template for systematic analysis +/codex:mode:bug-index "null pointer exception in user service" +# Provides: Stack trace analysis, variable state inspection, fix implementation +``` + +### Performance Bug Analysis +```bash +# Uses: debugging.txt + performance.txt combination +/codex:mode:bug-index "slow database queries causing timeout" +# Provides: Query optimization, indexing suggestions, connection pool fixes +``` + +### Integration Bug Fixes +```bash +# Uses: debugging.txt + integration/api-design.txt +/codex:mode:bug-index "third-party API integration failing randomly" +# Provides: Error handling, retry logic, fallback implementations +``` + +## Options + +| Option | Purpose | +|--------|---------| +| `--comprehensive` | Use `@{**/*}` for complete codebase analysis | +| `--save-session` | Save bug analysis and fixes to workflow session | +| `--implement-fix` | Auto-implement the recommended fix (default in Codex) | +| `--generate-tests` | Create tests to prevent regression | +| `--debug-mode` | Verbose debugging output with pattern explanations | + +### Comprehensive Debugging +```bash +/codex:mode:bug-index "intermittent authentication failures" --comprehensive +# Uses: @{**/*} for complete system analysis +``` + +### Bug Fix with Testing +```bash +/codex:mode:bug-index "user registration validation errors" --generate-tests +# Provides: Bug fix + comprehensive test suite +``` + +## Session Output + +When `--save-session` used, saves to: +`.workflow/WFS-[topic]/.chat/bug-index-[timestamp].md` + +**Session includes:** +- Bug description and symptoms +- File patterns used for analysis +- Root cause analysis with evidence +- Implemented fix with code changes +- Test cases to prevent regression +- Monitoring and prevention recommendations + +## Debugging Output Structure + +### Bug Analysis Template Output: +```markdown +# Bug Analysis: [Description] + +## Problem Investigation +- Symptoms and error messages +- Affected components and files +- Reproduction steps + +## Root Cause Analysis +- Code path analysis with file:line references +- Variable states and data flow +- Configuration and environment factors + +## Implemented Fixes +- Primary solution with code changes +- Alternative approaches considered +- Trade-offs and design decisions + +## Testing & Validation +- Test cases to verify fix +- Regression prevention tests +- Performance impact assessment + +## Monitoring & Prevention +- Error handling improvements +- Logging enhancements +- Code quality improvements +``` + +## Context-Aware Bug Fixing + +### Existing Pattern Integration +```bash +/codex:mode:bug-index "authentication middleware not working" +# Analyzes existing auth patterns in codebase +# Implements fix consistent with current architecture +# Updates related middleware to match patterns +``` + +### Technology Stack Compatibility +```bash +/codex:mode:bug-index "React hooks causing infinite renders" +# Reviews current React version and patterns +# Implements fix using appropriate hooks API +# Updates other components with similar issues +``` + +## Advanced Debugging Features + +### Multi-File Bug Tracking +```bash +/codex:mode:bug-index "user data inconsistency between frontend and backend" +# Analyzes both frontend and backend code +# Identifies data flow discrepancies +# Implements synchronized fixes across stack +``` + +### Production Issue Investigation +```bash +/codex:mode:bug-index "memory leak in production server" +# Reviews server code and configuration +# Analyzes log patterns and resource usage +# Implements monitoring and leak prevention +``` + +### Error Handling Enhancement +```bash +/codex:mode:bug-index "unhandled promise rejections causing crashes" +# Identifies all async operations without error handling +# Implements comprehensive error handling strategy +# Adds logging and monitoring for similar issues +``` + +## Bug Prevention Features + +- **Pattern Analysis**: Identifies similar bugs across codebase +- **Code Quality Improvements**: Suggests structural improvements +- **Error Handling Enhancement**: Adds robust error handling +- **Test Coverage**: Creates tests to prevent similar issues +- **Documentation Updates**: Improves code documentation + +## Codex vs Gemini Bug Analysis + +| Feature | Codex Bug-Index | Gemini Bug-Index | +|---------|-----------------|------------------| +| File Context | `@` patterns **required** | `--all-files` available | +| Output | Analysis + working fixes | Analysis + recommendations | +| Implementation | Automatic code changes | Manual implementation needed | +| Testing | Auto-generates test cases | Suggests testing approach | +| Integration | Updates related code | Focuses on specific bug | + +## Workflow Integration + +### Bug Fixing Workflow +```bash +# 1. Analyze and fix the bug +/codex:mode:bug-index "user login failing with token errors" + +# 2. Review the implemented changes +/workflow:review + +# 3. Execute any additional tasks identified +/codex:execute "implement additional error handling for edge cases" +``` + +For detailed syntax, patterns, and advanced usage see: +**@~/.claude/workflows/codex-unified.md** \ No newline at end of file diff --git a/.claude/commands/codex/mode/plan.md b/.claude/commands/codex/mode/plan.md new file mode 100644 index 00000000..a131cb6c --- /dev/null +++ b/.claude/commands/codex/mode/plan.md @@ -0,0 +1,261 @@ +--- +name: plan +description: Development planning and implementation strategy using specialized templates with Codex +usage: /codex:mode:plan "planning topic" +argument-hint: "development planning topic or implementation challenge" +examples: + - /codex:mode:plan "design user dashboard feature architecture" + - /codex:mode:plan "plan microservices migration with implementation" + - /codex:mode:plan "implement real-time notification system with React" +allowed-tools: Bash(codex:*) +model: sonnet +--- + +# Development Planning Command (/codex:mode:plan) + +## Overview +Comprehensive development planning and implementation strategy using expert planning templates with Codex CLI. + +**Core Guidelines**: @~/.claude/workflows/codex-unified.md + +⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files. + +## Usage + +### Basic Development Planning +```bash +/codex:mode:plan "design authentication system with implementation" +``` +**Executes**: `codex exec "@{**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt)"` + +### Architecture Planning with Context +```bash +/codex:mode:plan "microservices migration strategy" +``` +**Executes**: `codex exec "@{src/**/*,*.config.*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/planning/migration.txt)"` + +### Feature Implementation Planning +```bash +/codex:mode:plan "real-time notifications with WebSocket integration" +``` +**Executes**: `codex exec "@{**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) + +Additional Planning Context: +$(cat ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt)"` + +## Codex-Specific Planning Patterns + +**Essential File Patterns** (Required for comprehensive planning): +```bash +@{**/*} # All files for complete context +@{src/**/*} # Source code architecture +@{*.config.*,package.json} # Configuration and dependencies +@{CLAUDE.md,**/*CLAUDE.md} # Project guidelines +@{docs/**/*,README.*} # Documentation for context +@{test/**/*} # Testing patterns +``` + +## Command Execution + +**Planning Templates Used**: +- Primary: `~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt` +- Migration: `~/.claude/workflows/cli-templates/prompts/planning/migration.txt` +- Combined with development templates for implementation guidance + +**Executes**: +```bash +codex exec "@{**/*} @{CLAUDE.md,**/*CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt) + +Context: Complete codebase analysis for informed planning +Planning Topic: [user_description] +Implementation Focus: Development strategy with code generation guidance" +``` + +## Planning Focus Areas + +### Development Planning Provides: +- **Requirements Analysis**: Functional and technical requirements +- **Architecture Design**: System structure with implementation details +- **Implementation Strategy**: Step-by-step development approach with code examples +- **Technology Selection**: Framework and library recommendations +- **Task Decomposition**: Detailed task breakdown with dependencies +- **Code Structure Planning**: File organization and module design +- **Testing Strategy**: Test planning and coverage approach +- **Integration Planning**: API design and data flow + +### Codex Enhancement: +- **Implementation Guidance**: Actual code patterns and examples +- **Automated Scaffolding**: Template generation for planned components +- **Dependency Analysis**: Required packages and configurations +- **Pattern Detection**: Leverages existing codebase patterns + +## Planning Templates + +### Task Breakdown Planning +```bash +# Uses: planning/task-breakdown.txt +/codex:mode:plan "implement user authentication system" +# Provides: Detailed task list, dependencies, implementation order +``` + +### Migration Planning +```bash +# Uses: planning/migration.txt +/codex:mode:plan "migrate from REST to GraphQL API" +# Provides: Migration strategy, compatibility planning, rollout approach +``` + +### Feature Planning with Implementation +```bash +# Uses: development/feature.txt + planning/task-breakdown.txt +/codex:mode:plan "build real-time chat application" +# Provides: Architecture + implementation roadmap + code examples +``` + +## Options + +| Option | Purpose | +|--------|---------| +| `--comprehensive` | Use `@{**/*}` for complete codebase context | +| `--save-session` | Save planning analysis to workflow session | +| `--with-implementation` | Include code generation in planning | +| `--template ` | Force specific planning template | + +### Comprehensive Planning +```bash +/codex:mode:plan "design payment system architecture" --comprehensive +# Uses: @{**/*} pattern for maximum context +``` + +### Planning with Implementation +```bash +/codex:mode:plan "implement user dashboard" --with-implementation +# Combines planning templates with development templates for actionable output +``` + +## Session Output + +When `--save-session` used, saves to: +`.workflow/WFS-[topic]/.chat/plan-[timestamp].md` + +**Session includes:** +- Planning topic and requirements +- Template combination used +- Complete architecture analysis +- Implementation roadmap with tasks +- Code structure recommendations +- Technology stack decisions +- Integration strategies +- Next steps and action items + +## Planning Template Structure + +### Task Breakdown Template Output: +```markdown +# Development Plan: [Topic] + +## Requirements Analysis +- Functional requirements +- Technical requirements +- Constraints and dependencies + +## Architecture Design +- System components +- Data flow +- Integration points + +## Implementation Strategy +- Development phases +- Task breakdown +- Dependencies and blockers +- Estimated effort + +## Code Structure +- File organization +- Module design +- Component hierarchy + +## Technology Decisions +- Framework selection +- Library recommendations +- Configuration requirements + +## Testing Approach +- Testing strategy +- Coverage requirements +- Test automation + +## Action Items +- [ ] Detailed task list with priorities +- [ ] Implementation order +- [ ] Review checkpoints +``` + +## Context-Aware Planning + +### Existing Codebase Integration +```bash +/codex:mode:plan "add user roles and permissions system" +# Analyzes existing authentication patterns +# Plans integration with current user management +# Suggests compatible implementation approach +``` + +### Technology Stack Analysis +```bash +/codex:mode:plan "implement real-time features" +# Reviews current tech stack (React, Node.js, etc.) +# Recommends compatible WebSocket/SSE solutions +# Plans integration with existing architecture +``` + +## Planning Workflow Integration + +### Pre-Development Planning +1. **Architecture Analysis**: Understand current system structure +2. **Requirement Planning**: Define scope and objectives +3. **Implementation Strategy**: Create detailed development plan +4. **Task Creation**: Generate actionable tasks for execution + +### Planning to Execution Flow +```bash +# 1. Plan the implementation +/codex:mode:plan "implement user dashboard with analytics" + +# 2. Execute the plan +/codex:execute "implement user dashboard based on planning analysis" + +# 3. Review and iterate +/workflow:review +``` + +## Codex vs Gemini Planning + +| Feature | Codex Planning | Gemini Planning | +|---------|----------------|-----------------| +| File Context | `@` patterns **required** | `--all-files` available | +| Output Focus | Implementation-ready plans | Analysis and strategy | +| Code Examples | Includes actual code patterns | Conceptual guidance | +| Integration | Direct execution pathway | Planning only | +| Templates | Development + planning combined | Planning focused | + +## Advanced Planning Features + +### Multi-Phase Planning +```bash +/codex:mode:plan "modernize legacy application architecture" +# Provides: Phase-by-phase migration strategy +# Includes: Compatibility planning, risk assessment +# Generates: Implementation timeline with milestones +``` + +### Cross-System Integration Planning +```bash +/codex:mode:plan "integrate third-party payment system with existing e-commerce" +# Analyzes: Current system architecture +# Plans: Integration approach and data flow +# Recommends: Security and error handling strategies +``` + +For detailed syntax, patterns, and advanced usage see: +**@~/.claude/workflows/codex-unified.md** \ No newline at end of file diff --git a/.claude/commands/gemini/mode/CLAUDE.md b/.claude/commands/gemini/mode/CLAUDE.md deleted file mode 100644 index 280dd478..00000000 --- a/.claude/commands/gemini/mode/CLAUDE.md +++ /dev/null @@ -1,57 +0,0 @@ -# Module: Gemini Mode (`/gemini:mode:*`) - -## Overview - -The `mode` module provides specialized commands for executing the Gemini CLI with different analysis strategies. Each mode is tailored for a specific task, such as bug analysis, project planning, or automatic template selection based on user intent. - -These commands act as wrappers around the core `gemini` CLI, pre-configuring it with specific prompt templates and context settings. - -## Module-Specific Implementation Patterns - -### Command Definition Files - -Each command within the `mode` module is defined by a Markdown file (e.g., `auto.md`, `bug-index.md`). These files contain YAML frontmatter that specifies: -- `name`: The command name. -- `description`: A brief explanation of the command's purpose. -- `usage`: How to invoke the command. -- `argument-hint`: A hint for the user about the expected argument. -- `examples`: Sample usages. -- `allowed-tools`: Tools the command is permitted to use. -- `model`: The underlying model to be used. - -The body of the Markdown file provides detailed documentation for the command. - -### Template-Driven Execution - -The core pattern for this module is the use of pre-defined prompt templates stored in `~/.claude/prompt-templates/`. The commands construct a `gemini` CLI call, injecting the content of a specific template into the prompt. - -## Commands and Interfaces - -### `/gemini:mode:auto` -- **Purpose**: Automatically selects the most appropriate Gemini template by analyzing the user's input against keywords, names, and descriptions defined in the templates' YAML frontmatter. -- **Interface**: `/gemini:mode:auto "description of task"` -- **Dependencies**: Relies on the dynamic discovery of templates in `~/.claude/prompt-templates/`. - -### `/gemini:mode:bug-index` -- **Purpose**: Executes a systematic bug analysis using a dedicated diagnostic template. -- **Interface**: `/gemini:mode:bug-index "bug description"` -- **Dependencies**: Uses the `~/.claude/prompt-templates/bug-fix.md` template. - -### `/gemini:mode:plan` -- **Purpose**: Performs comprehensive project planning and architecture analysis using a specialized planning template. -- **Interface**: `/gemini:mode:plan "planning topic"` -- **Dependencies**: Uses the `~/.claude/prompt-templates/plan.md` template. - -## Dependencies and Relationships - -- **External Dependency**: The `mode` module is highly dependent on the prompt templates located in the `~/.claude/prompt-templates/` directory. The structure and metadata (YAML frontmatter) of these templates are critical for the `auto` mode's functionality. -- **Internal Relationship**: The commands within this module are independent of each other but share a common purpose of simplifying access to the `gemini` CLI for specific use cases. They do not call each other. -- **Core CLI**: All commands are wrappers that ultimately construct and execute a `gemini` shell command. - -## Testing Strategy - -- **Unit Testing**: Not directly applicable as these are command definition files. -- **Integration Testing**: Testing should focus on verifying that each command correctly constructs and executes the intended `gemini` CLI command. - - For `/gemini:mode:auto`, tests should cover the selection logic with various inputs to ensure the correct template is chosen. - - For `/gemini:mode:bug-index` and `/gemini:mode:plan`, tests should confirm that the correct, hardcoded template is used. -- **Manual Verification**: Manually running each command with its example arguments is the primary way to ensure they are functioning as documented. diff --git a/.claude/commands/workflow/brainstorm/CLAUDE.md b/.claude/commands/workflow/brainstorm/CLAUDE.md deleted file mode 100644 index 169472ca..00000000 --- a/.claude/commands/workflow/brainstorm/CLAUDE.md +++ /dev/null @@ -1,75 +0,0 @@ -# Module Analysis: `workflow:brainstorm` - -## 1. Module-specific Implementation Patterns - -### Role-Based Command Structure -The `brainstorm` workflow is composed of multiple, distinct "role" commands. Each role is defined in its own Markdown file (e.g., `product-manager.md`, `system-architect.md`). This modular design allows for easy extension by adding new role files. - -- **Command Naming Convention**: Each role is invoked via a consistent command structure: `/workflow:brainstorm: `. -- **File Naming Convention**: The command's `` corresponds directly to the filename (e.g., `product-manager.md` implements `/workflow:brainstorm:product-manager`). - -### Standardized Role Definition Structure -Each role's `.md` file follows a strict, standardized structure: -1. **Frontmatter**: Defines the command `name`, `description`, `usage`, `argument-hint`, `examples`, and `allowed-tools`. All roles consistently use `Task(conceptual-planning-agent)` and `TodoWrite(*)`. -2. **Role Overview**: Defines the role's purpose, responsibilities, and success metrics. -3. **Analysis Framework**: References shared principles (`brainstorming-principles.md`, `brainstorming-framework.md`) and lists key questions specific to the role's perspective. -4. **Execution Protocol**: A multi-phase process detailing session detection, directory creation, task initialization (`TodoWrite`), and delegation to the `conceptual-planning-agent`. -5. **Output Specification**: Defines the directory structure and file templates for the analysis artifacts generated by the role. -6. **Session Integration**: Specifies how the role's output integrates with the parent session state (`workflow-session.json`). -7. **Quality Assurance**: Provides checklists and standards for validating the quality of the role's output. - -## 2. Internal Architecture and Design Decisions - -### Session-Based Workflow -The entire workflow is stateful and session-based, managed within the `.workflow/` directory. -- **State Management**: An active session is marked by a `.workflow/.active-*` file. -- **Output Scaffolding**: Each role command creates a dedicated output directory: `.workflow/WFS-{topic-slug}/.brainstorming//`. This isolates each perspective's artifacts. - -### "Map-Reduce" Architectural Pattern -The workflow follows a pattern analogous to Map-Reduce: -- **Map Phase**: Each individual role command (`product-manager`, `ui-designer`, etc.) acts as a "mapper". It takes the input `{topic}` and produces a detailed analysis from its unique perspective. -- **Reduce Phase**: The `synthesis` command acts as the "reducer". It collects the outputs from all completed roles, integrates them, identifies consensus and conflicts, and produces a single, comprehensive strategic report. - -### Delegation to `conceptual-planning-agent` -The core analytical work is not performed by the commands themselves. Instead, they act as templating engines that construct a detailed prompt for the `conceptual-planning-agent`. This design decision centralizes the complex reasoning and generation logic into a single, powerful tool, while the Markdown files serve as declarative "configurations" for that tool. - -## 3. API Contracts and Interfaces - -### Command-Line Interface (CLI) -The primary user-facing interface is the set of CLI commands: -- **Role Commands**: `/workflow:brainstorm: ` -- **Synthesis Command**: `/workflow:brainstorm:synthesis` (no arguments) - -### `conceptual-planning-agent` Contract -The interface with the planning agent is a structured prompt passed to the `Task()` tool. This prompt consistently contains: -- `ASSIGNED_ROLE` / `ROLE CONTEXT`: Defines the persona for the agent. -- `USER_CONTEXT`: Injects user requirements from the session. -- `ANALYSIS_REQUIREMENTS`: A detailed, numbered list of tasks for the agent to perform. -- `OUTPUT REQUIREMENTS`: Specifies the exact file paths and high-level content structure for the generated artifacts. - -### Filesystem Contract -The workflow relies on a strict filesystem structure for state and outputs: -- **Session State**: `.workflow/WFS-{topic-slug}/workflow-session.json` is updated by each role to track progress. -- **Role Outputs**: Each role must produce a set of `.md` files in its designated directory (e.g., `analysis.md`, `roadmap.md`). -- **Synthesis Input**: The `synthesis` command expects to find these specific output files to perform its function. - -## 4. Module Dependencies and Relationships - -- **Internal Dependencies**: - - The `synthesis` command is dependent on the outputs of all other role commands. It cannot function until one or more roles have completed their analysis. - - Individual role commands are largely independent of one another. - -- **External Dependencies**: - - **`conceptual-planning-agent`**: All roles have a critical dependency on this tool for their core logic. - - **Shared Frameworks**: All roles include and depend on `@~/.claude/workflows/brainstorming-principles.md` and `@~/.claude/workflows/brainstorming-framework.md`, ensuring a consistent analytical foundation. - -## 5. Testing Strategies - -This module does not contain automated tests. Validation relies on a set of quality assurance standards defined within each role's Markdown file. - -- **Checklist-Based Validation**: Each file contains a "Quality Assurance" or "Quality Standards" section with checklists for: - - **Required Analysis Elements**: Ensures all necessary components are present in the output. - - **Core Principles**: Validates that the analysis adheres to the role's guiding principles (e.g., "User-Centric", "Data-Driven"). - - **Quality Metrics**: Provides criteria for assessing the quality of the output (e.g., "Requirements completeness", "Feasibility of implementation plan"). - -This approach serves as a form of manual, requirement-based testing for the output generated by the `conceptual-planning-agent`. diff --git a/.claude/workflows/codex-unified.md b/.claude/workflows/codex-unified.md index 6a4ca615..ca9be3f2 100644 --- a/.claude/workflows/codex-unified.md +++ b/.claude/workflows/codex-unified.md @@ -113,6 +113,18 @@ Templates are shared between gemini and codex. This structure must be located at ### 📦 Standard Command Structures +- **Module-Specific Development (Folder Analysis Required)** + ```bash + # MUST use @{folder/**/*} pattern since codex has no --all-files + codex exec "@{src/auth/**/*,CLAUDE.md} Refactor authentication module using latest patterns" + + # Alternative: use --cd flag to navigate + include folder + codex --cd src/auth exec "@{**/*,../../CLAUDE.md} Implement JWT refresh token functionality" + + # For comprehensive module analysis + codex exec "@{backend/services/**/*,package.json,CLAUDE.md} Optimize service layer performance" + ``` + - **Basic Development Task** ```bash codex exec "@{src/**/*,*.json,CLAUDE.md} Implement user authentication with JWT" diff --git a/.claude/workflows/gemini-unified.md b/.claude/workflows/gemini-unified.md index a3b5f5b7..11f498c5 100644 --- a/.claude/workflows/gemini-unified.md +++ b/.claude/workflows/gemini-unified.md @@ -108,6 +108,18 @@ Templates are shared between gemini and codex. This structure can be located at These are recommended command templates for common scenarios. +- **Module-Specific Analysis (Quick Module Analysis)** + ```bash + # Navigate to module directory for focused analysis + cd src/auth && gemini --all-files -p "Analyze authentication module patterns and implementation" + + # Or specify module from root directory + cd backend/services && gemini --all-files -p "Review service architecture and dependencies" + + # Template-enhanced module analysis + cd frontend/components && gemini --all-files -p "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)" + ``` + - **Basic Structure (Manual Prompt)** ```bash gemini --all-files -p "@{target_patterns} @{CLAUDE.md,**/*CLAUDE.md} diff --git a/README.md b/README.md index 376c311f..5cae4e01 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ A sophisticated multi-agent automation workflow framework that transforms complex software development tasks from conceptualization to implementation review into manageable, trackable, AI-orchestrated processes. -> **🎉 v1.0 Release**: Complete Gemini CLI integration with template system, dynamic template discovery, streamlined documentation, and intelligent auto-selection capabilities. See [CHANGELOG.md](CHANGELOG.md) for details. +> **🎉 v1.1 Release**: Unified CLI architecture with both Gemini (analysis) and Codex (development) integration, shared template system, comprehensive workflow documentation, and autonomous development capabilities. See [CHANGELOG.md](CHANGELOG.md) for details. ## 🏗️ Architecture Overview @@ -41,11 +41,12 @@ CCW intelligently adapts its file structure and workflow processes based on unif - **Code Review Agent**: Reviews code quality and compliance - **Memory Gemini Bridge**: Intelligent CLAUDE.md documentation system with context-aware updates -### Gemini CLI Integration (v1.0) -- **Dynamic Template Discovery**: Automatically detects and loads templates from `~/.claude/prompt-templates/` +### Unified CLI Integration (v1.1) +- **Gemini & Codex Unified**: Comprehensive CLI integration with both analysis (`gemini`) and development (`codex`) workflows +- **Dynamic Template Discovery**: Automatically detects and loads templates from `~/.claude/workflows/cli-templates/` - **Intelligent Auto-Selection**: Matches user input against template keywords and descriptions -- **Template System**: Bug-fix, planning, and custom analysis templates -- **Streamlined Commands**: Consolidated documentation with 500+ lines reduced +- **Template System**: Analysis, development, planning, and specialized templates +- **Streamlined Commands**: Unified documentation architecture with shared templates ### Workflow Session Management - Create, pause, resume, list, and switch workflow sessions @@ -120,6 +121,11 @@ For Gemini CLI integration, configure your `settings.json` file: ## 📚 Complete Command Reference +### CLI Tool Guidelines +- **Gemini Commands**: For analysis, investigation, and understanding codebase patterns +- **Codex Commands**: For autonomous development, code generation, and implementation +- **Unified Templates**: Shared template system at `~/.claude/workflows/cli-templates/` + ### Core Commands | Command | Syntax | Description | @@ -128,9 +134,11 @@ For Gemini CLI integration, configure your `settings.json` file: | `/gemini:analyze` | `/gemini:analyze [--all-files] [--save-session]` | Direct codebase analysis and investigation | | `/gemini:chat` | `/gemini:chat [--all-files] [--save-session]` | Simple direct interaction with Gemini CLI without templates | | `/gemini:execute` | `/gemini:execute [--yolo] [--debug]` | Intelligent executor with automatic file context inference | -| `/gemini:mode:auto` | `/gemini:mode:auto ""` | 🆕 Auto-select and execute appropriate template based on user input analysis | +| `/gemini:mode:auto` | `/gemini:mode:auto ""` | Auto-select and execute appropriate template based on user input analysis | | `/gemini:mode:bug-index` | `/gemini:mode:bug-index ` | Bug analysis using specialized diagnostic template | | `/gemini:mode:plan` | `/gemini:mode:plan ` | Project planning using specialized architecture template | +| `/codex:exec` | `/codex:exec "@{patterns} prompt"` | 🆕 Autonomous development with explicit file pattern references | +| `/codex:--full-auto` | `/codex --full-auto "task description"` | 🆕 Full automation mode for complex development workflows | | `/update-memory` | `/update-memory [related\|full]` | Intelligent CLAUDE.md documentation system with context-aware updates | | `/update-memory-full` | `/update-memory-full` | 🆕 Complete project-wide CLAUDE.md documentation update with depth-parallel execution | | `/update-memory-related` | `/update-memory-related` | 🆕 Context-aware documentation updates for modules affected by recent changes | @@ -258,24 +266,26 @@ git commit -m "Major refactoring" | **Medium** | 5-15 tasks | 2 levels (impl-N.M) | Enhanced + auto-generated TODO_LIST.md | Optional brainstorming → Action plan → Progress tracking | | **Complex** | >15 tasks | 3 levels (impl-N.M.P) | Complete document suite | Required brainstorming → Multi-agent orchestration → Deep context analysis | -### 🚀 v1.0 Release Benefits -- **Smart Automation**: Intelligent template selection reduces manual template discovery -- **Documentation**: 500+ lines streamlined while maintaining functionality -- **Template System**: Dynamic discovery and YAML-based metadata parsing +### 🚀 v1.1 Release Benefits +- **Unified CLI Architecture**: Seamless integration of analysis (`gemini`) and development (`codex`) workflows +- **Smart Automation**: Intelligent template selection with autonomous development capabilities +- **Shared Template System**: Unified template library with cross-tool compatibility +- **Enhanced Documentation**: Comprehensive workflow guides with best practices - **Cross-Platform**: Unified path handling for Windows/Linux compatibility -- **Developer Experience**: Simplified commands with powerful auto-selection +- **Developer Experience**: Powerful automation with human oversight control ## 🔧 Technical Highlights +- **Dual CLI Integration**: Seamless `gemini` (analysis) and `codex` (development) workflow coordination - **Intelligent Context Processing**: Dynamic context construction with technology stack detection -- **Template-Driven Architecture**: Highly customizable and extensible through templates +- **Template-Driven Architecture**: Highly customizable and extensible through unified shared templates - **Quality Assurance Integration**: Built-in code review and testing strategy phases - **Intelligent Documentation System**: 4-layer hierarchical CLAUDE.md system with: - **Dual-mode Operations**: `related` (git-aware change detection) and `full` (complete project scan) - **Complexity-adaptive Execution**: Auto-delegation to memory-gemini-bridge for complex projects (>15/20 modules) - **Depth-parallel Processing**: Bottom-up execution ensuring child context availability for parent updates - **Git Integration**: Smart change detection with fallback strategies and comprehensive status reporting -- **CLI-First Design**: Powerful, orthogonal command-line interface for automation +- **CLI-First Design**: Powerful, orthogonal command-line interface for automation and autonomous development ## 🎨 Design Philosophy diff --git a/README_CN.md b/README_CN.md index b21ba72a..10e2364f 100644 --- a/README_CN.md +++ b/README_CN.md @@ -8,7 +8,7 @@ 一个精密的多智能体自动化工作流框架,将复杂的软件开发任务从概念构思到实现审查转化为可管理、可追踪、AI协调的流程。 -> **🎉 v1.0 版本发布**:完整的 Gemini CLI 集成,包含模板系统、动态模板发现、精简文档和智能自动选择功能。详见 [CHANGELOG.md](CHANGELOG.md)。 +> **🎉 v1.1 版本发布**:统一的 CLI 架构,集成 Gemini(分析)和 Codex(开发),共享模板系统,全面的工作流文档和自主开发能力。详见 [CHANGELOG.md](CHANGELOG.md)。 ## 🏗️ 架构概览 @@ -41,12 +41,12 @@ CCW 根据统一的任务数量阈值智能调整其文件结构和工作流程 - **代码审查智能体**:审查代码质量和合规性 - **记忆桥接智能体**:智能 CLAUDE.md 文档系统,提供上下文感知更新 -### Gemini CLI 集成 (v1.0) -- **动态模板发现**:自动检测和加载来自 `~/.claude/prompt-templates/` 的模板 +### 统一 CLI 集成 (v1.1) +- **Gemini & Codex 统一**:全面的 CLI 集成,支持分析(`gemini`)和开发(`codex`)工作流 +- **动态模板发现**:自动检测和加载来自 `~/.claude/workflows/cli-templates/` 的模板 - **智能自动选择**:根据模板关键词和描述匹配用户输入 -- **模板系统**:Bug修复、规划和自定义分析模板 -- **精简命令**:整合文档,减少500+行代码 -- **准确命令结构**:统一的 `/gemini:mode:*` 和 `/workflow:*` 命令模式 +- **模板系统**:分析、开发、规划和专用模板 +- **统一命令架构**:统一的文档架构,共享模板系统 ### 工作流会话管理 - 创建、暂停、恢复、列出和切换工作流会话 @@ -121,6 +121,11 @@ Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/cat ## 📚 完整命令参考 +### CLI 工具指南 +- **Gemini 命令**:用于分析、调查和理解代码库模式 +- **Codex 命令**:用于自主开发、代码生成和实现 +- **统一模板**:共享模板系统位于 `~/.claude/workflows/cli-templates/` + ### 核心命令 | 命令 | 语法 | 描述 | @@ -129,9 +134,11 @@ Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/cat | `/gemini:chat` | `/gemini:chat <查询> [--all-files] [--save-session]` | 与 Gemini CLI 的简单直接交互,不使用模板 | | `/gemini:analyze` | `/gemini:analyze <查询> [--all-files] [--save-session]` | 直接代码库分析和调查 | | `/gemini:execute` | `/gemini:execute <任务ID\|描述> [--yolo] [--debug]` | 智能执行器,自动推断文件上下文 | -| `/gemini:mode:auto` | `/gemini:mode:auto "<描述>"` | 🆕 基于用户输入分析自动选择和执行合适的模板 | +| `/gemini:mode:auto` | `/gemini:mode:auto "<描述>"` | 基于用户输入分析自动选择和执行合适的模板 | | `/gemini:mode:bug-index` | `/gemini:mode:bug-index <错误描述>` | 使用专门的诊断模板进行错误分析 | | `/gemini:mode:plan` | `/gemini:mode:plan <规划主题>` | 使用专门的架构模板进行项目规划 | +| `/codex:exec` | `/codex:exec "@{patterns} prompt"` | 🆕 带显式文件模式引用的自主开发 | +| `/codex:--full-auto` | `/codex --full-auto "任务描述"` | 🆕 复杂开发工作流的全自动化模式 | | `/update-memory` | `/update-memory [related\|full]` | 智能 CLAUDE.md 文档系统,提供上下文感知更新 | | `/update-memory-full` | `/update-memory-full` | 🆕 完整的项目级 CLAUDE.md 文档更新,采用深度并行执行 | | `/update-memory-related` | `/update-memory-related` | 🆕 基于近期变更的上下文感知文档更新 | @@ -257,24 +264,26 @@ git commit -m "重大重构" | **中等** | 5-15个任务 | 2级 (impl-N.M) | 增强 + 自动生成TODO_LIST.md | 可选头脑风暴 → 行动计划 → 进度跟踪 | | **复杂** | >15个任务 | 3级 (impl-N.M.P) | 完整文档套件 | 必需头脑风暴 → 多智能体编排 → 深度上下文分析 | -### 🚀 架构 v2.0 优势 -- **性能提升**:标记文件系统带来95%更快的会话操作 -- **一致性保证**:JSON纯模型提供100%数据一致性 -- **效率提升**:维护开销减少40-50% -- **可扩展性**:支持数百个并发会话 -- **学习曲线**:渐进式复杂度使学习时间缩短50% +### 🚀 v1.1 版本优势 +- **统一 CLI 架构**:分析(`gemini`)和开发(`codex`)工作流的无缝集成 +- **智能自动化**:具备自主开发能力的智能模板选择 +- **共享模板系统**:统一的模板库,支持跨工具兼容性 +- **增强文档**:包含最佳实践的全面工作流指南 +- **跨平台支持**:统一的 Windows/Linux 路径处理 +- **开发体验**:强大的自动化与人工监督控制 ## 🔧 技术亮点 +- **双 CLI 集成**:无缝的 `gemini`(分析)和 `codex`(开发)工作流协调 - **智能上下文处理**:基于技术栈检测的动态上下文构建 -- **模板驱动架构**:通过模板实现高度可定制和可扩展性 +- **模板驱动架构**:通过统一共享模板实现高度可定制和可扩展性 - **质量保证集成**:内置代码审查和测试策略阶段 - **智能文档系统**:4层分层 CLAUDE.md 系统,具有: - **双模式操作**:`related`(git感知变更检测)和 `full`(完整项目扫描) - **复杂度自适应执行**:复杂项目(>15/20个模块)自动委托给 memory-gemini-bridge - **深度并行处理**:自下而上执行,确保子上下文可用于父级更新 - **Git集成**:智能变更检测,带回退策略和综合状态报告 -- **CLI 优先设计**:强大、正交的命令行界面,便于自动化 +- **CLI 优先设计**:强大、正交的命令行界面,支持自动化和自主开发 ## 🎨 设计理念