| name | writing-codex-briefs |
| description | Use when composing the task brief and acceptance criteria for a Codex dispatch (invoked from dispatching-to-codex). Covers the self-contained brief format and how to write acceptance checks that actually protect you — weak checks are the sneakiest way a dispatch goes wrong. |
Writing Codex Briefs
Codex sees zero chat history. The brief is the only channel. Anything not in it does not exist for Codex.
The Acceptance File — .codex/ACCEPTANCE.md
Written and committed BEFORE dispatch. This is the frozen bar the judge will enforce.
GOAL: <one sentence: what "done" means>
CHECKS (all must pass, exact commands):
- `<command>` exits 0 and prints <expected>
- `<build/typecheck command>` exits 0
- `<specific test command>` exits 0
CONSTRAINTS:
- Only edit <files/dirs>. Do not modify <test files / this file / unrelated code>.
Writing checks that protect you (the judge is only as strong as these):
- Prefer commands with exit codes over "the code should look right".
- Include at least one check that fails before the work is done (red → green) — a check that passes on the untouched repo proves nothing.
- Name the specific tests, not "run the tests" (slow suites make the judge cry wolf; flaky checks are worse than none).
- Vacuous bars ("typecheck passes") let bad work through with a green light. Ask: could a lazy stub pass these checks? If yes, tighten them.
The Brief
GOAL: <same one sentence — must match ACCEPTANCE.md>
CONTEXT: <repo path, key files, constraints — everything Codex needs, it cannot ask you>
DO: <numbered, concrete steps>
VERIFY: <run the exact CHECKS above and show their real output>
REPORT: <what to return: diff summary + which checks passed>
DO NOT: commit anything; touch .codex/ACCEPTANCE.md; edit unrelated files;
delete or weaken tests; add silent fallbacks or fake/stubbed results.
The DO NOT block is mandatory and always includes those five items — they are the exact ways executor models paper over failure.
Common Mistakes
- Context by reference ("as discussed above") — Codex has no "above". Inline it.
- Goal drift — brief GOAL ≠ ACCEPTANCE GOAL means the judge enforces a different bar than Codex aimed at.
- Kitchen-sink briefs — one dispatch, one goal. Two unrelated goals = two dispatches.
