Agent Evolution Patterns

Agent Evolution Patterns

Agent evolution closes the continuous-learning feedback loop: validated instincts flow from sessions into agent instructions, making agents smarter over time without touching the versioned agent files in the repo.

When to Activate

Use this skill when:

• Understanding why an agent keeps making the same mistake across sessions
• Promoting a high-confidence instinct to a specific agent
• Auditing what a reviewer agent has learned (checking its overlay)
• Rolling back a bad instinct that changed agent behaviour for the worse
• Designing a new agent that should benefit from accumulated instincts

The Problem This Solves

Without agent evolution:
  Session → /learn-eval → instinct captured → instinct sits unused
  Next session: same agent makes the same mistake again

With agent evolution:
  Session → /learn-eval → instinct captured → /agent-evolution → overlay written
  Next session: agent applies the instinct automatically

System Overview

continuous-learning-v2
  └── instincts/*.md  (confidence scored, domain tagged)
         |
         | /agent-evolution (user-approved promotion)
         v
~/.clarc/agent-instincts/
  typescript-reviewer.md   ← overlay with learned bullets
  tdd-guide.md
  code-reviewer.md
         |
         | session-start.js (automatic injection)
         v
Claude session context
  └── "When invoking typescript-reviewer, apply these instincts: ..."

Overlay File Format

## Learned Instincts (auto-generated — do not edit manually)

- Always flag direct DOM manipulation in React code (confidence: 0.85, learned: 2026-02-15)
- Check for missing useCallback on event handlers passed to memoized children (confidence: 0.78, learned: 2026-02-20)

Rules:

• One bullet = one atomic instinct (one trigger, one action)
• Never edit overlay files manually — use /agent-evolution to add, /instinct-outcome to remove
• Overlay files live in ~/.clarc/agent-instincts/ (user-local, not in the repo)

Instinct-to-Agent Domain Mapping

| Domain | Target Agents | |--------|--------------| | typescript | typescript-reviewer, code-reviewer | | python | python-reviewer, code-reviewer | | golang | go-reviewer, code-reviewer | | rust | rust-reviewer, code-reviewer | | java | java-reviewer, code-reviewer | | ruby | ruby-reviewer, code-reviewer | | swift | swift-reviewer, code-reviewer | | testing | tdd-guide, e2e-runner | | security | security-reviewer, devsecops-reviewer | | architecture | architect, planner | | documentation | doc-updater | | performance | performance-analyst | | git | (applied globally via MEMORY.md, not per-agent) | | (unknown) | code-reviewer (catch-all) |

Promotion Workflow

Step 1: Review candidates

/agent-evolution

Output:

Found 3 instincts ready for agent promotion (threshold: 0.75):

1. "Always flag direct DOM manipulation in React code"
   Confidence: 0.85 | Domain: typescript | Learned: 2026-02-15
   → Proposed for: typescript-reviewer, code-reviewer
   [A]pply / [S]kip / [E]dit before applying

2. "Check useCallback on event handlers passed to memo children"
   Confidence: 0.78 | Domain: typescript | Learned: 2026-02-20
   → Proposed for: typescript-reviewer
   [A]pply / [S]kip / [E]dit before applying

Step 2: Approve each instinct

• A — Apply as-is to all proposed agents
• S — Skip; instinct stays in the store for next review
• E — Edit the instinct text, then apply the edited version

Step 3: Verify

/agent-instincts typescript-reviewer

Output:

Overlay for typescript-reviewer:

- Always flag direct DOM manipulation in React code (confidence: 0.85, learned: 2026-02-15)
- Check for missing useCallback on event handlers passed to memoized children (confidence: 0.78, learned: 2026-02-20)

Session Injection

At session start, session-start.js reads all overlay files and outputs them to Claude:

--- Agent Learned Instincts ---
When invoking these agents, apply the following learned instincts:

### typescript-reviewer
## Learned Instincts (auto-generated — do not edit manually)

- Always flag direct DOM manipulation in React code (confidence: 0.85, learned: 2026-02-15)
---

Log: [SessionStart] Agent instinct overlays loaded: typescript-reviewer (2 instincts), tdd-guide (1 instinct)

Rollback Protocol

If an instinct makes an agent worse:

1. /instinct-outcome  bad --reason "Made typescript-reviewer too aggressive"
   → Confidence drops below 0.75 promotion threshold

2. /agent-evolution
   → Low-confidence instinct appears as removal candidate

3. User confirms removal
   → Instinct removed from overlay file

Or remove directly without going through the promotion flow:

node scripts/agent-evolution.js remove typescript-reviewer "Always flag direct DOM"

Threshold Tuning

| Threshold | Effect | |-----------|--------| | 0.9 | Only near-certain patterns (very conservative) | | 0.75 | Default — good balance | | 0.6 | More candidates, higher noise risk | | 0.5 | Exploratory — review carefully before applying |

Anti-Patterns

• Editing overlay files manually — use /agent-evolution so metadata is tracked
• Promoting instincts without reviewing them — always read what you apply (/agent-instincts)
• Applying a git domain instinct to agents — git instincts apply globally via MEMORY.md
• Forgetting to roll back — if an agent behaves unexpectedly, check its overlay first

Underlying Script

node scripts/agent-evolution.js list [--threshold 0.75]
node scripts/agent-evolution.js apply  "" --confidence 0.80 --learned YYYY-MM-DD
node scripts/agent-evolution.js show []
node scripts/agent-evolution.js remove  ""

Related Commands

• /agent-evolution — interactive promotion workflow
• /agent-instincts — show current overlay content
• /instinct-outcome bad — roll back a promoted instinct
• /evolve — cluster instincts into new skills/commands/agents (different from agent overlays)
• /instinct-status — view all captured instincts with confidence scores

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: marvinrichter
• Source: marvinrichter/clarc
• License: MIT
• Homepage: https://marvinrichter.github.io/clarc

Install and usage instructions live in the source repository linked above.