feat: Update documentation to reflect v1.1 unified CLI architecture

- Update README.md and README_CN.md to v1.1 with unified Gemini/Codex CLI integration - Add comprehensive Codex command documentation with autonomous development capabilities - Enhance CLI tool guidelines with shared template system architecture - Consolidate documentation structure removing outdated CLAUDE.md files - Reflect current project state with dual CLI workflow coordination 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-11 02:33:51 +08:00 · 2025-09-10 22:20:05 +08:00
parent a944e31962
commit 7bbf835b04
12 changed files with 1453 additions and 160 deletions
--- a/.claude/commands/codex/mode/auto.md
+++ 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 <name>` | 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.
--- a/.claude/commands/codex/mode/bug-index.md
+++ 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**
--- a/.claude/commands/codex/mode/plan.md
+++ 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 <name>` | 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**