Howto codex

Static reading edition · s04-07

Coordinate a small team without assuming a team mode

Subagents23 min estimatedApp / CLI / IDE

Build an explicit coordination plan with ownership, dependencies and evidence using documented Codex delegation.

Understand the approach

A small agent team is useful when each member owns an independent deliverable and the parent retains integration. Codex's documented subagent workflow should not be presented as a one-to-one copy of Claude's experimental team controls. The capstone needs only two implementation packages and a parent integrator. More titles would add coordination without creating a new independent output.

The ledger assigns A to starter/normalize.cjs and B to starter/report.cjs after a shared interface is established. A handles padded case and invalid status values. B receives normalized records and computes completed-only counts and effort. The parent waits for both code outputs, reconciles their handoffs and checks the combined state. A and B may proceed independently against CONTRACT.md; final acceptance depends on both.

Deliver a candidate that produces total=4, done=2 and doneMinutes=55, passes the four learner grading tests and preserves source inputs. Distinguish the runner's five named integration predicates from the seven frozen-baseline/reference tests. The deterministic simulation supplies reference handoffs with actualAgentsSpawned:false; any real worker activity needs its own observation. A ledger marked complete is useful only when its files and actual checks support that status.

Use the exact two-owner prompt and inspection flow in native-agent-guide.md for actual Codex coordination. The offline route already supplies working solution/normalize.cjs and solution/report.cjs, while candidate.test.cjs grades the editable starter. The real-worktree program proves an A-only handoff is rejected and the destination must be checked after integration. Codex’s documented parent/subagent orchestration reaches this outcome without claiming Claude’s experimental mailbox, automatic task-dependency service or teammate-pane controls. Judge working files and actual worker evidence rather than a fictional team-mode switch.

A normalizer, an aggregator, and one integration owner

Two independent work packages implement the status normalizer and report aggregator against a frozen interface. The coordinator reviews both handoffs and runs the combined program plus candidate checks. Acceptance requires valid input behavior, preservation and the fixture report total4, done2, doneMinutes55; a correct-looking total alone cannot pass. A failed or unverified boundary returns to its owner.

Two independent work packages implement the status normalizer and report aggregator against a frozen interface. The coordinator reviews both handoffs and runs the combined program plus candidate checks. Acceptance requires valid input behavior, preservation and the fixture report total4, done2, doneMinutes55; a correct-looking total alone cannot pass. A failed or unverified boundary returns to its owner.

Open the full diagram

Practice and acceptance

A team ledger is useful when it connects ownership, dependencies, artifacts and actual integration evidence.

About your environment

Checked 21 October 2026. The published guide reviewed here does not establish a one-to-one mapping for Claude's experimental team controls.

Try it step by step

  1. Run the broken starter and establish the final report contract.
  2. Use work-packages.json to assign two disjoint outputs and one parent-owned integration decision.
  3. Implement both modules with actual agents or sequentially, recording the method honestly.
  4. Inspect both handoffs and run the combined candidate plus boundary cases before marking the ledger complete.
  5. Compare with the reference solution only after attempting the task; report unverified Codex client behavior separately.

A useful starting example

Illustration · adapt before use.

Ownership and acceptance ledger for the A/B capstone markdown
| Task | Owner | Owns | Depends on | Done when |
| --- | --- | --- | --- | --- |
| Freeze interfaces | Parent | CONTRACT.md review | Baseline evidence | Inputs and acceptance are clear |
| Normalize statuses | A | starter/normalize.cjs | Frozen contract | Padded and invalid inputs meet contract |
| Aggregate report | B | starter/report.cjs | Frozen contract | Completed-only count/effort and validation work |
| Integrate candidate | Parent | Combined review | A + B | run.cjs starter and four candidate tests pass |

Return actual file/check evidence and explicitly identify whether real agents, sequential edits or deterministic simulation produced each artifact.
Run an independent report boundary after your attempt text
node -e "const {buildReport}=require('./labs/delegation-capstone/solution/report.cjs'); console.log(buildReport([{id:'open',status:'open',minutes:90},{id:'done',status:'done',minutes:5}]))"
# Reference: {total:2, done:1, doneMinutes:5}. The candidate must generalize too.
From input to result

The final evidence packet

The supplied reference demonstrates what an accepted local result contains.

Worked input text
A: normalize.cjs contract satisfied
B: report.cjs contract satisfied
I: run combined code and inspect boundary cases
Expected result · compare with your run
Report: {total:4, done:2, doneMinutes:55}
run.cjs solution: five named integration predicates pass
capstone.test.cjs: seven reference/baseline tests pass
candidate.test.cjs: four tests fail on unedited starter; four pass with the reference fixes
Actual agent activity: claim only observed client behavior

A green fixture suite is a bounded correctness signal; it is not evidence of agent speed, universal robustness or an unrun real-client workflow.

Hands-on exercise

Your turn

Deliver a working capstone candidate, not just a pair of agent briefs. Include the owned-file ledger, both handoffs, combined output and at least one independent boundary case. Try an incomplete handoff and show that integration rejects it. State whether real Codex agents, sequential edits or the supplied deterministic simulation produced each artifact.

Try the exercise before opening its reference answer. Use a disposable practice folder.

Run the practice

Deliver a small team's integrated code result

Extract into a new practice folder and keep the included labs folder. Run these commands from that extraction root, or from the course folder, using an existing Node.js installation.

  1. Command 1 text
    node --test labs/delegation-capstone/capstone.test.cjs

    Check: 7 contract checks pass for the unchanged reference set.

  2. Command 2 text
    node labs/delegation-capstone/run.cjs solution

    Check: Final reference report is total=4, done=2, doneMinutes=55.

  3. Command 3 text
    node --test labs/delegation-capstone/candidate.test.cjs

    Check: The unedited starter intentionally fails 4 candidate checks; all 4 should pass after both fixes.

  4. Command 4 text
    node --test labs/delegation-capstone/capstone.test.cjs labs/delegation-capstone/worktree.test.cjs

    Check: Nine reference/isolation checks pass; four learner checks remain intentionally red on the untouched starter.

A team ledger is useful when it connects ownership, dependencies, artifacts and actual integration evidence.

Check your result

  • Both module contracts and all four edited-candidate grading tests pass.
  • run.cjs produces the exact report and all five named integration predicates pass.
  • The seven reference/baseline tests, four candidate tests and any actual agent observations are reported as different evidence.
Reference answer & rubric Try the exercise before opening

The reference combines normalized, validated statuses with a completed-only aggregate and uses parent-owned checks to prevent partial delivery.

  1. Keep A and B's ownership disjoint and freeze CONTRACT.md.
  2. Require changed-file evidence and observed cases in each handoff.
  3. Verify total=4, done=2, doneMinutes=55 and rejection of malformed/duplicate records.
  4. Close the ledger only after combined verification; retain separate not-run status for actual role loading or background observation.
Think it through

Check your understanding

What does a depends-on column in a Markdown task ledger do?

  1. Automatically blocks every child until its dependency succeeds.
  2. Records a dependency that the coordinator must enforce.
  3. Creates Claude's shared task-list feature inside Codex.
Reveal the answer and explanation

Answer 2: Records a dependency that the coordinator must enforce.

The ledger makes the dependency visible. Actual orchestration still requires the parent to route and wait for the right work.

Take this quiz in the interactive lesson to save your answer in the browser.

When it does not work

The ledger says complete while the code still contains a starter bug.

Likely cause: Administrative status was treated as acceptance.

What to try: Run the actual combined candidate and reconcile the ledger with its failures.

Many specialists add coordination but no independent outputs.

Likely cause: Work was divided by titles rather than dependency and file ownership.

What to try: Collapse the plan to A, B and the parent integrator; add roles only for a concrete independent need.

Common mistakes

  • Claiming Claude team flags, mailbox paths or split-pane controls are current Codex commands.
  • Treating several agreeing agent summaries as a substitute for checking the product.
Source mapping & differences · alternative

Parent-coordinated Codex subagents plus an explicit ledger cover the coordination goal without claiming Claude Agent Teams feature parity.

Source topic: Agent teams ↗

Go to the source

Official documentation, checked 21 October 2026. Product names, controls and availability may vary with your version, platform or account.

Continue in the interactive lesson →

Completion and quiz progress are saved
only in the interactive course.