auto-evolution

name

auto-evolution

description

Multi-agent auto-evolution system with hybrid mode — orchestrate review-execute-audit loops with 4 roles (Coordinator, Reviewer, Executor, Auditor). Supports manual subtasks (simple tasks) and automatic subtask generation via Reviewer (complex tasks). A single coordinator agent drives the loop by spawning sub-agents. Break goals into subtasks, auto-iterate with dual quality gates, and auto-package results. Use when: user wants autonomous task execution with built-in quality assurance.

auto-evolution

Category: Agent Orchestration / Meta-Skill Version: 2.0.0

---

Description

Multi-agent auto-evolution system — a coordinator agent drives an autonomous review → execute → audit loop by spawning specialized sub-agents for each role.

This is a meta-skill: it doesn't handle business logic. It orchestrates the loop so complex tasks get completed autonomously with dual quality gates (pre-execution review + post-execution audit).

Architecture (4 Roles)

Role	Responsibility	When Spawned	Recommended Model
Coordinator	Drives the loop, updates task state, spawns sub-agents	Always (heartbeat/cron)	Any (cost-efficient)
Reviewer	Pre-execution review, generates detailed subtasks	Complex tasks only	Strong (Sonnet/GPT-5.4)
Executor	Implements one subtask, runs verification	After review approves	Cost-effective (Qwen3.5-Plus)
Auditor	Post-execution audit, decides pass/retry	After execution completes	Strong (Sonnet/GPT-5.4)

Why 4 roles?

• Reviewer and Auditor are both quality gates but serve different purposes
• Reviewer ensures the plan is sound before work starts
• Auditor verifies the result matches the plan after work completes
• Executor is pure labor — follows instructions, no judgment needed

Cost control: Only Reviewer and Auditor need strong models. Coordinator and Executor can use cheap models.

---

🔄 Hybrid Mode (v2.0)

Task Complexity Assessment (5 dimensions, 1-5 points each):

Dimension	1 point	3 points	5 points
Code Lines	<100	200-500	>1000
Files	1-2	5-10	>20
Risk	Docs/Test	Feature improvement	Architecture change
Dependencies	None	3-5	Cross-system
Innovation	Routine fix	Feature enhancement	New feature

Task Classification:

Total Score	Task Type	Subtask Mode	Flow
5-10	Simple	Manual	Executor only
11-17	Medium	Manual (recommended) or Auto	Optional Reviewer
18-25	Complex	Auto (required)	Reviewer → Executor → Auditor

Usage:

# Create task (interactive)
node scripts/create-task.js

# Start Reviewer (complex tasks only)
node scripts/start-reviewer.js <task-id>

---

Core Modules

File	Purpose
scripts/heartbeat-coordinator.js	Coordinator: classify tasks, match capsules, spawn Reviewer/Executor/Auditor
scripts/generate-capsule.js	Generate Capsule from completed task, update index
scripts/capsule-matcher.js	Match new tasks against historical Capsules
scripts/category-stats.js	Category statistics + weekly evolution report
scripts/monitor.js	Monitor: detect stuck tasks (including 'reviewed'), clean locks, failure alerts
scripts/pack-skill.js	Package completed tasks → skill directories (with archive verification)
scripts/create-task.js	Interactive task creator (v2 schema compatible)
scripts/start-reviewer.js	Outputs structured Reviewer payload for coordinator to spawn
scripts/utils/classify.js	Shared task classification utilities (used by coordinator, matcher, generator)
config/task-schema.json	Task file JSON Schema v2

---

Setup

1. Initialize workspace

mkdir -p evolution/tasks evolution/archive evolution/test-results

2. Create a task

cp skills/auto-evolution/references/task-example.json evolution/tasks/task-001.json
# Edit with your goal and subtasks

3. Configure the coordinator

Option A: Heartbeat (recommended — in your agent's HEARTBEAT.md)

## Evolution Loop
1. Run `node skills/auto-evolution/scripts/heartbeat-coordinator.js`
2. Parse output: if phase=review → spawn Reviewer sub-agent
3. Apply review → if phase=execute → spawn Executor sub-agent
4. Apply execution → if phase=audit → spawn Auditor sub-agent
5. Apply audit → done for this tick

Option B: Cron

openclaw cron add --agent <your-agent> \
  --name "evolution-coordinator" \
  --every 5m \
  --session isolated \
  --timeout-seconds 300 \
  --message "Evolution heartbeat: scan and process tasks."

4. (Optional) Configure the monitor

openclaw cron add --agent <any-agent> \
  --name "evolution-monitor" \
  --every 10m \
  --session isolated \
  --timeout-seconds 120 \
  --message "Run: node skills/auto-evolution/scripts/monitor.js"

5. Configure models (optional)

Edit evolution/config/models.json to customize which models are used for each role:

{
  "roles": {
    "reviewer": "google/gemini-3.1-pro",
    "executor": "aiberm/gpt-5.4",
    "auditor": "google/gemini-3.1-pro",
    "coordinator": "bailian/qwen3.5-plus"
  }
}

Default: Scripts read from this config file. No environment variables needed.

6. Environment variables (optional)

export OPENCLAW_WORKSPACE=/path/to/workspace
export EVOLUTION_TASKS_DIR=/path/to/tasks

---

How It Works

Full Loop

Coordinator heartbeat
  → finds task (priority: reviewed > executing > pending)
  → if pending: spawn Reviewer → reviewed
  → if reviewed: spawn Executor → executing
  → if executing: spawn Auditor → pending (next) or completed ✅

State Machine

pending → reviewed → executing → pending (next subtask)
                         → completed (all done)
                         → packaged ✅
                         → capsule generated ✅

Key Rules

• One subtask per iteration — keeps cycles fast and reviewable
• Dual quality gates — Reviewer (before) + Auditor (after)
• Only mark completed when all subtasks done
• If Reviewer/Auditor API fails → wait and retry next heartbeat
• Monitor auto-resets tasks stuck > 10 minutes

---

Task File Format

See references/task-example.json for a complete example.

Required fields:

{
  "task_id": "task-001",
  "status": "pending",
  "goal": "What to build",
  "current_iteration": 0,
  "max_iterations": 10,
  "context": {
    "subtasks": ["Step 1", "Step 2", "Step 3"]
  },
  "history": []
}

---

CLI Usage

# Scan and output next phase prompt
node scripts/heartbeat-coordinator.js

# Filter by phase (only process tasks in that phase)
node scripts/heartbeat-coordinator.js --phase review
node scripts/heartbeat-coordinator.js --phase execute
node scripts/heartbeat-coordinator.js --phase audit

# Apply review result
node scripts/heartbeat-coordinator.js apply-review task-001.json review.txt

# Apply execution result
node scripts/heartbeat-coordinator.js apply-exec task-001.json exec.txt

# Apply audit result
node scripts/heartbeat-coordinator.js apply-audit task-001.json audit.txt

# Run monitor
node scripts/monitor.js

# Package completed tasks
node scripts/pack-skill.js

v2 CLI (new)

# Generate Capsules from archived tasks
node scripts/generate-capsule.js --backfill

# Match capsules for pending tasks
node scripts/capsule-matcher.js --all

# Category statistics
node scripts/category-stats.js

# Generate weekly evolution report
node scripts/category-stats.js --weekly

---

Design Philosophy

• 4-role architecture — Coordinator drives, Reviewer/Executor/Auditor specialize
• Dual quality gates — Review before, audit after — never skip either
• Model-agnostic — swap any model for any role
• One subtask per tick — predictable, reviewable, won't timeout
• Self-healing — monitor detects and fixes stuck states
• Cost-efficient — strong models only where judgment matters (Reviewer, Auditor)
• Experience accumulation — every completed task becomes a reusable Capsule
• Category-driven — 6 task categories (build/refactor/optimize/repair/test/integrate)