# Self-Improving Agent Ecosystem

> A public reference kit for building evaluator-driven self-improving systems that can observe, propose, test, promote, and learn without confusing activity with improvement.

Self-Improving Agent Ecosystem is an open-source reference architecture created by David Zhang (GitHub: Git-on-my-level) and released under the MIT License. It provides the contracts, schemas, skills, examples, and deterministic helpers needed to build evaluator-driven systems that can safely observe, propose, test, promote, and learn — without conflating activity with genuine improvement. The repository is intentionally not a ready-to-run autonomous agent; it is a structured foundation that future agents build upon.

## What It Is

Self-Improving Agent Ecosystem is a reference kit for constructing safe, evaluator-driven feedback loops in agentic AI systems. It addresses a core challenge in autonomous systems: ensuring that a system's self-modification cycle is grounded in verifiable evidence rather than unchecked automation. The kit supplies the architectural contracts, JSON schemas, portable agent skills, and small Python helpers that any self-improving loop would otherwise have to rediscover independently.

## Three Loop Archetypes

The repository defines three composable loop archetypes that share the same underlying planes:

- **optimize** — ranks candidates against a scalar objective behind a hard correctness gate, using an AVO-lite style ratchet to prevent regression.
- **maintain** — drains a work queue (issues, pull requests, dependency updates, alerts) through triage, candidate, review, publish, merge, and outcome check stages, under a WIP limit and maximum item age. The README recommends most deployments start here.
- **observe → propose** — sensors convert telemetry, usage traces, transcripts, and human decisions into proposals only, never code. This archetype feeds the maintain queue, and a maintain loop can run optimize on any item that has a scorer.

## Four-Plane Architecture

The reference architecture separates concerns into four deliberately distinct planes:

- **Experiment kernel** — AVO-lite provides disposable worktrees, hard scoring, verification hooks, accepted-only lineage, an append-only ledger, and stagnation handling.
- **Workload control plane** — domain-owned sensors, evaluators, promotion, deployment, outcome checks, and rollback.
- **Authority and distribution** — reviewed policy and portable agent skills; no prompt silently grants deployment or credential authority.
- **External observation** — a separate process or host checks loop freshness, lineage gaps, observer blindness, and delivery health.

Key design principles baked into the architecture include: correctness and quality are treated as separate concerns; candidates are isolated from canonical state; a would-be winner is adversarially verified; every attempt retains exact evidence and lineage; and human decisions are labelled evidence with autonomy earned per class of action.

## Setup Path

Requirements are minimal: Git, Python 3.10+, and a POSIX shell. The validation helpers use only the Python standard library. After cloning, an optional script fetches AVO-lite source without executing it, and `init-ecosystem.sh` creates a local scaffold from public templates. Three scaffold profiles — `local`, `project`, and `live` — share one architecture but scale operational requirements to consequence. Every scaffold includes a `MISSION.md` so outcome, acceptance evidence, authority, non-goals, and stop conditions are explicit before any automation runs.

## Explicit Non-Goals

The README is direct about what the kit does not provide: a universal objective function, a fleet-wide write agent, an excuse to give an LLM production credentials, a replacement for domain tests or incident response, or a claim that worktree isolation constitutes a security sandbox. This scoping makes the kit a disciplined foundation rather than an overreaching framework.

## Current Status

The repository was created in late August 2026 and last updated in September 2026, with 40 stars and 1 fork at time of indexing. It is actively maintained on the `main` branch and includes contract tests and reward-hacking regression fixtures alongside the core architecture documentation.

## Features
- Three composable loop archetypes: optimize, maintain, observe→propose
- AVO-lite experiment kernel with disposable worktrees and hard scoring
- Adversarial verification of candidates before promotion
- Append-only ledger with full evidence and lineage retention
- JSON schemas for manifests, policy, and events
- Portable agent skill (self-improving-ecosystem SKILL.md)
- External deadman/health observation plane
- Scaffold profiles: local, project, and live
- Zero-dependency Python validation helpers
- Promotion, canary, quarantine, and rollback state machine
- Human-in-the-loop authority gates with explicit policy
- Reward-hacking regression test fixtures
- MISSION.md template for explicit outcome and stop conditions

## Integrations
AVO-lite, Git, Python 3.10+, POSIX shell

## Platforms
CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Version
main

## Links
- Website: https://github.com/Git-on-my-level/self-improving-agent-ecosystem
- Documentation: https://github.com/Git-on-my-level/self-improving-agent-ecosystem/tree/main/docs
- Repository: https://github.com/Git-on-my-level/self-improving-agent-ecosystem
- EveryDev.ai: https://www.everydev.ai/tools/self-improving-agent-ecosystem