---
name: Codex Development Tool
description: Autonomous development tool for implementation. Trigger keywords "use codex", "codex implement", "implement with codex". Use for feature implementation, bug fixes, testing, and automation. Requires explicit MODE specification (auto/write). Supports session management for multi-task workflows.
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---

# Codex Development Tool

## Core Execution

Codex executes autonomous development tasks with full file operations and session management.

**Trigger Keywords**: "use codex", "codex implement", "implement with codex", "codex fix bug"

**Execution Modes**:
- `auto`: Autonomous development with full file operations (requires explicit specification)
- `write`: Test generation and file modification (requires explicit specification)

**Command Pattern**:
```bash
codex -C [directory] --full-auto exec "
PURPOSE: [goal]
TASK: [specific task]
MODE: [auto|write]
CONTEXT: @{file/patterns}
EXPECTED: [deliverables]
RULES: [constraints]
" --skip-git-repo-check -s danger-full-access
```

**No Default Mode**: MODE must be explicitly specified in every command

## Universal Template Structure

Every Codex command should follow this detailed structure for best results:

```bash
codex -C [directory] --full-auto exec "
PURPOSE: [One clear sentence: what and why]
TASK: [Specific actionable task with deliverables]
MODE: [auto|write]
CONTEXT: @{file/patterns} [Previous session context, dependencies, requirements]
EXPECTED: [Concrete deliverables: files, tests, coverage, performance]
RULES: [Template reference] | [Constraints: standards, compatibility, testing]
" --skip-git-repo-check -s danger-full-access
```

**Session Resume Pattern**:
```bash
# First task: establish session
codex -C [directory] --full-auto exec "..." --skip-git-repo-check -s danger-full-access

# Subsequent tasks: continue session (add "resume --last" at END)
codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
```

### Template Field Guidelines

**PURPOSE**:
- One sentence combining goal + business driver
- Examples: "Implement auth system for enterprise SaaS", "Fix performance issue to meet SLA <200ms"

**TASK**:
- Break down into numbered sub-tasks with specific deliverables
- Include technical details: "Create JWT auth with RS256, 15min access token, 7d refresh token"
- Specify what to build, test, and document

**CONTEXT**:
- File patterns: `@{src/models/**/*.ts,src/services/**/*.ts}`
- Tech stack: "Express 4.18, PostgreSQL 14, Redis 7, TypeScript strict mode"
- Requirements: "Support 100k users, comply with OWASP guidelines"
- Session memory: "Previous auth implementation from current session"

**EXPECTED**:
- Numbered, concrete deliverables: "1) auth.service.ts, 2) auth.controller.ts, 3) auth.test.ts (>90% coverage)"
- Specific file names with purposes
- Test coverage requirements: ">90% coverage including security scenarios"
- Performance targets: "p95 <200ms", "Support 1000 req/min"
- Documentation requirements: "Update API.md with endpoints"

**RULES**:
- Template reference: `$(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)`
- Multiple constraints separated by `|`: "Follow OWASP | Use bcrypt salt 12 | Rate limit 5/15min | Include audit logs"
- Compatibility: "Maintain backward compatibility", "Ensure zero downtime"
- Testing strategy: "Test all error cases", "Mock external dependencies", "Load test with Artillery"
- Security requirements: "Validate all inputs", "Parameterized queries only", "Log security events"

## Command Structure

### Universal Template
Every Codex command follows this structure:

```bash
codex -C [directory] --full-auto exec "
PURPOSE: [clear development goal]
TASK: [specific development task]
MODE: [auto|write]
CONTEXT: [file references and memory context]
EXPECTED: [expected deliverables]
RULES: [template reference and constraints]
" --skip-git-repo-check -s danger-full-access
```

**Parameter Position**: `--skip-git-repo-check -s danger-full-access` must be placed at command END

## Execution Modes

### Auto Mode (Full Development)
⚠️ Autonomous development with full file operations (requires explicit MODE=auto):

```bash
codex -C [directory] --full-auto exec "
PURPOSE: [development goal]
TASK: [implementation task]
MODE: auto
CONTEXT: @{file/patterns} [session memory]
EXPECTED: [deliverables]
RULES: [constraints]
" --skip-git-repo-check -s danger-full-access
```

**When to use**:
- Feature implementation
- Bug fixes requiring code changes
- Refactoring tasks
- Complex algorithm implementation

### Write Mode (Test Generation)
⚠️ Test generation and file modification (requires explicit MODE=write):

```bash
codex -C [directory] --full-auto exec "
PURPOSE: [test goal]
TASK: [test generation task]
MODE: write
CONTEXT: @{file/patterns}
EXPECTED: [test deliverables]
RULES: [constraints]
" --skip-git-repo-check -s danger-full-access
```

**When to use**:
- Test generation
- Test coverage improvement
- Documentation updates

**No Default Mode**: MODE must be explicitly specified in every command

## Session Management

Codex supports session continuity for multi-task workflows. See [session-management.md](session-management.md) for detailed patterns.

### Session Resume Patterns

**First Task** (establish session):
```bash
codex -C project --full-auto exec "
PURPOSE: [initial task]
TASK: [first implementation]
MODE: auto
CONTEXT: @{relevant/files}
EXPECTED: [deliverables]
RULES: [constraints]
" --skip-git-repo-check -s danger-full-access
```

**Subsequent Tasks** (continue session):
```bash
codex --full-auto exec "
PURPOSE: [next task]
TASK: [related implementation]
MODE: auto
CONTEXT: Previous implementation from current session
EXPECTED: [deliverables]
RULES: [constraints]
" resume --last --skip-git-repo-check -s danger-full-access
```

**Parameter Position**: `resume --last` must be placed AFTER the prompt string at command END

### Auto-Resume Decision Rules

**Use `resume --last` when**:
- Current task extends previous Codex task in conversation
- Current task requires context from previous implementation
- Multi-step workflow (implement → enhance → test)
- Session memory indicates recent Codex execution

**Do NOT use `resume --last` when**:
- First Codex task in conversation
- New independent task unrelated to previous work
- Switching to different module/feature area
- No recent Codex task in conversation memory

### Interactive Session Resume

```bash
# Resume with session picker
codex resume

# Resume most recent session directly
codex resume --last
```

### Image Attachment Support

```bash
# Attach images for UI/design implementation
codex -i screenshot.png -C project --full-auto exec "
PURPOSE: Implement UI from design
TASK: Create component matching screenshot
MODE: auto
CONTEXT: @{src/components/**}
EXPECTED: React component matching design
RULES: Follow design system
" --skip-git-repo-check -s danger-full-access
```

## File Pattern Reference

Common patterns for CONTEXT field:

```bash
@{**/*}                    # All files
@{src/**/*}                # Source files
@{*.ts,*.tsx}              # TypeScript files
@{src/**/*.test.*}         # Test files
@{CLAUDE.md,**/*CLAUDE.md} # Documentation
```

## Template System

Templates are located in `~/.claude/workflows/cli-templates/prompts/`

### Available Templates

**Development Templates**:
- `development/feature.txt` - Feature implementation
- `development/refactor.txt` - Refactoring tasks
- `development/testing.txt` - Test generation

**Analysis Templates** (for planning):
- `analysis/pattern.txt` - Code pattern analysis
- `analysis/architecture.txt` - System architecture review
- `analysis/security.txt` - Security assessment

### Using Templates in RULES Field

```bash
# Single template
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) | Follow security best practices

# Multiple templates
RULES: $(cat template1.txt) $(cat template2.txt) | Maintain backward compatibility

# No template
RULES: Use Jest, follow existing patterns, 80%+ coverage
```

## Directory Context Configuration

Codex uses `-C` parameter for directory context:

```bash
# Focused on specific directory
codex -C src/auth --full-auto exec "..." --skip-git-repo-check -s danger-full-access

# Relative path
codex -C ../project --full-auto exec "..." --skip-git-repo-check -s danger-full-access

# Absolute path
codex -C /full/path/to/project --full-auto exec "..." --skip-git-repo-check -s danger-full-access
```

## Execution Configuration

### Timeout Allocation (Dynamic + Multiplier)
Codex uses 1.5x of base timeout due to development complexity:

- **Simple** (test generation): 30-60min (1800000-3600000ms)
- **Medium** (feature implementation): 60-90min (3600000-5400000ms)
- **Complex** (multi-module refactor): 90-180min (5400000-10800000ms)

Auto-detect from PURPOSE and TASK fields.

### Permission Framework
- ⚠️ **No Default Mode**: MODE must be explicitly specified
- 🔒 **Write Protection**: Requires explicit user instruction
- ✅ **Auto Mode**: Full file operations when MODE=auto specified
- ✅ **Write Mode**: Test generation when MODE=write specified

## Examples

Production-ready examples organized by scenario type:

- **[Feature Implementation](feature-examples.md)** - RESTful APIs and multi-task authentication systems with session resume patterns
- **[Bug Fix & Refactoring](bugfix-refactor-examples.md)** - Performance investigation workflows and large-scale DDD refactoring
- **[Advanced Development](advanced-examples.md)** - Graph algorithms, UI implementation from designs, and security-focused features
- **[Session Management](session-management.md)** - Interactive resume patterns and multi-phase development workflows

Each example follows the Universal Template Structure with detailed session continuity patterns.

## Best Practices

### Implementation Phase
- Always specify MODE (auto/write)
- Use `-C` for directory context
- Include file patterns in CONTEXT
- Reference templates in RULES
- Use session management for multi-step tasks

### Testing Phase
- Use MODE=write for test generation
- Reference implementation in CONTEXT
- Specify coverage requirements in RULES
- Use existing test patterns

### Multi-Task Workflows
- First task: establish session
- Subsequent tasks: use `resume --last`
- Maintain context continuity
- Keep related tasks in same session

## Error Handling

**If timeout occurs**:
- Reduce task scope
- Split into smaller subtasks
- Use session management for continuity

**If implementation blocked**:
- Check CONTEXT includes necessary files
- Verify MODE is specified
- Review RULES for conflicts

**If tests fail**:
- Use MODE=write to generate test fixes
- Reference failing tests in CONTEXT
- Specify fix requirements in RULES

**If session lost**:
- Use `codex resume` to restore session
- Reference previous work in CONTEXT
- Include session memory in prompt

## Security Considerations

### Permission Requirements
- `-s danger-full-access`: Full file system access
- `--skip-git-repo-check`: Skip git validation
- `--full-auto`: Autonomous execution mode

### Safety Guidelines
- Review generated code before committing
- Verify test coverage meets requirements
- Check for security vulnerabilities
- Validate backward compatibility

### Best Practices
- Use MODE=write for non-destructive operations
- Review RULES for security constraints
- Include security templates when relevant
- Test in isolated environment first