Dynamic Workflows for Codex

A saddle for the wild-horse LLM. A harness for Codex.

Dynamic Workflows for Codex is a portable AGENTS.md operating contract that teaches Codex to decide when a task benefits from multiple agents, delegate bounded work, integrate the results, and verify the outcome from the root thread.

It uses Codex's native agent-tree tools. It is not a clone of Claude Code's separate JavaScript workflow runtime, and it is not affiliated with OpenAI or Anthropic.

What it does

Every prompt passes through an adaptive orchestration gate:

prompt
  |
  v
is there useful independent work?
  | no                         | yes
  v                            v
single-agent execution      root orchestrator
                               |
                    +----------+----------+
                    v          v          v
                  scout   implementer  verifier
                    +----------+----------+
                               |
                               v
                    root integrates and tests

The harness favors the smallest effective execution graph. Trivial work remains single-agent. Substantive work can use scouts, fan-out/fan-in, independent attempts, implement/review pairs, or bounded pipelines.

The recommended runtime profile keeps the user-facing root at Ultra reasoning effort, gives ordinary workers a Medium default, and lets the root select lower or higher worker effort when the spawn interface supports it:

model_reasoning_effort = "ultra"

[agents]
max_concurrent_threads_per_session = 6
default_subagent_reasoning_effort = "medium"

Six concurrent threads means one root plus up to five workers. It is a ceiling, not a target; most tasks should use fewer. Restart Codex after changing the configuration.

Why an AGENTS.md harness?

Codex already provides the machinery to spawn, message, interrupt, resume, and wait for subagents. The missing piece is a durable operating contract that tells the root agent:

• when delegation is worth its coordination cost;
• how to write bounded worker assignments;
• how to prevent shared-workspace conflicts;
• how to integrate rather than concatenate results; and
• why tests and sources outrank multi-agent consensus.

The complete contract is in AGENTS.md.

Install

Project-level

Copy AGENTS.md to the root of a project. Codex will apply it in that project, subject to higher-priority instructions and any more-specific nested AGENTS.md.

User-level

Merge the sections into ~/.codex/AGENTS.md if you want the policy to apply across projects. Merge rather than overwrite when you already have global instructions.

The policy explicitly authorizes proactive delegation, so it can operate when Codex's turn-level multi-agent mode otherwise requires an explicit user or AGENTS.md request.

Try it

Use prompts with different orchestration shapes:

Explain what a mutex is in two sentences.

Expected: no worker agents.

Audit this repository's authentication, input validation, and secrets handling
in parallel. Independently verify every high-severity finding. Do not edit.

Expected: bounded parallel scouts and a root-integrated report.

Implement this feature. Give one agent ownership of the backend, one ownership
of the frontend, and keep shared types and final integration in the root.

Expected: non-overlapping ownership, followed by root-level integration checks.

Validation

Run the static contract checks:

./tests/validate-contract.sh

Behavioral scenarios and the evidence format are documented in tests/SCENARIOS.md. Static checks catch missing required clauses; they do not prove the contract is complete or internally consistent. Observed behavioral runs provide runtime evidence, not a universal guarantee across models or Codex versions.

Design boundaries

This project does not promise:

• Claude Code-style JavaScript workflows or /workflows UI;
• hundreds of simultaneous agents;
• context-free orchestration state;
• persistent background execution after Codex exits; or
• better results merely because more agents were used.

Its claim is narrower: good routing, bounded delegation, central integration, and independent verification can improve complex-task coverage while keeping simple work efficient.

Keeping the root at Ultra also increases usage for trivial prompts even when no workers spawn. That is an intentional configuration tradeoff in the recommended profile, not adaptive compute allocation.

Contributing

Please keep changes evidence-driven. A policy change should include a scenario that would fail or become materially worse without it. Do not add model-specific hype, hidden prompts, telemetry, dependencies, or networked services.

See CONTRIBUTING.md and docs/INSTALLATION.md for the complete workflow.

License

Apache License 2.0. See LICENSE.