agentleFS
ddivyanshsharmaaddivyanshsharmaa/fable-toolkit/skills/duo-codex/SKILL.md

duo-codex

Skill0 starsChanged 44 days agoMITView on GitHub

Two engine loop where Claude orchestrates, writes the spec, and reviews, while Codex (`codex exec`) does all the implementation and code or security audits. Loops review and fix rounds until the result passes every acceptance criterion, then proves the assembled result works end to end. Usually reached through /team, which picks this loop on its own when Codex is signed in and Antigravity is not. Invoke directly when the user says "duo codex", "claude and codex", "use codex for this", or "codex team".

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. About 0 are common, 14 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If FABLE_MODE comes back as anything other than duo-codex, switch to that loop (trio when Antigravity is also available and faster for the …

    line 28
  2. Distinctive:

    Not worth it, do it yourself instead:

    line 40
  3. Distinctive:

    Keep for yourself anything that needs a product decision, a taste call, or that you cannot write a checkable criterion for.

    line 65
  4. Very specific:

    Create the run dir <project>/.duo/<yyyyMMdd-HHmmss>/.

    line 75
  5. Distinctive:

    If the project is a git repo, record git rev-parse HEAD and require a reasonably clean tree so review can lean on git diff.

    line 77
  6. Distinctive:

    Never run git init at your home directory level.

    line 80
  7. Distinctive:

    Read the project's own agent instructions if they exist: CLAUDE.md, AGENTS.md, and the setup and deploy sections of the README.

    line 81
  8. Very specific:

    Write spec.md in the run dir with four sections.

    line 88
  9. Very specific:

    Never accept an engine's claim.

    line 171
  10. Distinctive:

    Read the actual diff too, not just the test result.

    line 184
  11. Distinctive:

    Never loosen a criterion to make it pass.

    line 210
  12. Distinctive:

    If the same unit fails twice for the same reason, the brief is the problem, not the engine.

    line 213
  13. Distinctive:

    Run all six checks before you tell the user anything is done:

    line 223
  14. Distinctive:

    Exercise the real flow end to end, from a clean state: Start the app, run the script on real input, open the page in a browser, execute the …

    line 225
  15. Distinctive:

    Check the neighbours: Run the surrounding tests or drive the adjacent flow to confirm nothing that already worked is now broken.

    line 231
  16. Distinctive:

    If a check genuinely cannot be run, because of missing credentials, a missing environment, or a browser you do not have, write "written but …

    line 238
  17. Distinctive:

    Never dispatch work you have not written a criterion for.

    line 263
  18. Very specific:

    codex exec hangs forever unless stdin is closed: Always append </dev/null and run it through the Bash tool.

    line 268
  19. Very specific:

    Leave it alone unless a unit clearly needs another.

    line 284
  20. Distinctive:

    Never put secrets or credentials in a brief.

    line 285

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/duo-codex, the Claude and Codex loop

You (Claude, in this session) are the orchestrator and reviewer. Codex writes the code. You write the spec, dispatch briefs, review output against primary evidence, loop fixes until the criteria pass, and then prove the assembled result actually works.

Codex runs on a ChatGPT subscription, so there is no per-call API key. But every dispatch spends real quota, and a vague brief burns a whole round. Brief quality is the single biggest lever you control.

Invoked directly rather than through /team? Run the preflight first:

bash "${CLAUDE_SKILL_DIR}/../team/scripts/preflight.sh"

If FABLE_MODE comes back as anything other than duo-codex, switch to that loop (trio when Antigravity is also available and faster for the bulk work, duo-gemini, or orchestrate for solo) and tell the user why in one line. Never ask the user which engines they have.

Use this when, and only when

Worth the overhead:

  • The task splits into 2 or more units that can be worked on without seeing each other's output, or is one substantial coding job worth a dedicated session.
  • You can write acceptance criteria a command can settle.

Not worth it, do it yourself instead:

  • You could finish it in a handful of your own tool calls.
  • Requirements are still fuzzy. Dispatching an unclear spec produces confident wrong work, and you pay for it twice.
  • The task is one continuous judgment call, such as choosing an approach or reviewing a design.
  • It touches credentials, production data, or anything irreversible. Briefs go to an external service.

Roles, fixed, do not blur them

EngineCommandStrengthGive it
Claude (you)this sessionjudgment, verificationspec, decomposition, review, running the tests, final residual fixes only
Codexcodex execprecision codingevery implementation unit: features, refactors, bug fixes, tricky logic, tests, boilerplate, code and security audits

Codex is your only worker, so bulk and precision work both land on it. Split bulk into several units rather than one giant brief: parallel sessions finish sooner, and a failed unit then costs one narrow re-round instead of redoing everything. Assign units yourself; never ask the user which engine should take one.

Web research and audits of public web pages do not go to Codex here. Give them to this toolkit's researcher agent, which searches and fetches with Claude's own tools, and demand a source URL for every finding.

Keep for yourself anything that needs a product decision, a taste call, or that you cannot write a checkable criterion for.

The loop

Spec, dispatch, review, fix, final gate, report. Steps 3 and 5 are where the value is. Everything before them is setup for them.

0. Setup

  • Create the run dir <project>/.duo/<yyyyMMdd-HHmmss>/. Every brief, engine output, and review verdict lands here, so the loop is auditable after the fact.
  • If the project is a git repo, record git rev-parse HEAD and require a reasonably clean tree so review can lean on git diff. If it is not a repo, list the files that will change and copy them into the run dir as a snapshot so you can diff manually.
  • Never run git init at your home directory level.
  • Read the project's own agent instructions if they exist: CLAUDE.md, AGENTS.md, and the setup and deploy sections of the README. Anything a worker must respect (conventions, deploy steps, files that are off limits) goes into every brief's Project context. Codex starts cold and will not know it otherwise.

1. Spec (you)

Write spec.md in the run dir with four sections.

Goal. One sentence, outcome shaped.

Numbered acceptance criteria. This is the entire quality gate. Each criterion must be settled by a command you can run or an observation you can make. If you cannot name the command, the criterion is not ready.

Too vague to useCheckable
"the CSV export works""node export.js fixtures/sample.json writes out/report.csv with 1 header row and 42 data rows"
"clean up the styles""no file under src/ contains an inline style= attribute, and npm run lint exits 0"
"add tests""npm test passes, with at least one test per exported function in src/parser.js, and every test asserts on a return value"
"make it faster""time node bench.js reports under 400ms on the 10k row fixture, down from 2.1s"

Note what the third example does: it blocks the stub test failure mode in advance. Write criteria that forbid the shortcut you expect the engine to take.

Units and ownership. Split the work so no unit needs another unit's output. For each unit record its id, goal, the criteria it owns, and its file list.

The collision rule: every file has exactly one owning unit per round. Two Codex sessions editing the same file in parallel is the most expensive failure in this loop, because the review cannot tell you which write survived, only that the result is wrong. If two units both need a file, merge them into one unit or run them in separate rounds.

Boundaries. What must not be created, edited, or deleted by anyone.

2. Dispatch (parallel, background, through the Bash tool)

Each unit gets a cold start complete brief file in the run dir. Codex cannot see this conversation, cannot ask a question, and will invent anything you leave out. Use this template:

# Unit <id>: <one line goal>

## Project context
<two or three sentences: what this project is, what already works, why this unit exists, plus any
rule from the project's own CLAUDE.md or AGENTS.md that this unit must respect>

## Stack and conventions
<language, framework, test runner, how to run things, style conventions to match>

## Files you own
<absolute paths this unit may create or edit>

## Files you must NOT touch
<absolute paths owned by other units, plus anything off limits>

## Goal
<outcome shaped: produce X at path Y with property Z>

## Acceptance criteria (copied verbatim from spec.md)
1. <criterion>
2. <criterion>

## How to check your own work
<the exact commands to run, and what output means pass>

## Output contract
<exact paths and formats to deliver, and what to put in your final message>

## Report honestly
If anything failed or you skipped it, say so explicitly and include the actual error text.
Do not summarise around a failure. A disclosed failure is cheap to fix; a hidden one is not.
codex exec -C "<project>" --sandbox workspace-write \
  -o "<rundir>/codex-u1-round1.md" \
  "$(cat "<rundir>/brief-u1.md")" </dev/null
  • Capture the session id line Codex prints and record it in the run dir. Fix rounds resume that session, which preserves its context and is far better than starting cold.
  • Dispatch all independent units in the same message as parallel background calls. While they run, build the review checklist and write the commands you will use for each criterion.
  • For a read only unit, such as a code review, a security audit, or "find where X happens", use --sandbox read-only so it cannot touch the tree at all, and ask for every finding with its file and line.

3. Review (you, and this is the point of the whole skill)

Never accept an engine's claim. For every criterion, gather primary evidence yourself and record it in review-roundN.md as a table:

| # | Criterion | Verdict | Evidence |
|---|---|---|---|
| 1 | <criterion text> | PASS | `npm test` exit 0, 14 passed, 0 skipped |
| 2 | <criterion text> | FAIL | `node export.js fixtures/sample.json` -> "TypeError: rows is not iterable" at export.js:31 |

Evidence means the command you ran and its decisive output, or the file and line you read. "Codex said it works" is testimony, not evidence, and never fills that column.

Read the actual diff too, not just the test result. Look specifically for:

  • A test that runs but asserts nothing, or asserts on a hardcoded value.
  • A function that exists and is correct but was never wired into its caller.
  • An edited file that was not in that unit's ownership list.
  • A criterion quietly skipped while the report talks about the others.
  • An exception swallowed so a run exits 0.

4. Fix rounds

Any FAIL gets a fix brief that quotes the failed criterion and pastes the evidence, the real error text or the wrong output. An engine cannot fix what it cannot see.

codex exec resume <session-id> "$(cat "<rundir>/fixbrief-u1.md")" </dev/null

Escalate structurally, not by repetition:

RoundIf it still fails
1Fix brief with evidence, resumed into the same session.
2Change something real. Split the unit into two narrower briefs, or add the context the engine clearly lacked, or start a fresh session when the old one has gone down a bad path.
3Take it yourself and fix the residual.
after 3Report the criterion as failing.

Never loosen a criterion to make it pass. If the criterion was wrong, say that explicitly in the report and give the corrected one, rather than quietly editing the goalposts.

If the same unit fails twice for the same reason, the brief is the problem, not the engine. Rewrite the brief with the missing context instead of resending it.

5. Final gate, you prove the whole thing works

Mandatory, and it cannot be delegated to Codex. Per unit reviews confirm each piece passed in isolation. They say nothing about whether the assembled result works, and integration is exactly where parallel sessions break: two units that each passed can still disagree about a function signature, a schema, or a path.

Run all six checks before you tell the user anything is done:

  1. Exercise the real flow end to end, from a clean state. Start the app, run the script on real input, open the page in a browser, execute the CLI the way a user would. Not a unit test, not "the file was written".
  2. Re-run every acceptance criterion against the assembled deliverable, not against the per unit output you already reviewed.
  3. Open every file the spec promised, at the exact path it named. Existence is not correctness.
  4. Check the neighbours. Run the surrounding tests or drive the adjacent flow to confirm nothing that already worked is now broken.
  5. Confirm the boundaries held. git status and git diff --stat, or the manual snapshot diff, must show changes only in files the spec allowed. A session editing an out of scope file is a finding even when every criterion passes.
  6. Re-read the outputs for silent shortfalls, using the list in step 3 above.

If a check genuinely cannot be run, because of missing credentials, a missing environment, or a browser you do not have, write "written but not verified, because X" in the report. Never round an unrun check up to a pass, and never let Codex's own "I could not verify this" stand in for your verification.

For high stakes or irreversible work, additionally spawn a verifier agent with the claim and the paths but not your expected answer, then reconcile its verdict with yours before reporting.

6. Report

Outcome first, in prose. Cover what was built and where, every criterion with its final verdict and the evidence that settled it, rounds used per unit, anything NOT verified with the reason, and anything you had to fix yourself after round 3, since that is a signal about the spec. The "not verified" section is mandatory and never empty by default. Add one line naming which units Codex handled and which ran as Claude subagents.

Quota economy

Each dispatch is real spend on a subscription, so:

  • One dispatch per unit per round. No "just checking in" follow ups.
  • Batch small related work into one unit rather than five tiny dispatches.
  • Re-read a brief before sending it. Most wasted rounds trace to a missing path or an unstated convention, not to engine weakness.
  • Resume beats respawn. A resumed session already knows the codebase it just read.
  • Never dispatch work you have not written a criterion for. You will not be able to tell whether it came back correct, which makes the spend worthless.

Gotchas from real runs

  • codex exec hangs forever unless stdin is closed. Always append </dev/null and run it through the Bash tool. On Windows, PowerShell 5.1 has no < redirect, so the Bash tool is mandatory rather than a preference. This is the number one failure mode.
  • It needs network. If a dispatch produces no output for about two minutes, it is probably running inside a sandboxed shell. Rerun it unsandboxed.
  • Flags worth knowing: -C <dir> sets the working dir, --sandbox read-only|workspace-write, -o <file> captures just the final message, --skip-git-repo-check for non repo dirs, and resume <id> or --last to continue a session.
  • Codex's own sandbox often cannot run Python or your test suite, and it will honestly report that it could not verify. That is expected. Running the tests is your job as reviewer, not grounds for a fix round.
  • On Windows, Codex can fail every command with SetTokenInformation(TokenDefaultDacl) failed: 1344 when its sandbox cannot start inside the calling shell. --sandbox read-only units still work. For a write unit that hits it, an untested but low risk fallback: run it read-only, ask for the change as a unified diff in the final message, and apply that diff yourself with git apply.
  • Codex uses whatever model its own config names (for example gpt-5.6-sol in September 2026). Leave it alone unless a unit clearly needs another; -m <model> overrides it per dispatch.
  • Never put secrets or credentials in a brief. Briefs go to an external service.
  • Engines can silently do less than asked, skipping a file or stubbing a test. The review step exists because of this. Check every criterion, never a sample.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.