codex-delegation

What this skill does

# 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

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

### Full Context Package

```json
{
  "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

```markdown
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

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

### Step 4: Receive

```markdown
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:

```json
{
  "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.