# iEvo Architecture

## Overview

iEvo is a self-evolving multi-agent SDD (Spec-Driven Development) framework. Three repos form the ecosystem:

```
ievo-ai/cli           ← this repo (CLI tool)
ievo-ai/marketplace   ← agent registry (planned)
ievo-ai/sdk           ← dev template for new agents (planned)
```

## Core concepts

### SDD Pipeline

Kanban-flow pipeline with EVO quality gates at every transition:

```
Backlog → Spec Writer → [EVO] → Sprint → Architect → [EVO]
    → Coder → [EVO] → Acceptance → [EVO] → Docs → Done
         ↑                              │ FAIL → back to Coder
         └────────── sprint loop ───────┘
```

- **Kanban-flow**: continuous, no fixed time-boxes. Tasks flow as fast as the pipeline allows
- **EVO gates**: EVO agent observes every transition, analyzes quality, proposes ROLE.md mutations
- **Backlog**: raw ideas, Researcher proposals — not yet refined
- **Sprint**: agreed set of refined REQs — human approves what goes in
- **15-minute rule**: Architect decomposes into tasks of ≤15 min each
- **Acceptance loop**: FAIL → back to Coder with report, Coder fixes, resubmits
- **Coder escalation**: if plan doesn't work → Q-xxx-arch.md → Architect revises

### Agent marketplace

Agents are packages. Install like pip:

```bash
ievo add spec-writer    # pulls from marketplace
ievo add coder          # resolves dependencies automatically
```

Each agent has:
- `agent.yaml` — manifest (version, deps, model tier, hooks, disclosure)
- `ROLE.md` — instructions (progressive disclosure: metadata → instructions → resources)
- `memory/` — context, decisions, vocabulary, history (filled during sessions)
- `skills/evo/` — self-evolution skill
- `EVOLUTION_LOG.md` — mutation history

### EVO: Self-evolution

Every agent includes the EVO skill. When an agent makes a mistake:

```
Error detected → EVO skill analyzes → Root cause found → ROLE.md updated → Logged
```

The mutation is logged in `EVOLUTION_LOG.md`. Over time, agents improve.

### Genetic testing (Phase 3)

```
Genome     = ROLE.md (rules)
Mutation   = EVO change
Population = variants across projects
Fitness    = eval suite score
Selection  = keep improvements, rollback regressions
Crossover  = Curator combines best rules from different projects
```

### Curator agent (Phase 3)

Lives in marketplace. Reads EVOLUTION_LOGs from multiple projects (opt-in), finds patterns, proposes ROLE.md improvements, creates PRs.

## Project structure (after `ievo init`)

```
my-project/
├── CLAUDE.md           # project config (filled by spec-writer)
├── .ievo/
│   └── manifest.yaml   # manifest: installed agents + versions
├── spec/
│   ├── SPEC_INDEX.md
│   ├── requirements/
│   ├── changes/
│   ├── questions/
│   └── templates/
├── plans/
└── agents/
    ├── spec-writer/
    │   ├── agent.yaml
    │   ├── ROLE.md
    │   ├── memory/
    │   ├── skills/evo/
    │   └── EVOLUTION_LOG.md
    ├── architect/
    └── coder/
```

## agent.yaml format

```yaml
name: spec-writer
version: 0.3.2
description: "Features → atomic, testable requirements"

model:
  primary: sonnet       # main work ($3/1M tokens)
  fallback: haiku       # simple tasks ($0.80/1M tokens)

dependencies: []        # other agents this one needs
mcp: []                 # MCP servers required
plugins: []             # Claude Code plugins
skills: [evo]           # always includes EVO

hooks:
  on_install: null
  on_session_start: load_memory
  on_session_end: save_memory
  on_error: evo_analyze

disclosure:             # progressive ROLE.md loading
  metadata: 100         # always loaded (tokens)
  instructions: 400     # on activation
  resources: 600        # on demand

sandbox:                # Docker sandbox settings
  allowed_tools:        # tools available inside container
    - Read
    - Write
    - Edit
    - Glob
    - Grep
  network: false        # true adds WebFetch/WebSearch
  memory_mb: 2048       # container memory limit
  cpu_limit: 2.0        # CPU cores
  timeout_seconds: 3600 # max session duration
```

## Model cost strategy

| Agent | Model | $/1M tokens | Why |
|-------|-------|-------------|-----|
| spec-writer | sonnet | $3.00 | reasoning |
| architect | opus | $15.00 | critical decisions |
| coder | sonnet | $3.00 | follows plan |
| acceptance | sonnet | $3.00 | quality verification |
| docs | haiku | $0.80 | templated writing |
| evo | sonnet | $3.00 | error analysis |
| researcher | opus | $15.00 | literature analysis |
| pm (planned) | haiku | $0.80 | status reports |

~49% cost reduction vs all-Opus.

## Four evolution layers

```
Layer 1: Self-correction  Each agent retries internally (max 3 attempts per task)
Layer 2: EVO agent        Observes every pipeline transition, proposes ROLE.md mutations
Layer 3: Curator          Aggregates lessons across projects → improves marketplace agents
Layer 4: Eva              Scans external signals → improves iEvo platform itself
```

### Eva — the Mother agent

Eva is the meta-evolution layer. She doesn't improve agents — she improves the system that improves agents.

**Input signals:**

| Source | What Eva reads | Example action |
|--------|---------------|----------------|
| Sentry | CLI crashes, exceptions | Creates fix PR in ievo-cli |
| GitHub Issues | Feature requests, bugs | Prioritizes by frequency, proposes implementation |
| User reviews | "agents are slow to start" | Mutates progressive disclosure tiers |
| Bug reports from projects | agent.yaml missing `on_error` | Updates SDK template defaults |
| Marketplace metrics | Agent install/uninstall rates | Flags underperforming agents for review |
| Her own PR history | Which of Eva's fixes improved things | Evolves her own ROLE.md |

**How Eva works:**

```
External signals (Sentry, Issues, Reviews)
       │
       ▼
┌─────────────────┐
│      EVA        │   Classify → Prioritize → Root cause
│  (meta-agent)   │   Same genetic cycle as EVO but applied
│                 │   to the platform, not to agents
└────────┬────────┘
         │
         ├──────────▶ PR to ievo-cli        (fix CLI bugs)
         ├──────────▶ PR to ievo-sdk        (improve templates)
         ├──────────▶ PR to marketplace     (update agent defaults)
         ├──────────▶ Update to Eva herself (self-improvement)
         │
         ▼
   Fitness tracking
   (did the PR improve metrics?)
```

**Self-evolution recursion:**

Eva applies genetics to herself. Her ROLE.md mutates based on the fitness of her own PRs. If Eva's changes consistently improve the system — those mutations stick. If they don't — rollback. Eva literally evolves how to evolve.

**Safety:**
- Eva never merges her own PRs — human review required
- Rollback mechanism: if system metrics drop after Eva's change, auto-revert
- Rate limiting: max N mutations per week to prevent runaway evolution
- Eva's self-mutations require higher fitness threshold than regular mutations

## Implementation phases

1. **Phase 1** (current): CLI + marketplace basics — init, add, run, learn
2. **Phase 2**: Dev SDK, eval suites, progressive disclosure, 3-tier model routing
3. **Phase 3**: Curator, genetic testing, REST API for evolution logs, ACP
4. **Phase 4**: Gateway pattern (Telegram/Slack/GitHub), SQLite memory, cross-agent sharing
5. **Phase 5**: Eva — external signal ingestion, auto-PRs, self-evolution of the platform

## Communication

- **Phase 1**: File-based (agents read/write markdown files)
- **Phase 3+**: ACP (Agent Context Protocol) for direct agent-to-agent
- **Phase 4**: OpenClaw-style gateway for multi-channel input
- **Phase 5**: Eva connects to Sentry API, GitHub API, review platforms via MCP
