██╗ ███████╗██╗ ██╗ ██████╗
╚═╝ ██╔════╝██║ ██║██╔═══██╗
██╗ █████╗ ██║ ██║██║ ██║
██║ ██╔══╝ ╚██╗ ██╔╝██║ ██║
██║ ███████╗ ╚████╔╝ ╚██████╔╝
╚═╝ ╚══════╝ ╚═══╝ ╚═════╝
Self-evolving AI agent framework ·
ievo.ai
# What is iEvo?
AI agents that learn from every mistake.
Not another orchestrator — a methodology layer.
Install agents like packages. They evolve collectively.
Three pillars:
✦ Spec-Driven Development — formal specs before code
✦ Agent Marketplace — ievo add <agent>
✦ Self-Evolution — genetic algorithm improves agents
─────────────────────────────────────────────────────────────
✓ Created ievo.yaml
✓ Created spec/
✓ Created plans/
✓ Created agents/
$ ievo add spec-writer architect coder
Resolving dependencies...
✓ spec-writer@0.3.2 — features → atomic REQs
✓ architect@0.2.1 — REQs → implementation plans
✓ coder@0.2.0 — plans → TDD code
3 agents installed. EVO skill included in each.
⚡ Loading memory...
⚡ Loading ROLE.md (tier 1: metadata)...
⚡ Loading ROLE.md (tier 2: instructions)...
✓ Ready. Conversation mode active.
spec-writer › Hello! I'm your Spec Writer. Tell me about
your project and I'll create formal requirements.
I'll also fill in my memory as we talk.
─────────────────────────────────────────────────────────────
SDD Pipeline — two human gates, everything between is automated
┌──────────┐ ┌──────────┐ ┌──────────┐
│ YOU │ ───▶ │ SPEC │ ───▶ │ARCHITECT │
│ (ideas) │ │ WRITER │ │ (plans) │
└──────────┘ └──────────┘ └──────────┘
│
review gate ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ YOU │ ◀─── │ REVIEWER │ ◀─── │ CODER │
│(approve) │ │(quality) │ │ (TDD) │
└──────────┘ └──────────┘ └──────────┘
─────────────────────────────────────────────────────────────
$ ievo list --marketplace
AGENT MODEL STATUS DESCRIPTION
─────────────────────────────────────────────────────────
spec-writer sonnet installed features → atomic REQs
architect opus installed REQs → implementation plans
coder sonnet installed plans → TDD code
tester sonnet available integration & acceptance
reviewer opus available quality & spec compliance
pm haiku available progress & priorities
─────────────────────────────────────────────────────────
DOMAIN AGENTS
─────────────────────────────────────────────────────────
medical-researcher sonnet available PubMed MCP integration
security-officer opus available vulnerability scanning
devops sonnet available K8s & CI/CD MCP
unity-developer sonnet available Unity engine MCP
─────────────────────────────────────────────────────────────
$ ievo learn log spec-writer --last 1
EVOLUTION #47 spec-writer 2026-02-28
Context: Agent assumed Node.js when project uses Python.
Action: Added rule: "NEVER assume tech stack. Check
CONTEXT.md or ask user."
Goal: Prevent tech-specific assumptions.
Fitness: 0.65 → 0.89 (+37%)
Status: mutation accepted ✓
─────────────────────────────────────────────────────────────
How self-evolution works:
Agent makes mistake
│
▼
┌──────────────────┐
│ EVO SKILL │ Root cause analysis
│ (in every agent) │ Classify → Analyze → Fix
└────────┬─────────┘
│
├──────────▶ ROLE.md updated (agent gets smarter)
│
▼
EVOLUTION_LOG.md Local lesson saved
│
│ ievo learn push (opt-in)
▼
┌─────────────────┐
│ CURATOR AGENT │ Reads logs from ALL projects
│ (marketplace) │ Finds patterns across users
└────────┬────────┘
│
├──────────▶ Genetic fitness test (eval suite)
│
▼
Marketplace updated ievo update → all projects improve
─────────────────────────────────────────────────────────────
$ ievo learn fitness spec-writer
Genetic fitness report — spec-writer
Genome : ROLE.md (42 rules, 8 sections)
Population: 147 variants across 23 projects
Eval suite: 12 test scenarios
v0.1.0 ████░░░░░░░░░░░░░░░░ 0.45
v0.2.0 ████████░░░░░░░░░░░░ 0.62
v0.3.0 █████████████░░░░░░░ 0.78
v0.3.2 ████████████████░░░░ 0.89 ← current
Top mutation: "Never assume tech stack" +12% fitness
Worst revert: "Always use bullet lists" -8% fitness
─────────────────────────────────────────────────────────────
$ cat agents/spec-writer/agent.yaml
name: spec-writer
version: 0.3.2
description: "Features → atomic, testable requirements"
model:
primary: sonnet # $3/1M tokens
fallback: haiku # $0.80/1M tokens
skills:
- evo # self-evolution (always included)
hooks:
on_session_start: "load_memory"
on_session_end: "save_memory"
on_error: "evo_analyze"
disclosure: # progressive loading
metadata: 100 # always loaded
instructions: 400 # on activation
resources: 600 # on demand
─────────────────────────────────────────────────────────────
3-tier model routing — 49% cost reduction vs all-Opus
AGENT MODEL $/1M tokens ROLE
─────────────────────────────────────────────────────
spec-writer sonnet $3.00 reasoning
architect opus $15.00 critical decisions
coder sonnet $3.00 follows plan
coder (tests) haiku $0.80 deterministic
reviewer opus $15.00 catches mistakes
pm haiku $0.80 status reports
─────────────────────────────────────────────────────────────
Three repos. One ecosystem.
ievo-marketplace/ Ready-made agents. Install & use.
ievo-sdk/ Dev template. Create new agents.
ievo-cli/ CLI tool. init, add, run, learn.
┌────────────────────────────────────────────────┐
│ iEvo ECOSYSTEM │
│ │
│ Marketplace Dev SDK CLI │
│ (agents) (Copier) (ievo) │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ SDD → REQs → Plan → TDD → EVO │ │
│ └──────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────┐ │
│ │ Claude API │ MCP │ File System │ Git │ │
│ └──────────────────────────────────────────┘ │
└────────────────────────────────────────────────┘
─────────────────────────────────────────────────────────────
Get started:
Docs coming soon
Discord coming soon