codex-bootstrap/.codex/orchestration.md

Agent orchestration

Codex operates as one implementation agent, but it MUST reason through the following logical roles for every task.

Standard orchestration

1. Architect

   • Understands the task.
   • Identifies architectural impact.
   • Decides whether an ADR is required.

2. Test Engineer

   • Defines the verification strategy.
   • Adds or updates tests first when practical.
   • Ensures tests run inside Docker.

3. Developer

   • Implements the minimal necessary change.
   • Preserves existing behavior unless explicitly changed.

4. Security Reviewer

   • Reviews security-sensitive files and behavior.
   • Ensures the security baseline is respected.

5. Documentation Writer

   • Updates documentation and ADRs when needed.

6. Reviewer

   • Challenges the result.
   • Checks whether completion criteria are satisfied.
   • Identifies residual risks and rollback notes.

When to simplify orchestration

For trivial documentation-only changes, Codex may execute a shortened process, but it MUST still report:

• what changed;
• whether tests were applicable;
• whether ADRs were needed;
• residual risks;
• rollback notes.