from objective to verified outcome
Most "autonomous agent" failures aren't prompt problems. They're missing-loop-component problems: no durable state, no objective gate, no stop condition, the maker grading its own work. Looptimal fixes that at two levels.
No clone required — this runs the real Stage-6 outer verifier against a fixture, tampers with the fixture, and confirms the tamper is caught:
uvx --from git+https://github.com/Renn-Labs/[email protected] verify-outcome --selftestSELFTEST GREEN
That single line is the whole pitch: an honest bundle round-trips GREEN, then the same fixture is
tampered (the artifact the loop claims to have fixed is reverted) with contract_hash left
untouched — and the outer verifier catches it. A maker's self-reported GREEN can't buy a pass here;
only a live re-check can. This is why maker ≠ checker isn't a slogan in Looptimal — it's the
literal thing verify-outcome.py does on every run, including this one.
At the loop level, it refuses to blueprint a loop until all four atoms are real:
| Atom | What it is | The failure it prevents |
|---|---|---|
| Goal | One objective, stated once | Scope drift, moving goalposts |
| State | A durable record of tried / failed / context | Re-doing work, amnesia across iterations |
| Verifier | A hard, external gate — test / build / lint / repro / rubric, or a separate reviewer | "Looks good to me" — the maker grading itself |
| Stop | Success criteria and a safety limit (max iters / budget / halt) | Runaway loops, burning budget on a stuck task |
Plus one rule that ties them together: maker ≠ checker — nothing is "done" until something other than the thing that produced it says so.
This isn't a hunch. SpecBench measures reward hacking as the pass-rate gap between a coding agent's visible validation tests and a held-out set covering the same requirements, and finds that gap widens ~28 percentage points for every 10× increase in code size — even as agents saturate the visible suite. ImpossibleBench found cheating rates as high as 76% when test files are visible (even mutated), dropping to near zero once they're simply hidden from the model. And Cursor's own SWE-bench Pro study found 63% of Opus 4.8 Max's "successful" resolutions had been retrieved from git history or the public web rather than derived. A maker that can see or grade its own gate will, on average, find the gate — not the fix.
At the outcome level, Looptimal goes further: it frames a sealed acceptance suite, picks or rejects the right loop archetype, war-games the plan before you commit, dispatches maker and checker agents, and re-runs the sealed suite against live state before anything is called done. "Done" means the outcome is proved against live state by a separate verifier — not asserted by the agent that did the work.
The loop-design wizard (formerly the standalone LoopPrint) is embedded as Stage 2: Design-loop. It also runs as a direct fast-path when you only want a loop blueprint. One product, one /looptimal skill.
Every line of output above is real — recorded by actually running scripts/verify-outcome.py --selftest and examples/critic-panel/run_demo.sh (see scripts/record-demo.py, and
assets/demo.cast for the raw asciinema recording). Nothing is scripted
sales copy; it's the outer verifier and the critic-panel quorum doing exactly what SECURITY.md
and the pitch above claim, on this exact codebase.
The most valuable thing Looptimal does is sometimes tell you not to build a loop. A loop only pays off when:
- It recurs — the setup cost amortizes over many runs.
- An objective gate can reject bad output — you can write the verifier.
- The budget absorbs retries — iterating is cheaper than getting it right once by hand.
- The agent can run what it writes — there's a real feedback signal, not a human in every cycle.
If recurrence fails, the honest answer is not always "stop." It means "not a reusable loop blueprint yet." A one-time objective with a real verifier can still route to a mission / goal run, using the same discipline: durable state, bounded retries, maker != checker, and a stop condition. If retries are not useful, route to a single verified pass. If no verifier or human checkpoint exists, reject the automation claim. The metric that matters is cost-per-accepted-change, not tokens spent.
Ralph loops, Claude Code's native loop support, and similar patterns run a loop — they're the execution engine. Looptimal is the layer around whichever one you're already using: the Tier-0 decision gate that says whether a loop is even worth building before you build it, the sealed definition of "done" frozen before the loop starts, and the independent verifier that re-proves the outcome once it's finished. Maker ≠ checker applied to whatever loop you're already running — not a replacement for it.
Spec-driven tools like GitHub spec-kit and AWS Kiro write a spec, which is a real and different
problem. Neither verifies the built thing against a live outcome once the spec is implemented —
that's exactly what Stage 6 (Verify-outcome) exists to close. If a target repo already has
spec-kit or Kiro artifacts, scripts/looptimal-frame-ingest.py is an optional Stage-0 Frame
helper that surfaces them as candidate acceptance-criteria text for a human to accept or edit —
it never auto-seals anything into a real contract.
If you just want a loop that runs, those tools are great at that. Looptimal is for when you need to prove what it claims when it's done — CI for agent done-claims, not another way to write or run one.
| # | Stage | What it does |
|---|---|---|
| 0 | Frame | Turn the objective into a hash-pinned, sealed acceptance suite; every criterion asserts an outcome (not a symptom) and binds a domain oracle. |
| 1 | Analyze | Produce a Capability Manifest and local capability readiness inventory — domains, risks, dependencies, skills/plugins/connectors/MCPs/agents/data sources. |
| 2 | Design-loop / Route | Run the loop-design wizard or route the objective: reusable loop, one-time mission / goal run, single verified pass, human-gated workflow, or hard REJECT when no honest verifier exists. |
| 3 | Plan | Build a consensus task graph with per-task acceptance tied to the sealed suite. |
| 4 | Simulate | War-game the loop forward N steps, pre-mortem the failure modes, harden the plan. |
| — | Human GO | Explicit approval to execute. No GO, no Execute. |
| 5 | Execute | Dispatch dynamic domain-expert sub-agents; maker ≠ checker; pre-action gates on irreversibles. |
| 6 | Verify-outcome | A separate checker re-runs the sealed suite against live state, ignoring self-reported GREEN. |
| 7 | Persist | Record evidence, decisions, rejected paths, and the next continuation state. |
The Design-loop wizard also runs as a direct fast-path when you only want a loop blueprint — say "design a loop" or "loop wizard" and Looptimal jumps to Stage 2 without outcome orchestration.
/plugin marketplace add Renn-Labs/Looptimal
/plugin install looptimal@renn-labs
Invoke as /looptimal (v2.0.0). Say "design a loop for …" for the wizard fast-path.
Other harnesses. Looptimal is a self-contained folder skill (SKILL.md + templates/ + references/ loaded on demand). Clone once and symlink where your harness discovers skills:
| Harness | Install |
|---|---|
| Claude Code (folder skill) | ln -s ~/looptimal ~/.claude/skills/looptimal |
| OpenCode | ln -s ~/looptimal ~/.config/opencode/skills/looptimal |
| OpenClaw / EClaw | ln -s ~/looptimal ~/.openclaw/skills/looptimal |
| Hermes | ln -s ~/looptimal ~/.hermes/skills/looptimal |
| Codex / OMX | cp -r ~/looptimal ~/.codex/skills/looptimal (re-copy after updates) |
| grok build | add ~/looptimal/SKILL.md entry to your AGENTS.md catalog |
Just the tooling, no clone. The doctor/lint/verify scripts are also installable as ordinary
console commands via uv/pipx — useful if you only want to run
looptimal-lint/verify-outcome against your own mission files, not install the skill itself:
uvx --from git+https://github.com/Renn-Labs/[email protected] verify-outcome --bundle path/to/evidence-bundle.jsonThis is a convenience layer over the same scripts/*.py, not a separate implementation — pin to a
tagged ref (@v2.2.0, not @main) so the command doesn't silently move under you. Not yet on
PyPI; the uvx --from git+... form works today without one.
From a checkout that includes the grouped entry point, you can also smoke-test the loop-design tools without waiting for the next tag:
uv run --with-editable . looptimal verify-outcome --selftest
uv run --with-editable '.[yaml]' looptimal library search secretpython3 scripts/looptimal-lint.py --selftest # plan-time gate self-test
python3 scripts/verify-outcome.py --selftest # Stage-6 outer verifier self-test (tamper → RED)
python3 scripts/loopprint-lint.py examples/ci-triage/loop-spec.yaml # loop-design wizard gate (GREEN)
python3 scripts/looptimal-doctor.py # install health check
# Worked example round-trip against live state — sealed with a demo HMAC key (see
# examples/issue-to-pr-bugfix/DEMO-KEY-NOT-SECRET.hex; loudly non-secret, never reuse it):
K=examples/issue-to-pr-bugfix/DEMO-KEY-NOT-SECRET.hex
python3 scripts/looptimal-lint.py examples/issue-to-pr-bugfix/mission.yaml --key-file "$K"
python3 scripts/verify-outcome.py --bundle examples/issue-to-pr-bugfix/evidence-bundle.json \
--workdir examples/issue-to-pr-bugfix --repeat 3 --key-file "$K"
# Opt-in: on GREEN, also emit a public verification receipt (references/receipt.md). Keyed here,
# so it is HMAC-signed; bare --receipt writes <workdir>/looptimal-receipt.json (never on RED):
python3 scripts/verify-outcome.py --bundle examples/issue-to-pr-bugfix/evidence-bundle.json \
--workdir examples/issue-to-pr-bugfix --repeat 3 --key-file "$K" --receipt
# Re-verify an existing receipt from first principles (re-derive its hashes, re-check the HMAC
# signature, and RE-RUN the sealed suite live) — a keyed receipt needs its key or it fails loud:
python3 scripts/verify-outcome.py --check-receipt examples/issue-to-pr-bugfix/looptimal-receipt.json \
--workdir examples/issue-to-pr-bugfix --repeat 3 --key-file "$K"The outer verifier (verify-outcome.py) is deliberately hostile to the maker: it loads the sealed contract the bundle points at (never a maker-supplied one), refuses non-sealed paths, canonicalizes and matches the contract hash, re-runs every criterion authoritatively (the bundle's self-reported results can only lose), requires each check to invoke a sealed, workdir-contained oracle script, and re-hashes artifacts.
Disclosed limit: by default, with no framer key configured, canonical_contract_hash() is an unkeyed sha256 self-digest over the contract mapping, and sealing rests on OS permissions — the framer owning sealed/, the checker controlling --workdir; the residual is that anyone who can write sealed/ can also recompute a matching hash after tampering. Passing a framer key (--key-file or the LOOPTIMAL_FRAMER_KEY env var) switches to a keyed HMAC-SHA256 digest folded over every file under sealed/ — the in-toto "materials" pattern — binding the oracle scripts a criterion actually invokes, not just the contract text naming them, so tamper-then-recompute no longer produces a matching hash. The residual that remains even when keyed is key custody: the key must live outside every maker-writable root, which is the checker's responsibility exactly like --workdir control already is. Do not over-claim tamper-proofness.
Loop blueprints generated by the Design-loop wizard (run-this-loop.sh, verify.sh) are executable code parameterized by loop-spec.yaml — treat them as code, not data. See SECURITY.md.
From the Design-loop wizard (Stage 2 / design fast-path), a self-contained runnable package per loop:
loop-spec.yaml— four atoms + pattern + budget, machine-readablemaker.sh— the maker step, run as a separate process from the verifier (maker ≠ checker)verify.sh— the external verifier (exit-code gate)state.md— the durable State artifact, updated every iterationrun-this-loop.sh— engine-agnostic runner; emitsmetrics.jsonl+state.jsonleach iterationsafety-checklist.md— human checkpoints + budget limits + checker identityflow.mmd— Mermaid diagram of the loop
From the full pipeline, additionally: acceptance-suite.yaml + acceptance-suite.sha256, Capability Manifest, local-capability-inventory.yaml, route.md, mission.yaml, consensus task graph, Simulate report, and evidence bundle.
Tooling: loopprint-lint.py gates the loop spec; loopprint-ls.py reports health of every loop in the repo (rot radar) — --update-index opts a repo's loops into an append-only, local-only ~/.loopprint/index.jsonl, and loopprint-ls.py --global reads it back ranked by cost-per-accepted-change across every repo that's opted in, flagging ROTTEN loops; deleting the index loses nothing, it's a rebuildable pointer cache; loopprint-report.py computes cost-per-accepted-change from metrics.jsonl; loopprint-skillify.py promotes a GREEN loop to a reusable skill. Verifier recipes: templates/verifier-library.yaml. Schema contract: references/schema.md.
python3 scripts/loopprint-update.py # dry-run: shows what would change, does nothing
python3 scripts/loopprint-update.py --apply # performs itSymlinked installs (Claude Code folder skill, OpenCode, OpenClaw/EClaw, Hermes) update for free
the moment you git pull the clone they point at. Copy-based installs (Codex/OMX:
cp -r ~/looptimal ~/.codex/skills/looptimal) don't — loopprint-update.py git pulls the clone
and re-syncs any copy-based install it finds at a known path, reporting exactly what changed
(never anything untracked — .omc//.buildlog/-style local state is never synced). Dry-run by
default; nothing is touched without --apply.
python3 scripts/looptimal-doctor.py # diagnose, copy-pasteable fix per problem
python3 scripts/looptimal-doctor.py --fix # apply safe repairs (chmod +x, relink dangling symlink)
python3 scripts/loopprint-doctor.py # diagnose the loop-design wizard install
python3 scripts/loopprint-doctor.py --fixFull symptom→cause→fix map per install type: references/troubleshooting.md.
- The skill is the system. Looptimal encodes components and gates, not a personality. It does not demand a banner on every reply or a confirmation incantation. A loop works because its parts are real, not because the model recites a mantra.
- Stack-agnostic core. The methodology and artifacts stand alone. Heavier orchestration (isolated sub-agent dispatch, a separate plan/judge reviewer, cross-repo leasing) is described generically — wire in whatever you use.
- Honest gates. A verifier the maker can satisfy by self-assessment is not a verifier. Looptimal always points the gate at something external.
- Outcome, not completion. "Tests pass" is not the bar; live-state re-verification against a sealed acceptance suite is.
Built by Erik Ford at Renn Labs — an AI research & advisory firm. Looptimal distills one lesson from building autonomous agents: reliability comes from loop components and verified outcomes — durable state, external verification, stop conditions, maker ≠ checker — not from clever prompts.
MIT © Renn Labs LLC