Evolve Loop — CI/CD for AI-written code

The idea

Intelligence proposes. A dependable process decides.

AI is strong at three decisions: what to build, how to build it and what looks wrong. The pipeline lets AI make these decisions freely.

A structured, repeatable process decides what is safe to ship. Its guardrails are code, and the AI cannot argue with code. Freedom where it helps, structure where it counts.

Intent

a clear goal

It changes a vague request into a clear goal, and it names the risky assumptions first.

Scout

a researched plan

It examines the code and the past lessons. Then it proposes the work that is worth the effort.

Triage

a bounded scope

It decides what this cycle does and what waits, so the scope stays small.

Build

changed code

It makes the change in isolation, after a test that fails first. Then the builder simplifies and reviews its own diff.

Audit

an independent verdict

By default, a reviewer from a different model family challenges the work and decides if it holds up. Before it, a code review scores the change on ten dimensions, in shadow.

Ship

a safe merge

It merges only the work that passed, with a record of each step.

Learn

a lesson kept

It turns the result into a permanent lesson for the next cycle.

AI-composed pipeline

The model composes its own pipeline.

Give it a goal. The advisor runs the mandated phases, picks from the common phases and writes new phases when the goal needs them. Then one routing table gives each phase that uses a model its CLI and model. agy runs first, on Gemini 3.8 Flash High. At the deep and top tiers, Claude Opus runs through agy first and through Claude Code second. Nothing here is pre-scripted.

goal

mandated floor common phase written for this goal + unlimited

Advisor

Per-phase LLM routing

One routing table gives each phase that uses a model its CLI and model. Below the deep tier, agy runs first, on Gemini 3.8 Flash High. The auditor, the tdd engineer and the code reviewer run on Claude Code only. Thus by default, the build and the review use different model families. Ship is host code, and it uses no model.

0 common 0 minted 0 floor 0 skipped

Advisor ▸ reasoning

The integrity floor

Autonomy without shortcuts.

Bypass mode means “do not ask the operator”. It never means “skip the checks”. A floor compiled into the binary evaluates every cycle before anything ships. Change the evidence and see the verdict change.

ship ⇒ build ∧ audit ∧ ( tdd ∨ trivial ) ∧ gates

Build evidence existsbuild-report.md from the builder

Independent audit says PASSaudit-report.md · an adversarial auditor on Claude Code, by default a different family from the builder

Tests written first, red observedtest-report.md · the failed run before the fix

Change is trivial, or a documentthe cycle classifier or deliverable_kind=document; it waives only the tdd conjunct

Eval quality gateevolve eval quality-check: no tautological or unsatisfiable predicates

Tree state attestedtree-diff guard · SHA binding from audit to ship

try a cycle

These are compiled Go defaults, not config that you can forget to set. The floor holds even when a model writes every prompt in the pipeline. The new code-review phase runs in shadow, so it does not gate a ship yet.

Continuous development

You never stop the loop. You feed it.

The queue is how you steer. While the loop runs, you file a JSON item with evolve inbox add. Every cycle, triage takes the top of a computed rank: weight, priority class, the items that it unblocks, recurrence, age and goal. The other items age forward, with no restart and no lost work. When an audit goes red, the retro files a lesson as a new item, and the failed item returns with its worktree. In the demo below, every third cycle fails, and the rank shows only the weight.

compose a todo → .evolve/inbox/<ts>-<id>.json

weight0.00

Real schema, in short: id, weight, title, kind and fix. A real item also has acceptance[] criteria, which the auditor enforces, and a priority_class.

the queue — triage takes the top of the rank, every cycle

0.72repo-map-artifactfeature
0.61artifact-log-compressionfeature
0.55flaky-rerun-scanbug

Built for parallelism

Run several loops at once.

Give each feature its own loop, and the loops run side by side. Each loop has its own git worktree and branch, and it composes the pipeline that its goal needs. The routing table picks the CLI for each phase. The loops never collide, and only green changes merge to main, one at a time.

merge gate · one at a time idle

main 0 shipped

Many features at once

Point a loop at each goal. The loops advance in parallel, not in a queue.

Isolated by design

Each loop owns a worktree and a branch: no crossed wires, no half merges.

Safe, serialized merges

Only green work reaches main, one merge at a time.

All you need is an LLM CLI subscription. Each lane runs on the CLIs that you already use, for example agy and Claude Code.

Usage

From one command to full control.

Start with a goal. Add a flag only when you want more. Each note tells what the command does behind the scenes.

/evo:loop "add dark mode"

Just a goal. The advisor composes the whole pipeline: which phases run, which CLI and model run each phase, and how many cycles. It stops when the work is done.
/evo:loop harden

Steer the approach. A strategy (harden · repair · innovate · balanced) changes the scope and the strictness. The phase spine stays the same, and the posture changes.
/evo:loop --cycles 3 "add dark mode"

Bound the cycles. --cycles N is a hard contract: exactly N cycles, with no early stop.
/evo:loop --cycles 3 harden "tighten input validation"

Stack the levers. Compose them: a strategy, a hard cycle bound and a goal in one command. This is the full-control end of the range.
/evo:loop --resume

Resume. It continues a run from its last checkpoint, with the worktree and the state intact. No work is lost.
evolve checkpoint save --all

Save work in progress. It saves the uncommitted work of each dev worktree as a ref under refs/checkpoints. It does not change the branch, the index or the working tree. evolve checkpoint restore puts the work into a new or clean worktree.
evolve inbox add --file fix-flaky-auth-test.json

Queue a backlog. evolve inbox add is the one way to file an item. The loop takes items in the order of a computed rank: weight, priority class, the items that it unblocks, recurrence, age and goal. The verbs show, list, edit, verify and withdraw curate an item, and each verb validates its change.
evolve inbox route-console <id> <reason> <cycle>

Route the work. It marks an item as operator-owned (route: console-manual). After that, every lane's claim refuses the item. evolve inbox route-lane reverses a false positive. Routing is plumbing, not a prompt.
evolve cli-routing explain builder

Explain the routing. It prints the CLI chain of an agent from the one routing table. The verbs init, set, unset and migrate of evolve cli-routing are the only writers of the table.
policy.json → "fleet": {"count": 3}

Go wide. Parallel lanes, each in its own git worktree. Quota pressure shrinks the width, but never below one isolated lane and never onto your main tree.
evolve release 22.27.0

Publish. A release pipeline that repairs itself: preflight gates, the changelog, an atomic version bump and a CI-verified publish. If the remote suite fails, the release demotes itself, so "latest" never points at a broken build.

Setup is one command, and it is optional

/evo:setup

Run it once. It finds your installed LLM CLIs and offers three presets, and one choice writes per-phase routing to .evolve/policy.json. If the project declares a cli_routing table, setup refuses, and evolve cli-routing edits the table. If you skip setup, each phase uses the defaults of its profile.

RecommendedEconomyMax-quality

What makes it work

Designed like a team, not a one-shot prompt.

AI-driven, end to end

It designs the work. It does not only type it.

The pipeline decides what to build, how to approach it and what is risky. It applies real judgment at every step, not one prompt into the dark.

A pipeline that adapts

Structure that changes shape for the task.

Every change follows the same clear pipeline, but the pipeline flexes. A one-line fix skips the ceremony, and a risky feature gets more review. The pipeline is structured enough to trust and dynamic enough to stay fast.

Agile by nature

Plan, build, review, reflect: every cycle.

Each cycle runs like a sprint: scope the work, build it, review it, ship it, then learn. The scope stays bounded, so nothing sprawls and the progress compounds.

Self-repair

A failure does not stop it. A failure teaches it.

When something breaks, the pipeline catches it, recovers and turns the failure into a permanent rule. If only audit gates forced a FAIL, the build gets a bounded repair round. At each wave boundary, the loop updates Claude Code and agy and smoke-tests them before dispatch. When fixes land on main, the loop rebuilds and restarts itself at the next boot.

An independent second mind

Built to challenge the work, not to approve it blindly.

By default, a reviewer from a different model family tries to break each change before it ships. A new code-review phase between build and audit scores each change on a shared quality index of ten dimensions. It runs in shadow now. The audit keeps the block until each named defect is fixed or honestly deferred.

Any model. No lock-in.

One routing table sends each phase to the right model.

One cli_routing table in .evolve/policy.json decides every dispatch, and evolve cli-routing is its only writer. In the table that builds Evolve Loop, agy runs first, on Gemini 3.8 Flash High. Deep and top seats run Claude Opus through agy, then through Claude Code. The auditor, the tdd engineer and the code reviewer run on Claude Code only. Codex and local models through Ollama are also routable.

Loops that converge

Built so that every loop that repeats converges or escalates.

One convergence policy is built to decide the next step of every loop that repeats (ADR-0126). It runs in shadow now: no loop calls it yet. First it changes the feedback, then the strategy, then the scope. A fourth round never occurs, and a CRITICAL finding is never deferred.

Standards, enforced

The bar is in the tools, not in a style guide.

Code explains itself: the commit gate refuses a commit that adds a comment. Every code change is test-first, and mutation tests check the tests. Every landing passes a review loop with a convergence rule. The documentation moves to ASD-STE100 Simplified Technical English: 21 core documents use it now, and its lint is in progress.

	A single-LLM loop	Evolve Loop
Decides what to build	You write out every step	It plans and scopes the work
Quality gate	An AI says "looks good"	An independent review must pass
When something breaks	Start again	It recovers, repairs and learns
Repeated rounds	Retry until the budget is gone	Converge or escalate, never a fourth round (in shadow)
Memory	Forgets between runs	Compounds: each run teaches the next
Models	One vendor, one model	One routing table: the best model for each phase
Best for	Quick throwaway edits	Work that you must merge

Try it in 90 seconds

One line. See what you get.

No account. No telemetry. One static binary. The installer verifies its checksum, sets up your PATH and connects the skills to each AI CLI that you already use.

Install Evolve Loop v22.27.0macOS & Linux · Apple Silicon + x64 · Windows through WSL2

curl -fsSL https://mickeyyaya.github.io/evolve-loop/install.sh | sh

✓verified end-to-end on macOS, Debian, and Alpine

then, in your AI CLI

Check your setupevolve doctor

Run your first cycle/evo:loop --cycles 3 "add dark mode"

Read install.sh before you run it Releases + SHA-256 checksums Prefer manual? Download the binary

Pin a version: EVO_VERSION=v22.27.0 … | sh · opt out of PATH edits: EVO_NO_MODIFY_PATH=1

what you'll see

$ curl -fsSL https://mickeyyaya.github.io/evolve-loop/install.sh | sh
evolve-install: trying prebuilt: …/evolve_darwin_arm64.tar.gz
evolve-install: checksum verified
evolve-install: detected AI CLI(s): claude agy
Installation complete!
evolve-install: installed: evolve 22.27.0 → ~/.local/bin/evolve
evolve-install: installed binary fingerprint (SHA256): <the 64-character SHA256 of your binary>
evolve-install: done. Next: evolve doctor    then    /evo:loop --cycles 3 "your goal"

Ship the code your agent wrote — no diff to read.

Agents can write the feature now. The hard part is the merge.