{"id":50965352,"url":"https://github.com/fmind/agent-evolutions","last_synced_at":"2026-06-18T19:33:21.875Z","repository":{"id":356559744,"uuid":"1226557477","full_name":"fmind/agent-evolutions","owner":"fmind","description":"Genetic exploration of solution spaces for AI coding agents (Claude Code, Gemini CLI, GitHub Copilot, OpenCode) — gather a verifiable objective, evolve variants, apply the winner.","archived":false,"fork":false,"pushed_at":"2026-05-31T17:32:39.000Z","size":480,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T15:41:45.351Z","etag":null,"topics":["agent-evolutions","agent-skills","agentic-coding","agy","ai-agents","antigravity","antigravity-cli","claude-code","gemini-cli","gemini-cli-extension","genetic-loop","github-copilot","opencode","variant-optimization","verifiable-scoring"],"latest_commit_sha":null,"homepage":"https://fmind.github.io/agent-evolutions/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fmind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-01T14:54:12.000Z","updated_at":"2026-05-31T17:32:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fmind/agent-evolutions","commit_stats":null,"previous_names":["fmind/agent-evolutions"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fmind/agent-evolutions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-evolutions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-evolutions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-evolutions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-evolutions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fmind","download_url":"https://codeload.github.com/fmind/agent-evolutions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-evolutions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34505420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-evolutions","agent-skills","agentic-coding","agy","ai-agents","antigravity","antigravity-cli","claude-code","gemini-cli","gemini-cli-extension","genetic-loop","github-copilot","opencode","variant-optimization","verifiable-scoring"],"created_at":"2026-06-18T19:33:21.205Z","updated_at":"2026-06-18T19:33:21.866Z","avatar_url":"https://github.com/fmind.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Evolutions\n\n[![CI](https://github.com/fmind/agent-evolutions/actions/workflows/ci.yml/badge.svg)](https://github.com/fmind/agent-evolutions/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![Claude Code](https://img.shields.io/badge/Claude%20Code-supported-D97706)](https://github.com/anthropics/claude-code) [![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-supported-4285F4)](https://github.com/google-gemini/gemini-cli) [![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-supported-181717)](https://github.com/features/copilot) [![OpenCode](https://img.shields.io/badge/OpenCode-supported-059669)](https://opencode.ai)\n\n![Agent Evolutions — genetic exploration of solution spaces with verifiable scoring](./image.jpeg)\n\n\u003e **Genetic exploration of solution spaces, with verifiable scoring.**\n\n**Agent Evolutions** is a file-based Agent Skill suite that drives a coding agent through a genetic loop: gather a single verifiable objective, generate variants in parallel batches, learn from each generation, rank survivors by exit codes (gates) and numeric measures (rubric), then port the winner into the repo. Three slash commands — `/new-agent-evolution`, `/run-agent-evolution`, `/apply-agent-evolution` — cover the three phases, each enforcing its preconditions on `evolution.yaml` field presence. Install once and the same `skills/` tree runs in Claude Code, Gemini CLI, GitHub Copilot, and OpenCode.\n\n**The payoff:** when you have an optimization that admits multiple plausible designs and at least one mechanical measure (faster, smaller, more accurate, more autonomous), the agent runs a budgeted genetic search instead of you guessing — and reports a winner you can defend with evidence.\n\n## Why this exists\n\nPicking a design by intuition is fast but wrong often enough to cost weeks downstream. Three patterns this skill suite replaces:\n\n- \"Which prompt wins?\" answered by a 5-minute eyeball test rarely survives production.\n- \"Which library shape is friendlier?\" answered by personal taste loses to whichever shape has empirical evidence.\n- \"Which caching strategy is fastest?\" needs a benchmark, not a vote.\n\nAgent Evolutions flips the default: pin the objective up front, freeze the gates and rubric, generate variants in adaptive batches, and let the leaderboard pick the winner.\n\n## What you get\n\n- **Evidence over opinion.** Every claim about which variant wins is backed by an independent shell-exit gate and a numeric rubric measure. No silent retries; no result-driven criteria; no narrative scoring.\n- **Genetic loop with adaptive batches.** Generation 1 seeds diverse hypotheses. Each later generation mutates top survivors, crosses them over, and injects fresh exploration variants — sized to `budget.parallel` so the loop _learns_ between batches instead of fanning out blindly.\n- **Hard gates + numeric rubric.** Variants failing any gate are excluded from ranking. Rubric axes are numeric with `direction` (minimize | maximize) and `weight`. Composite score is a rank-normalized weighted mean across axes — robust to outliers and recomputed on read by the run skill, never persisted in `evolution.yaml`.\n- **Self-contained variants.** Each `variants/v\u003cn\u003e/workspace/` is an isolated checkout (`git worktree`) or file copy. Every variant starts from `HEAD`; genetic lineage lives in `parents[]`, not in compounded file state.\n- **File-based sub-agent contract.** Each variant sub-agent writes `variants/v\u003cn\u003e/result.json` (validated against `result.schema.json`). The parent reads files, not chat — survives crashes, gives a permanent audit trail, no JSON-in-chat parsing.\n- **Resumable, budget-bounded.** `evolution.yaml` is the single source of truth. State is derived from field presence (no step machine, no pause flag) — the agent re-reads on entry and decides what to do. Budget caps cover total variants, parallel concurrency, wall clock, and score plateau.\n- **Three commands, three phases.** `/new-agent-evolution` captures the brief, `/run-agent-evolution` drives the genetic loop, `/apply-agent-evolution` lands the winner. Each refuses to run outside its phase based on `evolution.yaml` field presence — no accidental re-capture, no apply-before-winner. Apply diffs the winner workspace against the live tree, gets explicit user confirmation, copies files in, optionally re-runs gates against the repo. Excluded paths from `scope.exclude` are refused even if the variant touched them.\n- **Install once, use anywhere.** The same `skills/` tree drives Claude Code, Gemini CLI, and GitHub Copilot.\n\n## The skills\n\n| Phase   | Trigger                        | Owns                                                                                                                                                                             |\n| ------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Capture | `/new-agent-evolution \u003ctitle\u003e` | Discuss objective, gates, rubric, scope, budget. Commit `.agents/evolutions/\u003cid\u003e-\u003cslug\u003e/` on agreement.                                                                          |\n| Run     | `/run-agent-evolution \u003cid\u003e`    | Genetic loop: plan batch → dispatch parallel sub-agents → ingest each `result.json` → score on read → adapt or stop. Writes `winner` when budget / cap / plateau / no-survivors. |\n| Apply   | `/apply-agent-evolution \u003cid\u003e`  | Diff winner workspace vs live repo, confirm, copy in, optional post-apply gates. Writes `applied`.                                                                               |\n\nState is derived from `evolution.yaml` field presence:\n\n```text\nempty variants → ready\nhas variants, no winner → running\nhas winner, no applied → evaluated\nhas applied → done\n```\n\n## Walkthrough\n\n```text\n$ /new-agent-evolution \"optimize cli startup\"\n  → asks for objective, gates, rubric, scope, budget; proposes a draft\n  → on \"looks good\", writes evolution.yaml + EVOLUTION.md\n\n$ /run-agent-evolution 1\n  → gen 1: plans 6 diverse seeds (lazy-load, build-time inline, plugin map, polyfill strip, ...)\n  → spawns 6 sub-agents in parallel; each materializes a worktree, implements, writes result.json\n  → ranks: v2 (build-time inline) leads at 142 ms, v1 (lazy-load) at 184 ms, v4 fails G2\n  → gen 2: mutates v2 (\"v2 + tree-shake help chunk\") and v1, crosses v2×v3, adds 1 explore\n  → ...\n  → plateau at gen 4 — top score unchanged for 2 gens; stops at 24/30 evaluated\n  → winner: v7 (98.6 ms)\n\n$ /apply-agent-evolution 1\n  → diffs variants/v7/workspace vs live src/, tsdown.config.ts, package.json\n  → \"Confirm to apply, or reply abort\"\n  → user: \"looks good\"\n  → copies files; runs G1 + G2 against live repo; both green\n```\n\n## Install\n\n### Claude Code\n\n```text\n/plugin marketplace add fmind/agent-evolutions\n/plugin install agent-evolutions@agent-evolutions\n```\n\nFor local development, point the marketplace at a clone:\n\n```text\n/plugin marketplace add /path/to/agent-evolutions\n/plugin install agent-evolutions@agent-evolutions\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install fmind/agent-evolutions\n```\n\nFor local development (live-link, edits reload on next session):\n\n```bash\ngemini extensions link /path/to/agent-evolutions\n```\n\n### Antigravity CLI\n\n```bash\nagy plugin install https://github.com/fmind/agent-evolutions\n```\n\nFor local development (live-link, edits reload on next session):\n\n```bash\nagy plugin install /path/to/agent-evolutions\n```\n\n### OpenCode\n\nTo use these skills in OpenCode, place or clone the skill directories under `.agents/skills/` (for project scope) or `~/.agents/skills/` (for global scope). OpenCode automatically discovers and loads them.\n\n### GitHub Copilot\n\n```bash\ncopilot plugin marketplace add fmind/agent-evolutions\ncopilot plugin install agent-evolutions@agent-evolutions\n```\n\nVS Code — point `chat.pluginLocations` at a local clone:\n\n```jsonc\n// settings.json\n\"chat.pluginLocations\": {\n  \"/path/to/agent-evolutions\": true\n}\n```\n\n## Reference\n\n### Layout\n\n```text\nagent-evolutions/\n├── AGENTS.md                                # canonical context — read by Copilot; @-included by CLAUDE.md / GEMINI.md\n├── evolution.schema.json                    # JSONSchema for end-user evolution.yaml\n├── result.schema.json                       # JSONSchema for per-variant result.json (sub-agent contract)\n├── skills/new-agent-evolution/SKILL.md      # Capture phase — discuss \u0026 seed the brief\n├── skills/run-agent-evolution/SKILL.md      # Run phase — drive the genetic loop, pick the winner\n├── skills/apply-agent-evolution/SKILL.md    # Apply phase — diff, confirm, copy in\n├── examples/evolutions/                     # runnable walkthroughs\n├── .claude-plugin/                          # Claude Code plugin manifest + bundled marketplace\n├── gemini-extension.json                    # Gemini CLI extension manifest\n├── plugin.json                              # GitHub Copilot manifest\n└── .github/workflows/ci.yml                 # lint via pre-commit\n```\n\nIn an end-user project after the Capture phase (`/new-agent-evolution \u003ctitle\u003e`):\n\n```text\n.agents/evolutions/\u003cid\u003e-\u003cslug\u003e/\n├── evolution.yaml                           # machine state — validated against evolution.schema.json\n├── EVOLUTION.md                             # single human/agent surface: TL;DR, Brief (loaded verbatim by every variant), Variants, Results\n└── variants/v\u003cn\u003e/\n    ├── workspace/                           # one isolated workspace per variant (gitignored by default)\n    └── result.json                          # sub-agent output, validated against result.schema.json\n```\n\n### When this skill suite does not apply\n\n- The task is a one-line bug fix, rename, or doc edit. Just do it.\n- There is no reasonable way to verify the result mechanically, even via a measurable proxy. Use a normal review instead.\n- The user has already decided the design and is asking for implementation. Implement it.\n\nIf success criteria cannot be expressed as a shell exit code (gate) or a number (rubric), the skill pushes back: \"we need at least one mechanical check before variants make sense.\" Help write one before continuing.\n\n## Contributing\n\nIssues and PRs welcome. Three house rules to keep the skills lean:\n\n- **Each skill file has a line cap** (see `AGENTS.md` §Conventions) — every SKILL.md loads into agent context on every run, so verbosity costs budget.\n- **Voice is imperative.** The skill body addresses the agent (\"Read X, then write Y.\"), not a human reader — that prose belongs in this README.\n- **Run `npm install` once after cloning** — pulls in Prettier and markdownlint-cli2 (no runtime deps). Then `npm run lint` validates Prettier + markdownlint locally with the same hooks `pre-commit` and CI run.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmind%2Fagent-evolutions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffmind%2Fagent-evolutions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmind%2Fagent-evolutions/lists"}