codex-delegator

What this skill does

# Codex Delegator

## Overview

This skill enables Claude Code to automatically delegate complex, challenging tasks to OpenAI Codex CLI using `codex exec --full-auto`. When Claude Code encounters tasks that require different problem-solving approaches, deep logical analysis, or tasks that have proven resistant to repeated attempts, it can seamlessly invoke Codex to provide fresh perspectives and alternative solutions. The delegation happens automatically and transparently, with Claude Code handling context preparation, execution, and solution validation.

## How Automated Delegation Works

When Claude Code determines a task is suitable for delegation:

1. **Analysis Phase**: Claude Code analyzes the task complexity, context, and requirements
2. **Decision**: Determines if delegation would be beneficial based on:
   - Task has been attempted 2+ times without success
   - High logic complexity (nested conditions, complex algorithms)
   - Backend/algorithm intensive work
   - Need for different problem-solving approach

3. **Delegation**: Automatically invokes Codex:
   ```bash
   codex exec --full-auto "detailed task context with:
   - Problem description
   - Architecture and constraints
   - Previous attempts and failures
   - Success criteria"
   ```

4. **Validation**: Claude Code reviews Codex's solution for correctness and completeness
5. **Integration**: Returns validated solution to user with transparency about using Codex

**User Transparency**: Claude Code will inform you when it delegates to Codex, e.g., "I'm using Codex to generate this complex backend logic..."

## When to Use This Skill

Activate this skill specifically for:

1. **Complex Backend Logic**
   - Intricate business logic implementations
   - Complex data processing pipelines
   - Sophisticated algorithm implementations
   - Multi-layered service architectures
   - Advanced state management systems

2. **Logic-Intensive Problems**
   - Complex conditional logic with many edge cases
   - Intricate data transformations
   - Complex query optimization
   - Advanced caching strategies
   - Sophisticated error handling flows

3. **Persistent Unsolved Problems**
   - Bugs that remain after multiple fix attempts
   - Performance issues that resist optimization
   - Race conditions and concurrency problems
   - Memory leaks that are hard to track
   - Integration issues between complex systems

4. **When Different Perspective Needed**
   - Tasks attempted multiple times without success
   - Problems requiring alternative approaches
   - Situations where fresh analysis would help
   - Complex refactoring that's gotten stuck

## DO NOT Use This Skill For

- Simple CRUD operations
- Basic UI components
- Straightforward bug fixes
- Simple configuration changes
- General coding questions or tutorials

## Quick Decision Framework

**Use Codex when:**
- ✅ Problem has been attempted 2+ times without resolution
- ✅ Logic complexity score is high (multiple nested conditions, complex state)
- ✅ Backend/algorithm heavy task
- ✅ Need different problem-solving approach

**Don't use Codex when:**
- ❌ Problem is straightforward
- ❌ First attempt at the problem
- ❌ Simple frontend/styling work
- ❌ Basic setup or configuration

## Delegation Workflow

### Step 1: Verify Installation

Before delegating, check if Codex is available:

```bash
which codex
```

If not installed:
```bash
npm i -g @openai/codex
codex auth
```

### Step 2: Prepare Task Context

Create clear, detailed task description including:

1. **Problem statement** - What needs to be solved
2. **Context** - Relevant code, architecture, constraints
3. **Attempts made** - What has been tried and why it failed
4. **Expected outcome** - Clear success criteria
5. **Key files** - Specific files that need attention

### Step 3: Choose Execution Strategy

#### Strategy A: Interactive Mode (Recommended for Complex Problems)

Use when problem requires exploration and iteration:

```bash
cd /path/to/project
codex
```

Then provide detailed context:
```
I need help with [problem description].

Context:
- [Architecture overview]
- [Relevant constraints]
- [Previous attempts and failures]

The issue is in these files:
- [file1]: [specific problem]
- [file2]: [specific problem]

Goal: [clear success criteria]
```

**Advantages:**
- Can iterate on the solution
- Review changes with `/diff`
- Undo mistakes with `/undo`
- Switch models/reasoning levels with `/model`

#### Strategy B: Exec Mode (For Well-Defined Problems)

Use when problem is clear and specific:

```bash
codex exec "detailed task description with full context"
```

Add flags as needed:
- `--search` - For problems requiring up-to-date library knowledge
- `--full-auto` - For trusted, well-scoped tasks

#### Strategy C: Cloud Mode (For Persistent Problems)

Use for problems needing multiple solution attempts:

```bash
codex cloud exec --env ENV_ID --attempts 3 "complex problem description"
```

**Advantages:**
- Multiple solution attempts (best-of-N)
- Asynchronous execution
- Good for trial-and-error scenarios

### Step 4: Monitor and Validate

**In interactive mode:**
- Use `/diff` to review changes before accepting
- Use `/undo` if approach is wrong
- Use `/review` to get Codex's own code review

**After execution:**
- Run tests to verify solution
- Check edge cases
- Validate performance improvements
- Document the solution approach

### Step 5: Resume or Pivot

If problem persists:

```bash
# Resume previous session
codex resume

# Or try different model/reasoning level
codex
/model  # Switch to different model or higher reasoning
```

## Effective Task Delegation Examples

### Example 1: Complex Backend Logic

**Scenario:** Implementing sophisticated multi-tenant data isolation with complex permission rules.

```bash
cd /path/to/project
codex
```

```
I need to implement row-level security for a multi-tenant application.

Requirements:
- Each tenant can only access their own data
- Admin users can access all tenants
- Super admins can impersonate any user
- Audit all data access

Current architecture:
- PostgreSQL database
- Node.js/Express backend
- Using Sequelize ORM

Files involved:
- src/middleware/tenancy.js
- src/models/User.js
- src/policies/access-control.js

Previous attempts:
1. Tried global Sequelize scopes - leaked data in JOIN queries
2. Tried middleware checks - inconsistent across endpoints
3. Current approach using hooks - performance issues

Goal: Bulletproof tenant isolation with good performance
```

### Example 2: Persistent Bug

**Scenario:** Race condition causing intermittent failures.

```bash
codex exec --search "Debug and fix race condition in payment processing:

Context:
- Stripe webhook handler in src/webhooks/stripe.js
- Order service in src/services/orders.js
- Redis cache for order status

Problem:
- 5% of payments succeed but orders stay in 'pending' state
- Happens only under high load
- Attempted fixes:
  1. Added database transaction - didn't help
  2. Increased Redis TTL - still fails
  3. Added retry logic - made it worse

Stack trace (intermittent):
[paste stack trace]

Need: Root cause analysis and fix with proper synchronization"
```

### Example 3: Complex Algorithm

**Scenario:** Optimizing complex matching algorithm.

```bash
cd /path/to/project
codex
```

```
Need to optimize recommendation engine in src/algorithms/matching.js

Current implementation:
- O(n²) complexity with nested loops
- Processes 10k items in 30 seconds (too slow)
- Need to handle 100k+ items

Constraints:
- Must maintain ranking accuracy
- Memory limit: 2GB
- Real-time updates required

Attempted optimizations:
1. Added caching - helped but not enough
2. Tried batch processing - broke real-time requirement
3. Implemented early termination - minimal impact

Goal: Sub-second processing for 100k items
```

## Advanced Techniques

### Using Enhanced Reasoning

For extremely complex problems, request higher reasoning effort:

```bash
codex
/model  # Choose GPT-5 or increas