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
1---2name: evolve3description: Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent.4---56# Evolve Command78$ARGUMENTS910Triggers the Meta-Architect to improve agent and skill definitions based on observed patterns.1112## Usage1314```bash15/evolve [source]16# /evolve learnings : analyze kb/learnings/ for recurring failure patterns17# /evolve last-failure : analyze the most recent error log18# /evolve agents : audit all agent definitions for gaps19```2021## Protocol2223### 1. Analyze2425Read the input source and extract actionable patterns:2627- **learnings**: grep `kb/learnings/` for entries tagged `failure`, `retry`, `timeout`, or `inefficiency`28- **last-failure**: read the most recent file in `kb/learnings/` and identify root cause29- **agents**: scan all `.md` files in `app/agents/` for missing tools, vague prompts, or mismatched model tiers3031### 2. Design3233Draft changes targeting the identified patterns:3435| Target | File Location | Change Type |36|--------|--------------|-------------|37| Agent definitions | `app/agents/*.md` | Frontmatter (tools, model), system prompt text |38| Skill definitions | `app/skills/*/SKILL.md` | Description, workflow steps, allowed-tools |39| Rules | `app/rules/` | New or updated rule files |4041Show the proposed diff to the user before applying.4243### 3. Implement4445Apply approved changes. After each edit:4647- Run `python3 scripts/validate.py` to confirm structural integrity48- Verify YAML frontmatter parses without errors49- Confirm no forbidden patterns (eval, exec, shell=True)5051### 4. Report5253Create a summary documenting what evolved:5455```markdown56## Evolution Report57- **Source**: [learnings | last-failure | agents]58- **Pattern found**: [description of failure/inefficiency]59- **Changes applied**:60 - `app/agents/[name].md`: [what changed and why]61- **Validation**: passed / failed62```6364## Rules6566- **MUST** delegate file edits to the `meta-architect` agent — this command is the trigger, the agent owns the changes67- **MUST** have a concrete failure signal (recurring error, named incident, repeated correction) before evolving — do not mutate based on vibes68- **NEVER** evolve an agent based on a **single** failure instance — evolution is pattern-matching, not reaction69- **NEVER** touch `.claude/agents/*` files directly from this skill; `meta-architect` is the only agent with that authority70- **CRITICAL**: every evolution names the trigger, the change, and the expected measurable shift (e.g., "reduces false routing of `/debug` to `/fix`")71- **MANDATORY**: run `scripts/validate.py --strict` after every applied change; roll back if the score drops7273## Gotchas7475- 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.76- `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.77- "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.78- 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.79- Evolution in isolation invites regression. Keep a changelog (`kb/learnings/` entries or `CHANGELOG.md`) so future sessions can see what was tried and reverted.8081## When NOT to Use8283- For a specific, known agent edit — call `meta-architect` directly84- For fixing a failing test — use `/fix` or `/debug`85- For auditing **current** skill/agent quality — use `scripts/evaluate_skills.py` and `scripts/audit_skills.py --ci`86- For creating a **new** agent — use `/agent-creator`87- When no recurring pattern exists (single data point) — wait and observe; do not over-fit to noise
softspark