lucioway/way-stack/claudex-loop

Claudex-Loop — Recon, Interrogate, Review, Build

_(Renamed from Crucible 2026-08-16. Old trigger phrases still work.)_

Four phases, four failure modes killed:

• Phase 0 — RECON kills interviewing blind: Claude scouts the terrain (code or research) before asking you anything, so the interview starts informed instead of generic.
• Phase 1 — INTERROGATE kills building the wrong thing: Claude interrogates you until intent is locked — but only on decisions that are actually load-bearing.
• Phase 2 — REVIEW kills a plan that sounds right but breaks: a different model (Codex) attacks the locked plan. Cross-model = no echo chamber.
• Phase 3 — BUILD (optional) kills grading your own work: one model implements the locked plan, the rival model grades the diff — in both directions.

You enter at four points only: confirming the assumptions ledger, answering the fire, signing off the converged plan, and approving the final diff if you build. Codex is read-only throughout recon, interrogation, and review — no code is written until you sign off the converged plan.

PHASE 0 — RECON (Claude alone)

Before asking the user a single question, determine the terrain and gather what can be gathered without them.

Detect the terrain

• Brownfield — the working directory has real source code (not just scaffolding/config). Recon the codebase.
• Greenfield — empty dir, fresh scaffold, or the user is describing a brand-new project with no repo yet. There is nothing to recon; research replaces it.

Brownfield recon

1. Explore the codebase: architecture, relevant modules, existing patterns the plan must fit, current schema/auth/infra as applicable.
2. Look for living docs: CONTEXT.md (or CONTEXT-MAP.md for multi-context repos) and docs/adr/. If they exist, load them — the project has a ubiquitous language and prior decisions the plan must respect, and Phase 1 runs docs-aware (see below).
3. If the task involves tech or an integration the repo can't answer, open the research gate (below) before proceeding.

Greenfield recon

No code to read, so research carries the phase. Open the research gate, then cover:

1. Prior art — how do existing tools/products solve this? What's the standard shape?
2. Stack — reasonable default stack for this kind of project, with one alternative worth considering.
3. Known pitfalls — the 3-5 things people building this class of thing get wrong (search for postmortems, "lessons learned", common gotchas of the candidate stack).

The research gate (one question, asked at kickoff when external research would help)

Don't silently pick a research depth — offer the tiers with a recommendation based on stakes, and let the user choose:

• `none` — Claude's knowledge + codebase only. Right for medium tasks on familiar ground.
• `web` — a handful of targeted WebSearch passes (docs, gotchas, prior art). Minutes, not a project. The default recommendation for most greenfield work.
• `deep` — launch a deep-research dynamic workflow via the Workflow tool: a multi-agent research orchestration (parallel finder agents each searching a different way — prior art, stack landscape, pitfalls/postmortems, docs — then deep-read agents on the best sources, then one synthesis agent producing the brief). Heavy and token-expensive — recommend only for high-stakes greenfield, unfamiliar tech, or when the landscape itself is the question. The user choosing this tier IS the explicit opt-in the Workflow tool requires. Model pin: every agent() call in the research workflow MUST pass model: 'opus' (finders, deep-readers, and the synthesizer alike) — if the main session is on Fable, letting a dozen research agents inherit it annihilates token usage for what is mostly search-and-summarize work. Leave effort at the default — don't pass an effort override. Args gotcha (found in smoke test 2026-08-13): the workflow runtime may deliver args as a JSON-encoded STRING instead of an object — always open the script with const A = typeof args === 'string' ? JSON.parse(args) : args and reference A.*, or pipeline(args.questions, ...) dies instantly with "expects an array".

If invoked with research=none|web|deep, skip the question and use that tier.

If `deep` is chosen: draft the research prompt and get sign-off before launching. Show the user the topic framing + the 3-5 specific questions the assumptions ledger needs answered (not a generic "research X" — questions shaped like "what do teams building X get wrong about auth?" / "what's the current standard stack for Y and why?"). The user edits or approves, THEN author the workflow script with the approved questions as its args and run it. Save the synthesized brief to docs/research/YYYY-MM-DD-<slug>-claudex-research.md (or your notes location of choice, with ## Key Takeaways) — link it from the ledger entries it sourced and from PLAN.md.

Skill inventory scan (both terrains, after terrain detection)

Both benches carry installed skill packs. Enumerate and match against the task's domain:

• Claude side: list ~/.claude/skills/ (folder names + frontmatter description first lines are enough — don't read full SKILL.mds during recon).
• Codex side: list ~/.agents/skills/ (the skills CLI's Codex install target).

Filter to skills whose descriptions match the project's domain (e.g. a three.js game matches the threejs-* pack; an email feature matches resend skills). Record hits in the Assumptions Ledger as proposed toolchain entries, never auto-loads:

"threejs-game-skills pack installed on BOTH agents (9 skills incl. aaa-graphics-builder, gameplay-systems, 3d/image/audio generators) — proposing the build phase load graphics-builder + gameplay-systems, and the asset track use the generator skills. — source: skill inventory scan"

If a matched skill exists on only one bench, say which. If a Codex-side skill's loading behavior under headless codex exec is unverified, ledger that as an assumption to smoke-test before the build phase counts on it. Discovery informs the plan; nothing loads unless `PLAN.md`'s `## Toolchain` section names it and survives review.

Output: the Assumptions Ledger

End Phase 0 by presenting a single batch — NOT one-at-a-time — of everything Claude resolved on its own:

## Assumptions Ledger
_Confirm or correct in one pass. Anything unmarked I treat as confirmed._
1.<assumption> — source: <code path / doc / research finding / convention>
2....

Each entry cites its source. The user confirms/corrects in one reply. Corrections that open real questions get promoted into the Phase 1 decision map. This is the single biggest time-save over a naive grill: the interview never wastes questions on things the repo or the research already answered.

PHASE 1 — INTERROGATE (you ↔ Claude)

The interview. Rebuilt around one principle: every question must justify its own existence.

Open with the Decision Map

Lay out the tree of genuinely open decisions, tiered:

## Decision Map
### Load-bearing (asked one at a time)
-[ ] <decision> — irreversible / expensive-if-wrong (schema, auth, data model, concurrency, money, public API)
### Cosmetic (batched with defaults)
-[ ] <decision> — cheap to change later

Load-bearing = wrong answer costs a migration, a rewrite, a security hole, or user trust. Cosmetic = renameable, refactorable, swappable. Update the map as questions resolve (check items off, add branches corrections open) so the user can see convergence instead of wondering how many questions are left.

Load-bearing questions — one at a time, structured

Every question ships in this format:

Q<n>: <the question>

Why it matters: <the dependency or constraint that makes this load-bearing>

Recommendation: <Claude's answer, committed — not a menu>

If we guess wrong: <the concrete failure — migration, rewrite, breach, churn>

Wait for the answer before the next question. If drafting a question and the "if we guess wrong" line comes out weak — the question is cosmetic; demote it to the batch. If mid-interrogation a question turns out answerable from the code or the research, answer it yourself and log it to the ledger instead of asking.

Cosmetic decisions — one batch

Present the whole cosmetic tier as recommendations with a one-line rationale each. The user vetoes by exception; silence = accepted.

Escape hatch

At any point the user can say "accept all remaining recommendations" — Claude locks every open decision at its recommended answer, logs them as such in the plan, and proceeds. Offer it explicitly if the load-bearing tier exceeds ~8 questions.

Docs-aware mode (auto-on when Phase 0 found CONTEXT.md/ADRs; offer once on greenfield)

• Enforce the glossary — when the user's wording collides with a CONTEXT.md definition, stop and resolve it on the spot: quote the glossary's meaning, state the apparent meaning, make them pick.
• Pin down loose words — an overloaded or vague term gets a proposed canonical replacement before the conversation continues on top of it.
• Probe boundaries with scenarios — when two concepts blur, construct a concrete edge case that forces the line between them to be drawn.
• Check claims against the code — when the user asserts how something behaves, verify in the source; a mismatch is surfaced as a question, not silently trusted either way.
• Maintain `CONTEXT.md` as terms settle (format: CONTEXT-FORMAT.md). Glossary ONLY — never implementation details. Created lazily on the first settled term.
• Offer ADRs only past the three-part test — expensive to reverse AND puzzling without context AND a genuine trade-off. Format: ADR-FORMAT.md. docs/adr/ created lazily.

Lock the plan

When the decision map is fully checked and you're aligned, write `PLAN.md`:

# Plan: <task>
_Locked via claudex-loop — by Claude + <user>_
 
## Goal
<one paragraph — reflects what the interrogation actually settled>
 
## Approach
<numbered, concrete steps>
 
## Key decisions & tradeoffs
<the contestable choices the interrogation resolved — name them so Codex has something to bite; link any ADRs; mark any locked via the escape hatch>
 
## Toolchain
<only when the skill inventory scan matched something — which installed skills each build track MUST load and follow, per agent (Claude / Codex), plus any generator skills or MCP capabilities the build depends on. Omit the section entirely on no matches. Reviewable like everything else: Codex should attack unused relevant skills and unjustified inclusions alike>
 
## Assumptions
<the confirmed ledger — with sources>
 
## Risks / open questions
<anything still genuinely open>
 
## Out of scope
<bounds the interrogation established>

Initialize PLAN-REVIEW-LOG.md:

# Plan Review Log: <task>
Phases 0-1 (recon + interrogation) complete — plan locked with the user. MAX_ROUNDS=<n>.

PHASE 2 — REVIEW (Claude ↔ Codex)

Hand the locked plan to Codex for adversarial review. Mechanics verified end-to-end (2026-06-04) — do not "improve" the invocations below.

Prerequisites (verify once, fast)

• codex --version ≥ 0.130 (older CLIs error on the default gpt-5.5 model).
• Codex authenticated (prior codex login; ChatGPT account is fine). On auth/model error, surface it — don't silently retry.
• Do NOT pin -m. Use the config default. Pinning gpt-5.x-codex variants 400s on ChatGPT-account auth.
• Echo the active model before Round 1 so the user can confirm: read the model line from ~/.codex/config.toml (if absent, report "CLI default"). State it alongside the resolved tunables, e.g. Reviewer model: CLI default (config unpinned) — codex-cli 0.137.0. If the user objects, stop and let them adjust config before burning a review round.