Orchestrating Task Execution
Introduction: The Context Problem in Long Sessions
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.
How Orchestration Works: The Main Agent Pattern
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:
For example:
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:
The key insight: each subagent starts fresh. There's no accumulated context decay.
