codex-delegation

Worker Delegation Skill

This skill defines how the CEO (Claude) delegates tasks to workers. Workers can be either Codex MCP (GPT) or Claude Task sub-agents.

Executor Selection

The executor is determined by priority:

1. --executor argument (explicit override)
2. ./specs/.ralph-executor.json (saved config from /ceo-ralph:setup)
3. Runtime detection: check if mcp__codex__codex tool exists
4. Default: auto (try Codex, fall back to Task)

Codex MCP Executor

• Tool: mcp__codex__codex
• Runs GPT models in a sandboxed environment
• Best for: code generation, file manipulation
• Requires: Codex CLI installed + authenticated

Task Sub-agent Executor

• Tool: Task with subagent_type: "general-purpose"
• Runs Claude sub-agents (model: sonnet)
• Best for: when Codex is unavailable, or for Claude-native tasks
• Requires: nothing (built into Claude Code)

When to Delegate

Delegate to workers when:

• Task is implementation-focused (writing code)
• Task has clear acceptance criteria
• Task doesn't require strategic decisions
• Task is scoped to specific files

Do NOT delegate when:

• Task requires architecture decisions
• Task is a [VERIFY] checkpoint (delegate to qa-engineer instead)
• Task requires user interaction
• Task involves research or analysis

Preparing Context Packages

Minimal Context Package

{
  "taskId": "1.1",
  "task": {
    "title": "Task title",
    "do": "What to do",
    "doneWhen": "Completion criteria",
    "acceptance": ["Criterion 1", "Criterion 2"]
  }
}

Full Context Package

{
  "taskId": "1.1",
  "task": {
    "title": "Implement user login form",
    "do": "Create login form component at src/components/Login.tsx",
    "doneWhen": "Form renders with email/password fields and validation",
    "acceptance": [
      "Form has email input with validation",
      "Form has password input with masking",
      "Submit button triggers onSubmit handler",
      "Shows validation errors"
    ]
  },
  "files": {
    "src/components/Form.tsx": {
      "path": "src/components/Form.tsx",
      "content": "// Existing form component for reference...",
      "language": "typescript",
      "relevantSections": [
        { "startLine": 10, "endLine": 50, "description": "Form pattern" }
      ]
    }
  },
  "design": {
    "architecture": "React functional component with hooks",
    "patterns": ["controlled inputs", "form validation", "error display"]
  },
  "constraints": [
    "Follow existing Form component pattern",
    "Use project's validation library (zod)",
    "Match existing styling approach"
  ],
  "workingDirectory": "/path/to/project",
  "commitPrefix": "feat(auth)"
}

Context Optimization

File Selection

1. Include files directly mentioned in task
2. Include pattern files from same directory
3. Include type definitions if TypeScript
4. Limit to ~5 files maximum
5. Use relevant sections, not entire files

Context Pruning

If context is too large:

1. Extract only relevant functions/classes
2. Remove comments and whitespace
3. Summarize repetitive patterns
4. Reference design.md instead of repeating

Delegation Protocol

Step 1: Prepare

I am preparing to delegate Task {id} to a worker.

**Task**: {title}
**Executor**: {codex|task-agent}
**Files to include**: {list}
**Constraints**: {list}

Step 2: Delegate

Codex MCP:

mcp__codex__codex({
  prompt: "<spec-executor instructions>\n\nTask: <task block>\n\nContext: <files>",
  sandbox: "workspace-write"
})

Task sub-agent:

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: "<spec-executor instructions>\n\nTask: <task block>\n\nContext: <files>\n\nIMPORTANT: Output TASK_COMPLETE when done."
})

Step 3: Monitor

[<executor>] Task {id} delegated.
Status: {pending|running|completed|failed}

Step 4: Receive

Received result from worker.
Signal: {TASK_COMPLETE|TASK_BLOCKED|NO_SIGNAL}
Files modified: {count}

Handling Worker Output

On TASK_COMPLETE

1. Parse file modifications
2. Verify "Done when" criteria
3. Update delegation log
4. Proceed to next task

On TASK_BLOCKED

1. Read block reason
2. Assess if CEO can unblock
3. If yes: Provide guidance and retry
4. If no: Escalate to user

On NO_SIGNAL

1. Check if output looks complete
2. If yes: Treat as soft completion, verify carefully
3. If no: Retry with explicit signal instruction

Retry Strategy

When retrying:

{
  "previousAttempts": [
    {
      "attempt": 1,
      "executor": "codex",
      "feedback": "Missing validation on email field",
      "issues": [
        "Email input lacks validation",
        "Error messages not displayed"
      ]
    }
  ]
}

Feedback Quality

Good feedback:

• "In Login.tsx line 23, add email regex validation"
• "The onSubmit handler doesn't prevent default"

Bad feedback:

• "Fix the validation"
• "It doesn't work"

Delegation Logging

Every worker dispatch is logged to ./specs/$spec/.ralph-delegation.json. See schemas/delegation.schema.json for the full schema.

Each worker entry tracks:

• Worker ID, task ID, executor type
• Start/complete timestamps, duration
• Result signal, summary, files changed
• Commit hash

Aggregate stats are updated after each worker completes.