Use when you have 2+ tasks that Codex agents should execute. Runtime-native: Codex sub-agents when available, Codex CLI fallback otherwise. Handles file conflicts via merge/wave strategies. Triggers: "codex team", "spawn codex", "codex agents", "use codex for", "codex fix".
Use when you have 2+ tasks that Codex agents should execute. Runtime-native: Codex sub-agents when available, Codex CLI fallback otherwise. Handles file conflicts via merge/wave strategies. Triggers: "codex team", "spawn codex", "codex agents", "use codex for", "codex fix".
skill_api_version
1
context
fork
metadata
{"tier":"cross-vendor"}
Codex Team
The lead orchestrates, Codex agents execute. Each agent gets one focused task. The team lead prevents file conflicts before spawning — the orchestrator IS the lock manager.
For Claude-runtime feature compatibility (agents/hooks/worktree/settings), use ../shared/references/claude-code-latest-features.md when this skill falls back to /swarm.
When to Use
You have 2+ tasks (bug fixes, implementations, refactors)
Tasks are well-scoped with clear instructions
You want Codex execution with predictable isolation
You may be in Claude or Codex runtime (skill auto-selects backend)
Don't use when: Tasks need tight shared-state coordination. Use /swarm for dependency-heavy wave orchestration.
Backend Selection (MANDATORY)
Select backend in this order:
spawn_agent available -> Codex experimental sub-agents (preferred)
Codex CLI available -> Codex CLI via Bash (codex exec ...)
# REQUIRED before spawning with Codex CLI backend
if ! which codex > /dev/null 2>&1; then
echo "Codex CLI not found. Install: npm i -g @openai/codex"
# Fallback: use /swarm
fi
# Model availability test
CODEX_MODEL="${CODEX_MODEL:-gpt-5.3-codex}"
if ! codex exec --full-auto -m "$CODEX_MODEL" -C "$(pwd)" "echo ok" > /dev/null 2>&1; then
echo "Codex model $CODEX_MODEL unavailable. Falling back to /swarm."
fi
For code review and analysis tasks, prefer -s read-only over --full-auto.
Execution
Step 1: Define Tasks
Break work into focused tasks. Each task = one Codex agent (unless merged).
Step 2: Analyze File Targets (REQUIRED)
Before spawning, identify which files each task will edit. Codex agents are headless — they can't negotiate locks or wait turns. All conflict prevention happens here.
For each task, list the target files. Then apply the right strategy:
File Overlap
Strategy
Action
All tasks touch same file
Merge
Combine into 1 agent with all fixes
Some tasks share files
Multi-wave
Shared-file tasks go sequential across waves
No overlap
Parallel
Spawn all agents at once
# Decision logic (team lead performs this mentally):
tasks = [
{name: "fix spec_path", files: ["cmd/zeus.go"]},
{name: "remove beads field", files: ["cmd/zeus.go"]},
{name: "fix dispatch counter", files: ["cmd/zeus.go"]},
]
# All touch zeus.go → MERGE into 1 agent
spawn_agent(message="Fix the null check in pkg/auth.go:validateToken around line 89...")
spawn_agent(message="Add timeout field to internal/config.go:Config struct...")
spawn_agent(message="Fix log rotation in pkg/log.go:rotateLogFile...")
Codex CLI backend:
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/auth-fix.md "Fix the null check in pkg/auth.go:validateToken around line 89..."', run_in_background=true)
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/config-fix.md "Add timeout field to internal/config.go:Config struct..."', run_in_background=true)
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/logging-fix.md "Fix log rotation in pkg/log.go:rotateLogFile..."', run_in_background=true)
Strategy: Merge (same file)
Combine all fixes into a single agent prompt:
spawn_agent(message="Fix these 3 issues in cmd/zeus.go: (1) rename spec_path to spec_location in QUEST_REQUEST payload (2) remove beads field (3) fix dispatch counter increment location")
# CLI equivalent:
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/zeus-fixes.md \
"Fix these 3 issues in cmd/zeus.go: \
(1) Line 245: rename spec_path to spec_location in QUEST_REQUEST payload \
(2) Line 250: remove the spurious beads field from the payload \
(3) Line 196: fix dispatch counter — increment inside the loop, not outside"', run_in_background=true)
One agent, one file, no conflicts possible.
Strategy: Multi-wave (partial overlap)
# Wave 1: non-overlapping tasks (sub-agent backend)
spawn_agent(message='Fix null check in pkg/auth.go:89...')
spawn_agent(message='Add timeout to internal/config.go...')
# Wait for Wave 1 (sub-agent backend)
wait(ids=["<id-1>", "<id-2>"], timeout_ms=120000)
# Wave 1: non-overlapping tasks (CLI backend)
Bash(command='codex exec ... -o .agents/codex-team/auth-fix.md "Fix null check in pkg/auth.go:89..."', run_in_background=true)
Bash(command='codex exec ... -o .agents/codex-team/config-fix.md "Add timeout to internal/config.go..."', run_in_background=true)
# Wait for Wave 1
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)
# Read Wave 1 results — understand what changed
Read(.agents/codex-team/auth-fix.md)
git diff pkg/auth.go
# Wave 2: task that shares files with Wave 1 (sub-agent backend)
spawn_agent(message='Add rate limiting to pkg/auth.go and pkg/middleware.go. Note: validateToken now has a null check at line 89. Build on current file state.')
# Wave 2: CLI backend equivalent
Bash(command='codex exec ... -o .agents/codex-team/rate-limit.md \
"Add rate limiting to pkg/auth.go and pkg/middleware.go. \
Note: pkg/auth.go was recently modified — the validateToken function now has a null check at line 89. \
Build on the current state of the file."', run_in_background=true)
TaskOutput(task_id="<id-3>", block=true, timeout=120000)
The team lead synthesizes Wave 1 results and injects relevant context into Wave 2 prompts. Don't dump raw diffs — describe what changed and why it matters for the next task.
For multi-wave: verify Wave 2 agents built correctly on Wave 1 changes
Output Directory
mkdir -p .agents/codex-team
Output files: .agents/codex-team/<task-name>.md
Prompt Guidelines
Good Codex prompts are specific and self-contained:
# GOOD: Specific file, line, exact change
"Fix in cmd/zeus.go line 245: rename spec_path to spec_location in the QUEST_REQUEST payload struct"
# BAD: Vague, requires exploration
"Fix the spec path issue somewhere in the codebase"
Include in each prompt:
Exact file path(s)
Line numbers or function names
What to change and why
Any constraints (don't touch other files, preserve API compatibility)
For multi-wave Wave 2+ prompts, also include:
What changed in prior waves (summarized, not raw diffs)
Current state of shared files after prior edits
Limits
Max agents: 6 per wave (resource-reasonable)
Timeout: 2 minutes default per agent. Increase with timeout param for larger tasks
Max waves: 3 recommended. If you need more, reconsider task decomposition
Fallback
If Codex is unavailable, delegate to /swarm which auto-selects the best available backend (native teams with messaging/redirect/graceful shutdown, or background tasks as last resort):
Skill(skill="swarm")
Note:/codex-team runs Codex CLI processes as background shell commands — this is fine (separate OS processes). For Claude agent orchestration, use /swarm which uses your runtime's native multi-agent primitives.
