/evolve

name: evolve
description: "Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent."
effort: medium
disable-model-invocation: true
context: fork
agent: meta-architect
allowed-tools: Read, Edit, Grep, Glob

Evolve Command

$ARGUMENTS

Triggers the Meta-Architect to improve agent and skill definitions based on observed patterns.

Usage

/evolve [source]
# /evolve learnings        : analyze kb/learnings/ for recurring failure patterns
# /evolve last-failure     : analyze the most recent error log
# /evolve agents           : audit all agent definitions for gaps

Protocol

1. Analyze

Read the input source and extract actionable patterns:

• **learnings**: grep `kb/learnings/` for entries tagged `failure`, `retry`, `timeout`, or `inefficiency`
• **last-failure**: read the most recent file in `kb/learnings/` and identify root cause
• **agents**: scan all `.md` files in `app/agents/` for missing tools, vague prompts, or mismatched model tiers

2. Design

Draft changes targeting the identified patterns:

| Target | File Location | Change Type | |--------|--------------|-------------| | Agent definitions | `app/agents/*.md` | Frontmatter (tools, model), system prompt text | | Skill definitions | `app/skills/*/SKILL.md` | Description, workflow steps, allowed-tools | | Rules | `app/rules/` | New or updated rule files |

Show the proposed diff to the user before applying.

3. Implement

Apply approved changes. After each edit:

• Run `python3 scripts/validate.py` to confirm structural integrity
• Verify YAML frontmatter parses without errors
• Confirm no forbidden patterns (eval, exec, shell=True)

4. Report

Create a summary documenting what evolved:

## Evolution Report
- **Source**: [learnings | last-failure | agents]
- **Pattern found**: [description of failure/inefficiency]
- **Changes applied**:
  - `app/agents/[name].md`: [what changed and why]
- **Validation**: passed / failed

Rules

• **MUST** delegate file edits to the `meta-architect` agent — this command is the trigger, the agent owns the changes
• **MUST** have a concrete failure signal (recurring error, named incident, repeated correction) before evolving — do not mutate based on vibes
• **NEVER** evolve an agent based on a **single** failure instance — evolution is pattern-matching, not reaction
• **NEVER** touch `.claude/agents/*` files directly from this skill; `meta-architect` is the only agent with that authority
• **CRITICAL**: every evolution names the trigger, the change, and the expected measurable shift (e.g., "reduces false routing of `/debug` to `/fix`")
• **MANDATORY**: run `scripts/validate.py --strict` after every applied change; roll back if the score drops

Gotchas

• Small changes to an agent's description can silently re-route a dozen adjacent queries. After an evolution, run the skill router against a saved set of representative queries to confirm no drift.
• `kb/learnings/` entries without a `status: final` frontmatter field are often drafts — aggregating them treats speculative observations as validated patterns. Filter by status before mining.
• "Last-failure" often points at the **symptom**, not the root cause. A route-to-wrong-agent failure may actually be a description-field ambiguity; fix the description, not the router.
• Changes to agent frontmatter fields (`tools`, `model`) propagate to the installed global config only after `ai-toolkit update`. A locally-evolved agent still runs old behavior until the user reinstalls.
• Evolution in isolation invites regression. Keep a changelog (`kb/learnings/` entries or `CHANGELOG.md`) so future sessions can see what was tried and reverted.

When NOT to Use

• For a specific, known agent edit — call `meta-architect` directly
• For fixing a failing test — use `/fix` or `/debug`
• For auditing **current** skill/agent quality — use `scripts/evaluate_skills.py` and `scripts/audit_skills.py --ci`
• For creating a **new** agent — use `/agent-creator`
• When no recurring pattern exists (single data point) — wait and observe; do not over-fit to noise