cvg-hybrid-build-loop git:20260712.2b7be53A

Immutable. This exact content is served forever at /api/v1/blob/7f821502e899a14f.

---
name: cvg-hybrid-build-loop
description: Orchestrate the build loop with split engines - Codex CLI sessions implement and take every first-pass review round while a high-taste Claude design model holds the final exit gate. Use when the user asks for a hybrid, split-model, or cross-model build loop, such as codex implementing with fable as the closer or final reviewer. Claude Code only.
argument-hint: "[plan path, plus optional engine overrides]"
---

# Hybrid Build Loop

Run `cvg-build-loop` with a tiered engine split: a Codex CLI session
implements, Codex CLI sessions take every first-pass review round, and a
high-taste Claude design model reviews only when the execution tier already
believes the work is clean. The design model is the exit gate inside the
protocol, not a closer bolted on after the loop: its blockers re-enter the
normal feedback cycle.

## Prerequisites

- Claude Code as the orchestrating platform: the `Agent` tool `model`
  parameter and `SendMessage` continuation are required.
- A working `codex` CLI (`codex --version` succeeds) with the convergo codex
  plugin installed, so codex sessions can load role skills by name.
- Codex sessions run with whatever permissions the user's own codex
  configuration grants. Convergo passes no sandbox or permission flags;
  roles assume normal developer access — reading and writing the repo,
  committing, and running the project's build and test commands.

If either prerequisite fails, stop and report it. Do not silently fall back
to a single-engine loop; the user chose this skill for the split.

## Engine Bindings

Defaults; the user's invocation may override either tier.

| Tier | Default | Runs |
| --- | --- | --- |
| Execution tier | `codex exec -m gpt-5.6-sol` at `model_reasoning_effort=high` — the current frontier codex pin, updated with plugin releases | worker, first-pass fresh reviews, QA workers |
| Design tier | Claude `fable` via the `Agent` tool `model` parameter | final-fresh-exit reviews |

Focused re-reviews always return to the reviewer session that raised the
findings, on whichever tier that session lives — unchanged protocol.

Before the first spawn, echo the resolved bindings in one line — worker
model and effort, reviewer engine, design-tier model, round cap — so a
binding mistake surfaces before any specialist runs. If codex rejects the
pinned execution-tier model (a retired id), fall back to the model the
user's codex config resolves to — respawn the specialist wrapper with the
model pin dropped, initial `-m` and resume `-c` overrides both — echo what
actually ran (the `model:`
line of the run header, never an assumption), and flag it to the user if
it sits below a frontier model at high reasoning effort: the tier split's
economics assume execution is nearly as capable as the design tier.

## Procedure

Apply the `cvg-build-loop` skill in full — same phases, protocol gates,
callback templates, and round cap — with these routing overrides:

1. **Worker (Phase 1):** codex-backed specialist (pattern below), role
   skill `cvg-work`.
2. **Fresh code review (Phase 2):** codex-backed specialist (pattern
   below), role skill `cvg-code-review`. Codex
   sessions run through
   `codex exec`, which has no generic subagent primitive, so expect
   auxiliary persona coverage to run inline (the role skill's documented
   fallback). Inline coverage is valid for first-pass reviews; it can never
   satisfy the final-fresh-exit condition, which is one more reason the
   final gate below is a native design-tier specialist.
3. **Feedback (Phase 3):** unchanged — blockers return to the codex-backed
   worker with `cvg-code-review-feedback`.
4. **Tiered exit (Phase 5 override):** a clean execution-tier fresh review
   never exits the loop; it is a promotion. Spawn the
   `Review mode: final-fresh-exit` reviewer as a native design-tier
   specialist (`model: "fable"`, role skill `cvg-code-review`).
   - Design-tier review clean: the loop exits.
   - Design-tier blockers: normal Phase 3 feedback to the worker, focused
     re-review by the same design-tier session, and on pass the next fresh
     first review starts again at the execution tier before the next
     promotion.
   - Every feedback-repair-re-review-fresh-review cycle counts as one round
     against the cap, regardless of which tier raised the blockers.
5. **Design-tier cost control:** in the design-tier reviewer prompt, instruct
   that auxiliary persona subagents be spawned on a cheaper Claude model (for
   example `model: "opus"`); synthesis and the verdict stay on the design
   tier.
6. **QA (Phase 6):** execution tier.

## Cross-Repo Plans

One loop drives one worker in one repo. A plan whose slices or invariant
matrix span multiple repos is NOT completed by one loop. When Phase 0 finds
more than one repo in scope:

- declare the repo split and build order to the user before spawning the
  worker (the contract-source repo usually goes first), including which
  slices are runnable in parallel rather than blocked;
- scope this loop and its reviewer prompts to that one repo's slices;
- after this loop exits, the remaining repos' slices are open work — launch
  the next repo's loop or hand the sequencing decision to the user;
- never present a single-repo exit as plan completion: the completion
  summary must list every repo the plan names that this loop did not cover
  as blocking known gaps.

## Codex-Backed Specialist Pattern

A codex-backed specialist satisfies the real-specialist gate (real,
addressable, continuable) by wrapping a Codex CLI session in a thin
background Claude agent:

- Spawn a background agent on a cheap model (`model: "sonnet"`), **without
  worktree isolation** — codex must run in the worktree named in the
  specialist prompt, and an isolated wrapper worktree can be reclaimed out
  from under a still-running codex process. Its prompt instructs it to:
  1. compose one self-contained codex prompt from the specialist prompt it
     received — role skill to load, artifact paths, refs, boundaries, and the
     exact callback template; nothing else;
  2. launch codex exactly once as a background Bash command
     (`run_in_background: true` — codex runs routinely outlast the single
     foreground Bash timeout) from the worktree named in the specialist
     prompt, workers and reviewers alike, with the final message written
     to a file and the run header captured:
     `codex exec -m <execution-model> -c model_reasoning_effort="<effort>"
     -o <scratch>/last-message.txt "<prompt>"
     > <scratch>/run-header.log 2>&1` (binding values from Engine
     Bindings, or the user's override). `<scratch>` is a per-specialist
     directory the orchestrator names in the specialist prompt, under the
     loop's `/tmp/convergo/<loop-slug>/` tree. Convergo passes no sandbox or
     permission flags: the session runs with whatever the user's codex
     configuration grants, and role boundaries (a reviewer does not modify
     the repo) are contract lines in the role skills;
  3. stay in-turn and wait with repeated bounded foreground wait commands,
     rerun until the file lands:
     `for i in $(seq 1 100); do [ -s <scratch>/last-message.txt ] && { echo
     READY; exit 0; }; sleep 5; done; echo RERUN-THIS-WAIT`.
     `RERUN-THIS-WAIT` is an instruction, not a status: immediately run the
     same wait command again, for as long as the codex process is alive.
     The wrapper must NOT end its turn to wait for a wake-up: a stopped
     background specialist is not re-invoked when its background command
     exits, and the run becomes an orphan until someone nudges the wrapper.
     Do not hand the run to any separate background task queue;
  4. once READY, relay the `-o` file's content verbatim as its own final
     message, appending one line: `Codex session: <session-id>` (grep
     `session id:` from the run header log).

The `-o` file is the source of truth, not the exit code. Codex can exit
nonzero after a completed run (shutdown or hook noise), so a "command
failed" report with a non-empty `-o` file still means success — relay it.
Never relaunch codex because of the exit code alone; treat the run as
failed only when the process has exited and the `-o` file is still empty,
and then relay the tail of the run header log as a failure callback
instead of retrying. Append `</dev/null` to the codex command so it never
waits on stdin.

If a wrapper does stop early anyway, it is recoverable: `SendMessage` it to
relay now — the resumed wrapper reads the `-o` file and finishes.
- The wrapper agent id from the `Agent` tool result is the specialist id.
  Record the codex session id beside it for continuation.
- Continue the specialist with `SendMessage` to the same wrapper; the wrapper
  resumes the recorded codex session with
  `codex exec resume <session-id> -c model="<execution-model>"
  -c model_reasoning_effort="<effort>" "<follow-up>"` and relays the result
  verbatim again. The `-c` re-pin is load-bearing: `resume` does not accept
  `-m` and re-resolves model parameters from the user's codex config,
  silently dropping the first run's pin (verified live: a session launched
  at `low` effort resumed at the config default without the override).
- The wrapper must not read the repo, run other commands, review, summarize,
  or filter codex output. Relay fidelity is its whole job.

## Why the Exit Is Tiered

No one can know in advance which fresh review will be the last one, so the
scarce design model cannot simply "take the final round". Instead the exit
condition itself is two-level: an execution-tier clean review is necessary
but never sufficient, and only a clean design-tier `final-fresh-exit` review
ends the loop. The design model therefore runs exactly when the cheap engine
believes the work is done — typically once or twice per loop.