Orchestrating Task Execution

When you build a production API feature with 10 tasks, you face a critical choice: execute all tasks in one long session, or break them into independent units with fresh context each time.

In a traditional approach, you might give Codex CLI a complete specification and say "implement all 10 tasks." This seems efficient—one instruction, one session, done. However, there's a hidden risk: as the session progresses through tasks, the probability of forgetting specification details increases. By task 10, important validation rules or patterns from the beginning might be forgotten.

This is both a probability problem and a technical limitation. Ten tasks mean ten opportunities to miss something. Even if each task has a 95% chance of being perfect, by task 10 the cumulative probability of at least one error is significant. Additionally, as the session progresses, you may hit context window limits, forcing earlier information to be dropped. By task 10, important validation rules or patterns from the beginning might be forgotten due to both accumulated conversation length and statistical likelihood.

With agent orchestration, you solve this automatically. Instead of one long session, a Main Agent coordinates the work. For each task, it delegates to a fresh Subagent that starts with a clean slate—AGENTS.md is auto-loaded, specification files are loaded when you reference them with @, and there's no accumulated context from previous tasks.

The orchestration pattern has two roles:

Main Agent (Coordinator):

• Reads the task list from tasks.md
• For each task, spawns a specialized subagent
• Receives completion reports
• Waits for human approval
• Tracks progress
• Stops at phase boundaries for review

Subagent (Executor):

• Receives one specific task instruction
• Gets fresh context: AGENTS.md auto-loaded, specification files you reference with @, task instructions
• Implements the task following test-first workflow
• Runs self-validation
• Reports structured results

Spawning Subagents

To delegate work to a subagent, we ask the Main Agent to spawn a sub-agent with a specific role and instruction:

Spawn a task-executor agent: "instruction" @context-file

For example:

Spawn a task-executor agent: "Execute T001 from @specs/comments/tasks.md"

This tells the Main Agent to spawn a sub-agent using the task-executor role defined in your .codex/config.toml under [agents.task-executor].

Here's what a typical orchestration flow looks like:

Main Agent: "We have 10 tasks to complete for Task Comments feature."

For Task 1:
  Spawn a task-executor agent: "Execute T001 from @specs/comments/tasks.md"
  [Subagent works, validates, reports completion]
  [Human reviews: 3 minutes]
  [Human approves]

For Task 2:
  Spawn a task-executor agent: "Execute T002 from @specs/comments/tasks.md
                                Context: @src/models/comment.py from T001"
  [Fresh subagent, fresh context, validates, reports]
  [Human reviews: 3 minutes]
  [Human approves]

...and so on through Task 10.

The key insight: each subagent starts fresh. There's no accumulated context decay.