grill-with-docs-codex

name

grill-with-docs-codex

description

Two-act plan hardening with living documentation. ACT 1 (you ↔ Claude) — Claude interviews you relentlessly about a plan, one question at a time, challenging it against your project's existing domain model and glossary (CONTEXT.md), sharpening fuzzy terms, stress-testing with concrete scenarios, cross-referencing code, and updating CONTEXT.md + ADRs inline as decisions crystallise. ACT 2 (Claude ↔ Codex) — Claude writes the locked plan to PLAN.md and OpenAI Codex adversarially reviews it in a read-only sandbox (VERDICT:APPROVED/REVISE), Claude revises and re-submits to the SAME Codex session until APPROVED or a MAX_ROUNDS cap, then you sign off before any code. Use when the user says "/grill-with-docs-codex", "grill me against the docs then have codex review", "stress-test this against our domain model then get a second model on it", or is about to build something high-stakes in a project with established terminology/ADRs and wants alignment, documentation, AND a cross-model sanity check. Builds on Matt Pocock's grill-with-docs (MIT). NOT for reviewing already-written code (use /codex:review) and NOT for trivial changes.

Grill-with-Docs-Codex — Grill Against Your Domain, Then Get Reviewed

Two acts. Act 1 aligns intent and keeps your living docs honest; Act 2 has a different model attack the result.

• Act 1 is Matt Pocock's grill-with-docs, used under MIT (see THIRD-PARTY-NOTICES.md). It interrogates you, challenges your plan against CONTEXT.md/ADRs, and updates them inline.
• Act 2 is the original Codex adversarial review loop — cross-model, read-only, bounded.

You enter at two points: answering the grill, and signing off the converged plan.

---

ACT 1 — GRILL WITH DOCS (you ↔ Claude)

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question before continuing.

If a question can be answered by exploring the codebase, explore the codebase instead.

Domain awareness

During codebase exploration, also look for existing documentation:

File structure

Most repos have a single context:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts. The map points to where each one lives:

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

Create files lazily — only when you have something to write. If no CONTEXT.md exists, create one when the first term is resolved. If no docs/adr/ exists, create it when the first ADR is needed.

During the session

Challenge against the glossary

When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

Cross-reference with code

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

Update CONTEXT.md inline

When a term is resolved, update CONTEXT.md right there. Don't batch these up — capture them as they happen. Use the format in CONTEXT-FORMAT.md.

CONTEXT.md should be totally devoid of implementation details. Do not treat CONTEXT.md as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.

Offer ADRs sparingly

Only offer to create an ADR when all three are true:

1. Hard to reverse — the cost of changing your mind later is meaningful
2. Surprising without context — a future reader will wonder "why did they do it this way?"
3. The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons

If any of the three is missing, skip the ADR. Use the format in ADR-FORMAT.md.

Handoff to Act 2

When the decision tree is resolved, the glossary/ADRs are updated, and we're aligned, write the agreed plan to PLAN.md (use the canonical terms from CONTEXT.md), then run Act 2:

# Plan: <task>
_Locked via grill-with-docs — by Claude + <user>. Terms per CONTEXT.md._

## Goal
<one paragraph, in the project's ubiquitous language>

## Approach
<numbered, concrete steps>

## Key decisions & tradeoffs
<the contestable choices the grill resolved — link any ADRs created>

## Risks / open questions
<anything still open>

## Out of scope
<bounds>

Initialize PLAN-REVIEW-LOG.md:

# Plan Review Log: <task>
Act 1 (grill-with-docs) complete — plan locked, CONTEXT.md/ADRs updated. MAX_ROUNDS=<n>.

---

ACT 2 — REVIEW (Claude ↔ Codex)

Hand the locked plan to Codex for adversarial review. Mechanics verified end-to-end (2026-06-04).

Prerequisites

• codex --version ≥ 0.130 (older CLIs error on the default gpt-5.5 model).
• Codex authenticated (codex login; ChatGPT account fine). On auth/model error, surface it — don't silently retry.
• Do NOT pin -m (config default is used; gpt-5.x-codex variants 400 on ChatGPT-account auth).
• Echo the active model before Round 1 so the user can confirm: read the model line from ~/.codex/config.toml (absent = "CLI default"); state it with the resolved tunables. If the user objects, stop before burning a round.

Tunables (args, else default)

Var	Default	Meaning
MAX_ROUNDS	5	Hard cap. Loop ALWAYS terminates here.
PLAN_FILE	PLAN.md	The plan from Act 1.
LOG_FILE	PLAN-REVIEW-LOG.md	Append-only argument transcript.

Invoked with e.g. rounds=3 → use it. Echo resolved values first.

Review prompt (each round)

You are an adversarial reviewer for an implementation plan. Be skeptical and specific — your job is to find what breaks, not to be agreeable. Read the plan at PLAN.md (and CONTEXT.md/ADRs for the domain language) and any repo files you need (you are read-only). Identify concrete flaws: security holes, race conditions, missing edge cases, schema conflicts, domain-language mismatches, wrong assumptions, observability gaps, simpler alternatives. For each, give a one-line fix. Do NOT modify any files. End with EXACTLY one line: VERDICT: APPROVED or VERDICT: REVISE.

Round 1 — fresh session (capture thread_id)

codex exec -s read-only --json -o /tmp/codex-verdict.txt "$(cat REVIEW_PROMPT)" \
  < /dev/null 2>/dev/null | grep '"type":"thread.started"'

Parse thread_id from the thread.started line. Critique in /tmp/codex-verdict.txt. No verdict file + no thread.started = failed run (auth/model) → stop, tell the user. 2>/dev/null hides cosmetic MCP/auth noise. < /dev/null is mandatory: codex exec reads stdin in addition to the prompt arg, so under a non-interactive driver (Claude Code's Bash tool, CI, any non-TTY pipeline) it blocks forever waiting on stdin EOF — a silent ~0% CPU hang. The redirect gives it immediate EOF.

Rounds 2..MAX — resume SAME session

# resume REJECTS -s. Force read-only via -c sandbox_mode, or Codex inherits
# config.toml (possibly danger-full-access) and could WRITE files. Critical
# safety line — verified 2026-06-04.
codex exec resume "$THREAD_ID" -c sandbox_mode="read-only" --json \
  -o /tmp/codex-verdict.txt \
  "I revised the plan. Re-review PLAN.md — check prior findings + flag anything new. End with VERDICT: APPROVED or VERDICT: REVISE." \
  < /dev/null 2>/dev/null >/dev/null

The < /dev/null redirect is required on the resume call too — same non-interactive stdin hang as Round 1.

Timeout guard (both rounds): run every codex exec / codex exec resume with a 10-minute ceiling so any future stall fails loud instead of hanging silently. Via Claude Code's Bash tool, pass timeout: 600000 on the tool call (the default 2-minute tool timeout is too short for real reviews and would kill them mid-run). In a plain shell, prefix the command with timeout 600 (Linux / Git Bash) or gtimeout 600 (macOS via coreutils — stock macOS has no timeout). If the ceiling trips, treat it as a failed run: stop and tell the user rather than retrying blind.

Each round

1. Read verdict file; append ## Round <n> — Codex + critique to LOG_FILE.
2. Last line verdict: APPROVED → Resolution (converged); REVISE → Claude decides what's worth acting on (final arbiter), revise PLAN_FILE, append ### Claude's response (what changed/rejected + why), increment.
3. round > MAX_ROUNDS → Resolution (deadlock).

Resolution (you sign off)

• APPROVED: present final plan + 3-bullet summary of what the two acts improved + round count. Ask: implement now — Codex builds it (/codex-build), Claude builds it, or stop? No code during either act.
• Deadlock (cap hit, no APPROVED): list unresolved points + Claude's counter-position; hand to user. Don't fake convergence.
• Act 3 (optional): user picks Codex → invoke the codex-build skill with SPEC_FILE=PLAN.md and the same LOG_FILE. Roles flip: Codex writes with full access, Claude reviews the diff + runs the proof; build rounds append to the same log.

---

Hard rules

• Act 1 precedes Act 2. CONTEXT.md stays a glossary only — no implementation details.
• Codex read-only EVERY round (-s read-only first, -c sandbox_mode="read-only" on resume — resume has no -s). Never writes.
• Loop ALWAYS terminates at MAX_ROUNDS. Claude is final arbiter on REVISE (reject with logged reason). Code only after sign-off. LOG_FILE is the deliverable.

What NOT to do

• Don't review already-written code (/codex:review). Don't pin -codex variants on ChatGPT auth. Don't let Codex edit files. Don't skip Act 1.