Dispatching parallel agents codex

<!-- Upstream source: obra/superpowers skills/dispatching-parallel-agents/SKILL.md Last synced: 2026-04-05 Divergence: Codex-backed dispatch — parallel `codex_implement` MCP calls replace upstream `Task()` tool calls; review still done by Claude after all threads return -->

Dispatching Parallel Agents

Overview

When you have multiple unrelated tasks (different subsystems, different bugs), working them sequentially wastes time. Each thread is independent and can happen in parallel.

Core principle: Dispatch one codex_implement per independent problem domain. Let them work concurrently.

<HARD-GATE> Parallel execution MUST use codex_implement calls. You cannot implement tasks yourself. This skill dispatches Codex workers — Claude orchestrates, Codex executes. </HARD-GATE>

When to Use

digraph when_to_use {
    "Multiple independent tasks?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single codex_implement handles all" [shape=box];
    "One codex_implement per domain" [shape=box];
    "Can they run without shared state?" [shape=diamond];
    "Sequential codex_implement" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple independent tasks?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single codex_implement handles all" [label="no - related"];
    "Are they independent?" -> "Can they run without shared state?" [label="yes"];
    "Can they run without shared state?" -> "Parallel dispatch" [label="yes"];
    "Can they run without shared state?" -> "Sequential codex_implement" [label="no - shared state"];
}

Use when:

• 3+ failing test files with different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from others
• No shared state between threads (no same-file edits)

Don't use when:

• Failures are related (fix one might fix others)
• Need to understand full system state first
• Threads would edit the same files

The Pattern

1. Identify Independent Domains

Group tasks by what's being changed:

• Thread A: Agent forwarding contract in scripts/
• Thread B: Test fixture updates in tests/fixtures/
• Thread C: Schema validation in schemas/

Each domain is independent — Thread A doesn't touch Thread B's files.

2. Create Focused Task Prompts

Each codex_implement call gets:

• Specific scope: One file or subsystem
• Clear goal: What done looks like
• Constraints: Don't change other code
• Expected output: Summary of what was found and fixed

3. Dispatch in Parallel

Call multiple codex_implement tools in a single message so they run concurrently:

{
  "tool": "codex_implement",
  "arguments": {
    "taskId": "parallel-A",
    "prompt": "Fix the 3 failing tests in tests/adapter/codex-run.test.mjs. These are timeout-related. Root cause and fix only — do not touch other test files.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

{
  "tool": "codex_implement",
  "arguments": {
    "taskId": "parallel-B",
    "prompt": "Fix the schema mismatch in schemas/implementer-result.schema.json. The 'tests' field is missing from the required array. Do not touch other schemas.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

{
  "tool": "codex_implement",
  "arguments": {
    "taskId": "parallel-C",
    "prompt": "Update the fixture in tests/fixtures/sample-result.jsonl to match the new implementer-result schema. Only touch that fixture file.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

4. Review and Integrate

When all threads return, each response includes a sessionId — capture it for follow-up:

• Read each summary
• Verify fixes don't conflict (check for same-file edits)
• Run full test suite
• Use codex_resume with the returned taskId and sessionId if any thread needs follow-up

Writing Good Prompts

Good prompts are:

1. Focused - One clear problem domain
2. Self-contained - All context needed to understand the problem
3. Specific about constraints - Name files they must NOT touch
4. Clear about output - Summary of root cause and changes made

Bad:

"Fix all the tests"  ← agent gets lost
"Fix the race condition"  ← agent doesn't know where

Good:

"Fix the 3 failing tests in tests/adapter/codex-run.test.mjs.
Tests: [list test names + error messages].
Root cause is likely X. Fix by Y.
Do NOT change production code.
Return: root cause found and what you changed."

Common Mistakes

Too broad: Agent gets lost in unrelated code. No constraints: Agent refactors everything. Vague output: You don't know what changed. Overlapping scope: Threads edit same files, creating conflicts.

When NOT to Use

Related failures: Investigate together, fixing one might fix others. Need full context: Understanding requires seeing the whole system. Exploratory debugging: You don't know what's broken yet — use codex_debug first. Shared state: Threads would interfere (editing same files).

After All Threads Return

1. Review each summary — understand what changed
2. Check for conflicts — did any threads edit the same file?
3. Run full suite — npm test
4. Resume if needed — use codex_resume with the appropriate taskId and sessionId
5. Spot check — Codex can make systematic errors; read the diff

Key Benefits

1. Parallelization — multiple threads work simultaneously
2. Focus — each thread has narrow scope
3. Independence — threads don't interfere
4. Speed — N problems solved in time of 1