convergo

Convergo

Plan → review → build loops for coding agents — that actually terminate.

Quick Start · Why · How It Works · Hybrid Loops · Skills · Install

Agent-written code needs review, and agent review needs a loop: find issues, fix them, review again. The dirty secret is that this loop often doesn't converge — each round adds patches, prose, and pseudo-code instead of closing in on done. Convergo is a plugin that bounds that loop by construction. The original user outcome anchors scope. One independent full review is followed by focused repair checks; a clean recheck can finish the review. Further full reviews need material change, new evidence or an explicit requirement. Three repair rounds without resolving real blockers stop with an honest unfinished result.

It is a convergence-focused fork of Compound Engineering: CE gets the plan-first, review-everything shape right; Convergo makes the loops terminate.

Built for correctness-critical, reviewable work with AI coding agents. Not for quick spikes or throwaway prototypes — see Cost and Fit.

Quick Start

Claude Code — everything ships with the plugin:

/plugin marketplace add gomilesf/convergo
/plugin install convergo

Codex and every other host: see Install — every host is a single plugin install.

Then, in a repo with an issue to work on:

/cvg-plan-loop create a plan for issue #42
... review the plan yourself ...
/cvg-build-loop docs/plans/42-plan.md

Why Convergo Exists

An unbounded agent review loop can fail to settle — and the failure mode is not "the reviewer found a bug" (that's the loop working). The failure mode is divergence:

• Plan review discovers one symptom per round instead of the missing surface, invariant, or behavior decision underneath them all.
• The planner responds by adding more text instead of repairing the plan's structure.
• Code review pushes the worker into local patches even when the finding is really a plan gap, a contract gap, or a systemic design gap.
• Every round makes the artifact larger, vaguer, and more likely to accumulate pseudo-code — which spawns a new class of review findings.

One missing invariant across eight surfaces should become one plan repair, not eight rounds of local patches. Convergo's rules exist to force exactly that.

What a Run Looks Like

/cvg-build-loop docs/plans/rate-limit-plan.md on Claude Code, condensed:

orchestrator  records base commit and worktree state,
              spawns a WORKER session with the plan, ends its turn (no polling)

worker        implements behavior slices with regression evidence,
              keeps impl notes for the reviewer
              -> "Implementation round complete. Base a1b2c3, head d4e5f6.
                  Verification: 41 tests pass. Known gaps: none."

orchestrator  spawns a FRESH REVIEWER session

reviewer      checks original intent + plan + diff, selecting auxiliaries
              only for relevant risk or required independent coverage
              -> "Not ready. F1 (P1): retry path drops the rate-limit header.
                  F2: plan never decided burst behavior — contract gap."

orchestrator  adjudicates scope/severity against the goal and evidence,
              returns original findings + reasons to the SAME worker

worker        intake first, then repair: F1 is implementation-owned -> fixes it
              F2 needs a product decision -> pauses dependent work and reports
              while independent authorized work continues

planner       resolves source-backed omissions; asks you only if a real
              product or risk decision is missing

worker        finishes the repair -> new head commit

reviewer      (same session) focused re-review of the fixes -> pass

orchestrator  confirms required acceptance and original intent are satisfied,
              exits with the review result and any non-blocking P2 notes

Feedback preserves the original goal, the actor considers removing unnecessary mechanisms before adding patches, and focused verification can close the loop.

The Rules That Make It Converge

Every rule below is written into the skills, not just described here. What can be machine-checked is — the findings schema is validated per finding, and the generated platform builds are byte-checked by tests; the behavioral rules are prompt contracts, exercised end-to-end by the release smoke test.

Original intent governs the plan. The user outcome, explicit non-goals, authorized changes and current product/safety constraints govern scope. Candidate surfaces are investigated before becoming requirements. Completion checks for omissions, unnecessary additions and changed semantics.

Consider removal before adding machinery. Before a materially new mechanism or a repair, identify what required behavior fails without it. Removing a cache, state or accidental capability may eliminate an entire failure class. Use an isolated ablation experiment only when uncertainty warrants it; keep necessary protections. This adds no mandatory artifact or review round.

Feedback goes through evidence-based intake. The orchestrator can adjudicate scope and severity, preserving original findings and reasons. Workers repair implementation; planners revise plans. Only dependent work pauses for a material unresolved decision. Ordinary technical omissions do not automatically require another user approval.

Findings carry evidence, not vibes. Sub-reviewers return findings against a shared schema: P0–P3 severity, discrete confidence anchors, a quote-the-line gate for high-confidence claims. Low-confidence findings are dropped at merge unless they are critical, and P3 style findings are never emitted at all — style belongs to tooling, not the loop. Reviewers run under a fresh-review evidence boundary — no project memory, no prior sessions, no rollout history; only the plan, the diff, and the repo. The worker's impl notes are the one deliberate exception: they ship with the diff so the reviewer sees declared deviations, assumptions, and accepted gaps. The notes carry decisions, never review provenance — no round numbers, finding IDs, or fix-status claims — so a fresh reviewer inherits the decision record, not the previous reviewer's search map.

Independent review has a stable exit. A complete independent review and any needed focused rechecks can satisfy the gate. A new full pass needs material change, new evidence or an explicit requirement. Required signatures and actual acceptance cannot be replaced by inline checks or a green build.

The loop is capped. Each substantive repair plus recheck counts, including repeated fixes by the same reviewer. The default is three; changing roles or models does not reset it. Settled findings cannot re-block without new evidence, including at a final gate. Remaining P2 notes do not cause another loop; real unresolved blockers mean unfinished work, not success at the cap.

One loop covers one repo. The loop's base/head and diff bookkeeping spans a single repo, so changes outside it would escape review. When a plan's slices span multiple repos, the orchestrator declares the repo split up front, runs one loop per repo, and reports every uncovered repo as a blocking known gap — a single-repo exit is never presented as plan completion.

Plans are right-sized decision artifacts. /cvg-plan classifies complexity first (brief / standard / full); only cross-cutting work gets the full surfaces + invariant-matrix treatment. Plans never contain code. Open behavior decisions that bind multiple slices go into a behavior contract rather than being invented downstream.

The loop asks for material decisions. The build loop starts only when you explicitly trigger it on a reviewed plan — this gate is where your judgment counts most: check that the behavior contract records decisions you actually want, that each slice's "done when" is verifiable, and that the invariant matrix covers every surface you know about. Mid-loop, source-backed omissions return to the planner; only a missing product choice, new risk or broader authorization needs you. If the cap is reached with real blockers, the report names what remains and the smallest next step.

Two Ways to Use It

Standalone skills (any supported host): drive each step yourself. With no orchestrator, the skills route blocking questions to you directly.

/cvg-plan -> /cvg-plan-review -> (fix via /cvg-plan-review-feedback)
-> /cvg-work -> /cvg-code-review -> (fix via /cvg-code-review-feedback)

Orchestrated loops (Claude Code and Codex): the session becomes an orchestrator that spawns and supervises real specialist sessions.

discuss goal
-> /cvg-plan-loop        planner <-> independent review and focused rechecks
-> human reviews and questions the plan
-> /cvg-build-loop       worker <-> independent review and focused rechecks
-> required QA gates, if any
-> done

The loop skills share one protocol (cvg-multi-session), bound to the host platform before anything else runs: Codex specialists are native Desktop tasks; Claude Code specialists are background agents. Each platform's build ships only its own transport mechanics — the copies under plugins/codex and plugins/claude are generated from one canonical source. Specialist identity always comes from the platform response, never from the specialist's own prose. Repair rounds reuse the same worker, focused re-reviews reuse the same reviewer, and only a full fresh review creates a new task.

Codex repository specialists use Desktop create_thread with a native project worktree. Repairs and focused checks use send_message_to_thread on the same task; wait_threads and heartbeat handoffs monitor completion. A callback is both sent to the orchestrator task and retained as the specialist's final answer for recovery. Convergo does not start a standalone App Server or introduce a second task writer.

Full Access is intentionally broad local authority. The release smoke verifies that native project-worktree creation and same-task continuation both retain approval_policy=never and sandbox_policy.type=danger-full-access without an approval prompt. Run orchestrated Codex loops only in trusted worktrees. Review gates and role boundaries remain contractual rather than sandbox boundaries.

On Claude Code there is a third option: the same loops with a split-engine routing — see Hybrid Loops.

Hybrid Loops: Fable Plans, Codex Builds

(Claude Code only.) The loop protocol doesn't care which model plays which role — the two hybrid presets pin a deliberate split that matches today's model economics: Claude Fable has the best taste and judgment but scarce quota; GPT-5.6 Sol through the Codex CLI at high reasoning effort is nearly as capable at execution and effectively free at typical subscription limits. So the presets spend Fable only where judgment has leverage, and let Codex burn every iteration. These are defaults, not hardcoded — any invocation can override either engine.

Role	Engine	Why