Cvg Hybrid Plan Loop

Hybrid Plan Loop

Run cvg-plan-loop with a fixed engine split: the planner runs on a high-taste Claude design model, and every fresh plan reviewer runs in a Codex CLI session. The design model's scarce quota is spent only where taste has leverage — drafting and revising the plan; review rounds burn the cheap engine. Cross-model review is also a feature: a different model family reviewing the plan exposes blind spots same-model self-review tends to share.

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 the repo and writing their /tmp/convergo findings and audit artifacts.

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 | | --- | --- | --- | | Design tier | Claude fable via the Agent tool model parameter | planner, plan revisions | | Execution tier | codex exec -m gpt-5.6-sol at model_reasoning_effort=high — the current frontier codex pin, updated with plugin releases | fresh plan reviewers |

Before the first spawn, echo the resolved bindings in one line — planner model, reviewer engine and 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: cross-model review only pays if the reviewing engine is near-peer.

Procedure

Apply the cvg-plan-loop skill in full — same phases, protocol gates, callback templates, and exit condition — with these routing overrides:

1. Planner (Phase 1): spawn as a native background specialist with the

design-tier model. Everything else about the planner prompt is unchanged.

1. Fresh plan reviewers (Phase 2 and every later fresh review): spawn as

codex-backed specialists (pattern below) with role skill cvg-plan-review.

1. Plan review feedback: unchanged — blockers return to the same

design-tier planner session with cvg-plan-review-feedback.

1. Exit: unchanged — a fresh execution-tier reviewer reporting no

blocking findings.

codex exec sessions expose a subagent primitive (collaboration.spawn_agent — verified live): instruct codex plan reviewers to dispatch their auxiliary personas through it and record the returned child ids. Inline coverage marked inline in the callback remains cvg-plan-review's documented fallback and stays valid for plan reviews; do not treat it as a blocker or ask the wrapper to relaunch codex to force real dispatch.

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 repo 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;

1. launch codex exactly once as a background Bash command

(run_in_background: true — codex runs routinely outlast the single foreground Bash timeout) from the repo named in the specialist prompt, with the final message written to a file and the run header captured: codex exec -m -c model_reasoning_effort="" -o /last-message.txt "" > /run-header.log 2>&1 /codex.pid; wait "$(cat /codex.pid)" (binding values from Engine Bindings, or the user's override; the pid file is what the orchestrator's watcher probes for liveness). ` is a per-specialist directory the orchestrator names in the specialist prompt, under the loop's /tmp/convergo//` tree. Convergo passes no sandbox or permission flags: the session runs with whatever the user's codex configuration grants, and the reviewer's read-only conduct is a contract line in its role skill;

1. end its turn immediately after the launch, with an ARMED callback

naming the paths: ARMED. Codex running. Output: /last-message.txt. Header: /run-header.log. Do not wait for codex in-turn and do not poll: completion notices queue in a stopped wrapper's transcript without waking it (verified live), and the orchestrator owns the waiting — see the watcher below;

1. when the orchestrator messages it to relay, read the -o file and

relay its content verbatim as its own final message, appending one line: Codex session: (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 /last-message.txt ] && { echo DONE; exit 0; }; p=$(cat /codex.pid 2>/dev/null); [ -n "$p" ] && kill -0 "$p" 2>/dev/null || { echo DIED; exit 0; }; sleep 5; done; echo TIMEOUT

(Liveness is probed through the pid file, never by matching command lines: host hooks inject text into every shell's argv, which makes pgrep-style patterns self-match or miss unpredictably — verified live. kill -0 on the recorded pid is argv-independent.)

Its completion wakes the orchestrator. On DONE or DIED, SendMessage the wrapper to relay now; the wrapper applies the source-of-truth rule above. On TIMEOUT (two hours), escalate to the user. A background watcher that exits when its condition holds is the platform's own single-completion shape — it is not in-turn waiting.

Fast path: when codex completes while the wrapper is still in its launch turn (the completion notice arrives in-turn), the wrapper relays immediately instead of ARMED. A relay-shaped first callback — payload plus Codex session: line — is the result; skip the watcher.

• 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

launches codex exec resume -c model="" -c model_reasoning_effort="" -o /last-message-.txt "" > /run-header-.log 2>&1 /codex.pid; wait "$(cat /codex.pid)" as a background Bash command and ends its turn ARMED again with the new paths; the orchestrator arms a fresh watcher on the new output file. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gomilesf
• Source: gomilesf/convergo
• License: MIT

Install and usage instructions live in the source repository linked above.