Agent Evolutions: Stop Guessing the Design — Evolve It

Most coding-agent tasks have one right answer hiding behind a workflow. “Add password sign-in.” “Fix the off-by-one in the pagination cursor.” “Refactor this handler to use the new client.” The job is to converge — pick the path, drive it to done, ship the diff. That is the world agent-levers lives in.

Some tasks aren’t shaped like that. “Which prompt wins?” “Which caching strategy is fastest?” “Which library shape is friendlier to call from a worker?” There is no single correct path. There are five plausible ones, the differences are not obvious from inspection, and the only honest way to pick is to measure. The shape of the work is divergent  — branch out, evaluate, keep what works.

I kept reaching for that second shape and finding nothing on the shelf. So I built agent-evolutions — a small set of Agent Skills that turn a coding agent into a budgeted genetic search over a design space, with verifiable scoring at every step.

This is the fourth post in a thread on the shared .agents/ ground, after supagents, agent-docs, and agent-levers. Same bet, different question: levers ask “did we build it right?”, evolutions ask “did we pick the right thing to build?”

Agent Evolutions: Genetic exploration of solution spaces, with verifiable scoring — https://github.com/fmind/agent-evolutions

The design-by-intuition tax

Three failure modes I keep watching teams pay for — including my own:

The five-minute eyeball test. Two prompts on the screen, both look reasonable. One person prefers the terser one; another prefers the structured one. The team picks whichever was authored by the loudest reviewer. Three weeks later a quiet regression appears on a slice of traffic nobody A/B’d against.

Taste vs. taste. “Which client shape should we expose — fluent builder or plain options bag?” Six people, six opinions, zero numbers. The argument lasts a week. Whatever ships is then defended for years because rolling it back is more expensive than living with it.

The benchmark that becomes a vote. “Which caching strategy is fastest?” Real, mechanical, measurable. Then someone runs one manual test, on one workload, and reports a winner. Nobody asks how sensitive the result is, nobody runs the loser to confirm, nobody bothers with a second seed.

These all share a common shape: a design question with multiple plausible answers and at least one mechanical measure — and we answered it with intuition anyway. The cost of guessing wrong is rarely visible at decision time. It shows up months later as a refactor.

What I wanted was a tool that made the right move — generate variants, measure, evolve, pick — cheaper than the wrong move. That is the gap agent-evolutions is aimed at.

Convergent and divergent loops, side by side

The clearest way I can frame the relationship to agent-levers is by the shape of the loop.

Levers is convergent. One workspace, one diff, one verifier set, plan → do → check → act in a sequential chain. The question being answered is how do we drive this single task to done. The whole machine is tuned to finish.

Evolutions is divergent, then convergent. N parallel workspaces (one per variant), N independent results, batched generations that learn from the previous batch, a final pick at the end. The question is which of several plausible designs measures best. The machine is tuned to explore first, then collapse.

Both loops live on the same .agents/ ground, both use file-based state, both let any compliant coding agent drive them. They are not competitors — they are complementary tools for different question shapes. Most non-trivial work, in my experience, is mostly levers and occasionally evolutions. The trick is knowing which kind of question you’re holding.

Genetic search, not random sampling

The first thing people picture when I say “spawn variants in parallel and pick the best” is brute-force Best-of-N: fan out thirty prompt mutations, score them, keep the top one. That is sampling. It is blind, and it scales badly — doubling the budget barely improves the answer because every sample is drawn from the same flat distribution.

Agent-evolutions runs a genetic loop instead:

• Generation 1 seeds a small, diverse set of hypotheses — qualitatively different approaches, not minor variants of one idea.
• Generation 2+ mutates the top survivors, crosses pairs over, and injects a small share of fresh exploration variants to avoid premature collapse.
• Batches are sized to budget.parallel , deliberately, so the loop can learn between batches instead of fanning out blindly.
• Stopping is automatic: budget cap, wall clock, score plateau across N generations, or no survivors.

Each generation conditions on what worked in the previous one. That is the qualitative difference — and the reason a small directed search routinely beats a much larger random one. The skill’s documented optimize cli startup walkthrough finishes in 24 evaluated variants across 4 generations, with the winner from generation 2 — not generation 1.

Three commands, three phases

The whole surface area is three slash commands, one per phase:

• Capture  — /new-agent-evolution