Agent-Skills.md

Agent Skills: Convergence Engine

|

UncategorizedID: ekson73/multi-agent-os/convergence-engine

Repository

ekson73/multi-agent-os
ekson73License: MIT

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ekson73/multi-agent-os/tree/HEAD/skills/convergence-engine

Skill Files

Browse the full folder contents for convergence-engine.

Download Skill

Loading file tree…

skills/convergence-engine/SKILL.md

Skill Metadata

Name
convergence-engine
Description
|

Convergence Engine

A thin deterministic-harness × probabilistic-cognition kernel. The Convergence Engine does not re-implement convergence, critique, scoring, or escalation — it composes primitives that already live in this repo, behind a small set of non-negotiable rules that make iterative self-improvement raise quality instead of corroding it.

Principle (the synthesis): best result = deterministic scaffolding (scripts · hooks · guard-rails · round-caps — cheap, f=0, ~zero-token, amnesia-proof, repeatable) bounding and verifying probabilistic cognition (judgment — expensive, fallible, where the value is created). Deterministic skeleton, probabilistic muscle.

Purpose

Drive a result to high quality via bounded iterative review (not one shot) by composing existing primitives under rules that make self-improvement raise quality, not corrode it. Routes one of three regimes (REFINE / SELECT / DEFER) by verifiability, under the master condition + economic stop below.

Trigger Phrases

converge to high quality · iterate until good enough · best-of-N · refine until it passes · lift the score before asking me · convergence engine · drive this to convergence · engine de convergência

When to use

  • High quality via bounded iterative review, not one shot (codegen, config, governance docs).
  • Competing proposals to reconcile → SELECT → converge.
  • An autonomy_score below the HIGH gate to lift honestly before HITL → REFINE → cascade-resolver.
  • Diverse-lens breadth before acting → perspective-trio; depth verify → persona-pipeline.

When NOT to use

Skip the engine on a clean high-confidence single-pass answer (self-critique paradox — over-review degrades it), when a deterministic oracle alone suffices, or when the task is unverifiable AND below the floor (→ straight to DEFER/HITL).

The master condition (non-negotiable)

Iterative convergence raises quality IFF verifier_accuracy > generator_accuracy AND the verifier is independent (cross-axis diverse — see Diversity below).

Violate it → the self-critique paradox: same-model critique on clean output degrades it (~98%→57%; Huang et al. 2024). A deterministic verifier (tests · compile · schema · lint · gitleaks) has f=0 and is the strongest critic — prefer a deterministic oracle wherever one exists; use a probabilistic critic only where none does.

Determinism / probabilism allocation

| Engine function | Layer | Mechanism (this repo) | |---|---|---| | Selectivity gate (loop-or-skip) | deterministic | hook/script on signal (tests-fail? low-conf? oracle-exists?) — never invoke cognition on a clean, high-confidence answer | | Verifier / oracle-gate | det where checkable → prob else | tests · compile · schema · lint · gitleaks · diff (f=0); persona-pipeline / perspective-trio ONLY where no deterministic oracle | | Round-cap · token-budget · time-box | deterministic | cascade-resolver 8 termination conditions + harness n ≤ n* — NOT model self-judgment | | Vote-tally · dedup · keep-best (monotonicity) | deterministic | count/compare — never ship a regressed round | | Merge-gate | deterministic | CONTRIBUTING.md bot-convergence gate + pr-review-protocol §2.6.1 G1-G8 (mergeable / CLEAN / checks=SUCCESS are API reads) | | Gap-finding · fix-gen · judgment · synthesis | probabilistic | diverse cross-brand critic panel (the cognition) | | Audit-trail · state | deterministic | hooks · files · git (amnesia-proof) |

Three-regime switch (calculated per task)

Classify the task by verifiability and generator competence, then route:

| Regime | Condition | Composition (existing primitives) | |---|---|---| | REFINE | gen ≳ 70%, verifiable | perspective-trio (parallel diverse breadth) then cascade-resolver (sequential diverse uplift, keep-best) → geometric climb to human-multi-pass ~95% | | SELECT | gen 40–70%, verifiable | best-of-N → converge (5-act steelman→critique→compare→synthesize→reject-log). Works because verifying ≫ generating (asymmetry); selection needs only a good verifier, not a >50% generator | | DEFER | gen < 40% OR unverifiable | HITL — the deliberate 10–15% residue, never 0% (escalate with the synthesis, do not fake a result) |

Verify-depth pass (any regime, before acting on a high-impact result): persona-pipeline (6-stage board, depth-scaled by risk) → produces the certainty factor the autonomy gate consumes.

Cutoffs are heuristic → calibrate per task-class empirically. Benchmark grounding (2026): knowledge/reasoning 85–94%, single-issue coding 74–94% (but contamination-resistant SWE-bench Pro ~46%), long-horizon agentic 37–69%, multi-run consistency drops ~60% → 25%. "80%" is task-class-dependent, not a constant.

Multi-axis diversity (the r-lever)

Vary the critic panel along {discipline (security · perf · correctness · UX) · view (abstraction) · vertical (depth-audit) + horizontal (peer breadth) · brand (Claude · Gemini · GPT differ)} simultaneously. Correlation on any axis re-introduces shared blind-spots and stalls convergence.

⚠ No hive-mind / shared-memory for the critique layer — it correlates critics → kills the r-diversity → violates the master condition. Enforced by perspective-trio's diversity guard + cascade-resolver's no-duplicate-role validator.

Economic stop (deterministic, harness-enforced)

n* = 1 + ⌈ ln( (1−ρ)·g₀·V / C ) / ln(1/ρ) ⌉
   ρ = retained-gap-fraction · g₀ = initial gap · V = value/correct-unit · C = round-cost

Round-count convention (binding — n* is the FIRST REJECTED round). Round k shrinks the gap g₀ρ^(k-1) → g₀ρ^k, so it buys V·g₀·(1−ρ)·ρ^(k-1); keep looping while that exceeds C. Solving gives n* = last_affordable + 1 — verified numerically across 16 parameter sets (15/16; the 16th is the degenerate case where no round is affordable at all). ⇒ the last round worth running is n*−1. Anyone treating n* as a round budget runs one round too many.

Marginal-value indexing: round k is affordable iff V·g₀·(1−ρ)·ρ^(k-1) > C — the value of the gap that round closes, not the gap remaining. Index from k=1 (the first refine round after DRAFT).

Parameter bounds — n* is dominated by ρ, NOT by V/C. The ln(V/C) numerator does grow only logarithmically, but the ln(1/ρ) denominator collapses as ρ→1, so a slow-converging loop needs many rounds:

| ρ (retained-gap fraction) | V/C=20 | V/C=100 | V/C=1000 | |---|---|---|---| | 0.3 (fast — each round kills 70% of the gap) | 4 | 5 | 7 | | 0.5 | 5 | 7 | 10 | | 0.7 | 7 | 11 | 17 | | 0.9 (slow — each round kills 10%) | 8 | 23 | 45 |

Corrected 2026-08-14. This line previously asserted "robustly ≤ 3–4 rounds". That is false and was never computed — ρ=0.9, g₀=1, V/C=100 yields 23. The claim survived because the logarithmic-in-V/C half is true and nobody evaluated the other half. Measure ρ for your task class before assuming a small n*; if you cannot estimate ρ, do not quote a round count — use the harness cap and the stagnation test below, which need no parameter estimate.

Floor = human-parity (~90%, NOT 100%); cap is harness-enforced (cascade-resolver termination), not model-judged. Also stop on Δ < ε for K rounds OR consensus — these are the parameter-free stopping rules and are the ones to prefer when ρ is unknown. The curve is sub-geometric (easy errors re-found, hard residual resists) → the plateau arrives sooner than the formula's worst case; looping past n* costs 4–10× for <1% gain.

Composition map (no new engine)

| Function | Primitive | Path | |---|---|---| | Breadth (parallel orthogonal lenses) | perspective-trio | agents/perspective-trio.md | | Score-uplift loop (sequential diverse, economic-stop) | cascade-resolver | agents/cascade-resolver.md | | Depth verify (6-stage board, certainty) | persona-pipeline | agents/persona-pipeline.md | | Proposal synthesis (SELECT) | converge | skills/converge/SKILL.md | | Autonomous drive harness | auto-pilot | skills/auto-pilot/SKILL.md | | Deterministic loops/fan-out | host Workflow/orchestration primitive | (runtime) | | Merge-gate / state / audit | CONTRIBUTING.md gate · hooks · git | repo infra |

The engine is a router + bounds over these — itself an instance of native-primitive-over-custom-machinery. Related agents (best-fit-router, agent-forger) are not dispatched and intentionally not bundled (YAGNI).

Return-Gate application (self-resolve before asking)

Before returning [options · decisions · questions] to the operator: (1) rank by recommendation; (2) impact-score each (6-factor autonomy gate); (3) diverse-validate (persona-pipeline + the multi-axis panel); (4) gate — top item HIGH (≥0.85) ∧ reversible ∧ ¬HUMAN_DOMAIN → decide + act + report (skip the ask); else score-uplift (cascade-resolver, ≤ n*) → regenerate ranked items → re-loop bounded; (5) exit — HIGH self-resolution → act; OR genuine residue → ask (tool-over-prose, recommended-first). Escapes (do NOT suppress the ask): HUMAN_DOMAIN · a genuine operator-preference the agent lacks + can't self-verify · irreversible/high-blast · duly-justified.

Viability bar (settled)

Beat the human baseline (~90% single-pass, NOT 100%) — humans reach higher via the same multi-pass review this automates. Viable NOW for verifiable regimes; HITL on the residue.

Protocol Rules (invariants & bounds — non-negotiable)

  • Master condition (verifier > generator, independent) — gate deterministically (not model self-judgment): bin/convergence-guard --generator <axis> --verifier <axis> [--oracle … --oracle-result pass|fail …] → 0 ALLOW / 3 REFUSE (fail-safe: missing → REFUSE); on REFUSE → oracle · cross-axis verifier · or DEFER.
  • Stopping is deterministic-harness-enforced (cascade-resolver conditions / n*), never model self-judgment.
  • Keep-best monotonicity: never ship a round that regressed against the prior best.
  • Recursion depth ≤ 2; cascade attempts cannot spawn cascade.
  • The 10–15% HITL residue is by design, not a failure — never fake a result to avoid it.
  • No --no-verify, no auto-merge bypass of the CONTRIBUTING.md convergence gate.

Anti-patterns (do NOT)

  • ❌ Self-critique on a clean, high-confidence output (the paradox — degrades it)
  • ❌ Same-model / same-brand verifier (correlated blind-spots; violates the master condition)
  • ❌ Model-judged stopping (must be deterministic-harness-enforced)
  • ❌ Loop past n* (4–10× cost, <1% gain)
  • ❌ Hive-mind / shared-memory for the critique layer (correlates critics)
  • ❌ Suppressing a genuine HITL-residue ask (the 10–15% deferral is by design)
  • ❌ Treating any single benchmark % as ground-truth (contamination inflates 5–15 pts)
  • ❌ Re-implementing converge / cascade / pipeline inside this skill (it is a composition, not an engine)

Examples (invocation prompts — not a CLI)

Invoke conversationally (frontmatter triggers) — no CLI:

  • REFINE — "drive this to high quality via a few bounded diverse-review iterations" → perspective-trio (breadth) then cascade-resolver (uplift, keep-best), stop at n*.
  • SELECT — "reconcile these competing proposals into one validated synthesis" → converge.
  • AUTO — "converge this PR before asking me" → classify regime, route, apply the Return-Gate before any HITL ask.

Prior art

See PRIOR-ART.md for research grounding (Self-Refine, Reflexion, CRITIC, Huang 2024, multi-agent-debate Du et al.) + composed-primitive provenance. converge has its own 20+-survey in skills/converge/PRIOR-ART.md.

Related multi-agent-os artifacts

  • skills/converge/SKILL.md — the SELECT-regime synthesis primitive this engine routes to
  • agents/perspective-trio.md · agents/cascade-resolver.md · agents/persona-pipeline.md — the probabilistic primitives this engine composes
  • skills/auto-pilot/SKILL.md — sibling autonomous-drive kernel (also composes, doesn't re-implement)
  • skills/quiesce/SKILL.md — termination-predicate driver that can wrap this engine per PR
  • protocols/agent-delegation.md — how spawned primitives fit the delegation chain

License

MIT (matches multi-agent-os repo LICENSE).