Multi Codex Orchestrator

Use this skill when the user explicitly wants multiple Codex workers running as independent agents, rather than relying on built-in sub-agent behavior.

When To Use

• The task can be split into mostly independent workstreams.
• Each worker can own a bounded path set or responsibility.
• The coordinator can validate and integrate outputs at the end.

When Not To Use

• The task is small enough for one agent.
• Several workers would need to edit the same core files.
• The task is highly sequential and cannot benefit from parallelism.

Default Execution Model

1. Create a plan file from assets/templates/plan.yaml.
2. Give each worker a clear id, role, paths, and goal.
3. Use scripts/spawn_agents.sh to validate the plan and create one git worktree per worker under /tmp/.
4. Run each worker with codex exec in its own worktree.
5. Require each worker to write result.json in its run directory.
6. Use scripts/collect_results.sh to gather artifacts and diffs.
7. Integrate centrally. Do not let workers merge each other's changes.

Hard Rules

• One worker owns one write scope.
• Default to isolated git worktrees, not one shared writable tree.
• Workers must produce structured outputs, not just free-form prose.
• The coordinator must re-validate before integrating.
• If two workers need the same file, redesign the split or serialize the work.

File Layout

• scripts/plan_tasks.sh: copy a starter plan into a target project folder.
• scripts/spawn_agents.sh: parse the plan, create worktrees, and launch workers.
• scripts/collect_results.sh: summarize each worker run.
• scripts/merge_patches.sh: verify worker status and apply non-conflicting diffs into the integration branch.
• references/task-schema.md: the supported plan shape.
• references/output-schema.md: required worker outputs.
• references/conflict-policy.md: what to do when scopes collide.

Quick Start

PROJECT_DIR=output/2026-04-10/my-parallel-run
mkdir -p "$PROJECT_DIR"

./scripts/plan_tasks.sh "$PROJECT_DIR"
# edit "$PROJECT_DIR/plan.yaml"

./scripts/spawn_agents.sh "$PROJECT_DIR/plan.yaml"
./scripts/collect_results.sh "$(cat "$PROJECT_DIR/.last-run-dir")"

Plan Format

Read references/task-schema.md before editing plan.yaml.

This MVP expects a small, line-oriented YAML shape:

goal: Add RBAC to the app
repo_path: /abs/path/to/repo
base_branch: main
run_root: /tmp/multi-codex-orchestrator
agents:
  - id: analyst
    role: analyze
    paths: src/auth,src/models
    goal: Inspect current auth model and propose changes
  - id: backend
    role: implement
    paths: src/auth,src/api
    goal: Implement middleware and API changes

Worker Prompting

The launcher renders assets/templates/agent-task.md for each worker and appends the worker-specific fields from the plan.

Each worker should:

• stay inside its owned paths
• write result.json
• leave code changes in its worktree
• avoid rebasing, merging, or force-pushing

Before launch, the coordinator should reject any plan where two workers own overlapping paths.

Validation

• Use scripts/collect_results.sh first.
• Review result.json, last-message.txt, and diff.patch for each worker.
• Only then apply scripts/merge_patches.sh, which will refuse blocked or conflicting worker outputs.

Notes

• This is an MVP skill. It favors explicit structure over clever automation.
• If you need more flexible schemas later, replace the shell YAML parsing with a dedicated parser.