evolve-agent

# Evolve an Existing Agent Improve, extend, or create an advanced variant of an agent that was originally authored with `create-agent`. This procedure covers the maintenance side of the agent lifecycle: assessing gaps against best practices, applying targeted improvements to the persona definition, bumping versions, and keeping the registry and cross-references in sync. ## When to Use - An agent's skills list is outdated after new skills were added to the library - User feedback reveals missing capabilities, unclear purpose, or weak examples - Tool requirements have changed (new MCP server, tool removed, privilege reduction needed) - An agent's scope needs sharpening — it overlaps with another agent or is too broad - An advanced variant is needed alongside the original (e.g., `r-developer` and `r-developer-advanced`) - Related agents or teams were added and cross-references in See Also are stale ## Inputs - **Required**: Path to the existing agent file to evolve (e.g., `agents/r-developer.md`) - **Required**: Evolution trigger (feedback, new skills, tool change, scope overlap, team integration, discovered limitations) - **Optional**: Target version bump magnitude (patch, minor, major) - **Optional**: Whether to create an advanced variant instead of refining in-place (default: refine in-place) ## Procedure ### Step 1: Assess the Current Agent Read the existing agent file and evaluate each section against the quality checklist from `guides/agent-best-practices.md`: | Section | What to Check | Common Issues | |---|---|---| | Frontmatter | All required fields present (`name`, `description`, `tools`, `model`, `version`, `author`) | Missing `tags`, stale `version`, wrong `priority` | | Purpose | Specific problem statement, not generic "helps with X" | Vague or overlapping with another agent | | Capabilities | Concrete, verifiable capabilities with bold lead-ins | Generic ("handles development"), no grouping | | Available Skills | Matches frontmatter `skills` list, all IDs exist in registry | Stale IDs, missing new skills, lists default skills unnecessarily | | Usage Scenarios | 2-3 realistic scenarios with invocation patterns | Placeholder text, unrealistic examples | | Examples | Shows user request and agent behavior | Missing or trivial examples | | Limitations | 3-5 honest constraints | Too few, too vague, or missing entirely | | See Also | Valid cross-references to agents, guides, teams | Stale links to renamed or removed files | ```bash # Read the agent file cat agents/<agent-name>.md # Check frontmatter parses head -20 agents/<agent-name>.md # Verify skills in frontmatter exist in registry grep "skills:" -A 20 agents/<agent-name>.md # Check if agent is referenced by any team grep -r "<agent-name>" teams/*.md ``` **Expected:** A list of specific gaps, weaknesses, or improvement opportunities organized by section. **On failure:** If the agent file does not exist or has no frontmatter, this skill does not apply — use `create-agent` instead to author it from scratch. ### Step 2: Gather Evolution Requirements Identify and categorize what triggered the evolution: | Trigger | Example | Typical Scope | |---|---|---| | User feedback | "Agent missed XSS in review" | Add skill or capability | | New skills available | Library gained `analyze-api-security` | Update skills list | | Tool change | New MCP server available | Add to tools/mcp_servers | | Scope overlap | Two agents both claim "code review" | Sharpen purpose and limitations | | Team integration | Agent added to a new team | Update See Also, verify capabilities | | Model upgrade | Task requires deeper reasoning | Change model field | | Privilege reduction | Agent has Bash but only reads files | Remove unnecessary tools | Document the specific changes needed before editing. List each change with its target section: ```text - Frontmatter: add `new-skill-id` to skills list - Capabilities: add "API Security Analysis" capability - Available Skills: add `new-skill-id` with description - Limitations: remove outdated limitation about missing skill - See Also: add link to new team that includes this agent ``` **Expected:** A concrete list of changes, each mapped to a specific section of the agent file. **On failure:** If the changes are unclear, consult the user for clarification before proceeding. Vague evolution goals produce vague improvements. ### Step 3: Choose Evolution Scope Use this decision matrix to determine whether to refine in-place or create a variant: | Criteria | Refinement (in-place) | Advanced Variant (new agent) | |---|---|---| | Agent ID | Unchanged | New ID: `<agent>-advanced` or `<agent>-<specialty>` | | File path | Same `.md` file | New file in `agents/` | | Version bump | Patch or minor | Starts at 1.0.0 | | Model | May change | Often higher (e.g., sonnet → opus) | | Registry | Update existing entry | New entry added | | Original agent | Modified directly | Left intact, gains See Also cross-reference | **Refinement**: Choose when updating skills, fixing documentation, sharpening scope, or adjusting tools. The agent keeps its identity. **Variant**: Choose when the evolved version would serve a substantially different audience, require a different model, or add capabilities that would make the original too broad. The original stays as-is for simpler use cases. **Expected:** A clear decision — refinement or variant — with rationale. **On failure:** If unsure, default to refinement. You can always extract a variant later; it is harder to merge one back. ### Step 4: Apply Changes to the Agent File #### For Refinements Edit the existing agent file directly: - **Frontmatter**: Update `skills`, `tools`, `tags`, `model`, `priority`, `mcp_servers` as needed - **Purpose/Capabilities**: Revise to reflect new scope or added functionality - **Available Skills**: Add new skills with descriptions, remove deprecated ones - **Usage Scenarios**: Add or revise scenarios to demonstrate new capabilities - **Limitations**: Remove constraints that no longer apply, add new honest ones - **See Also**: Update cross-references to reflect current agent/team/guide landscape Follow these editing rules: - Preserve all existing sections — add content, do not remove sections - Keep the Available Skills section in sync with the frontmatter `skills` list - Do not add default skills (`meditate`, `heal`) to frontmatter unless they are core to the agent's methodology - Verify each skill ID exists: `grep "id: skill-name" skills/_registry.yml` #### For Variants ```bash # Copy the original as a starting point cp agents/<agent-name>.md agents/<agent-name>-advanced.md # Edit the variant: # - Change `name` to `<agent-name>-advanced` # - Update `description` to reflect the advanced scope # - Raise `model` if needed (e.g., sonnet → opus) # - Reset `version` to "1.0.0" # - Expand skills, capabilities, and examples for the advanced use case # - Reference the original in See Also as a simpler alternative ``` **Expected:** The agent file (refined or new variant) passes the assessment checklist from Step 1. **On failure:** If an edit breaks the document structure, use `git diff` to review changes and revert partial edits with `git checkout -- <file>`. ### Step 4.5: Sync Translated Variants > **Required when translations exist.** Applies to human authors and AI agents > alike. **Do not bump `source_commit`** — an evolve run that changes English > without retranslating leaves every provenance field untouched, and the staleness > it creates is true rather than noise (#405, #616). Check which translations exist for the evolved agent. They are about to become stale, and this step is how you leave them honestly stale rather than falsely fresh: ```bash # Check for existing translations ls i18n/*/agents/<agent-name>.md 2>/dev/null ``` #### Which provenance field may move, and by what `scripts/lib/provenance.js` is the authority on this; the table is its summary. | Field | Moves when | Moved by | |---|---|---| | `source_commit` | a **human** retranslates against a newer English revision | that human, in the commit carrying the retranslated prose | | `fence_basis_commit` | frozen-fence bytes are propagated into the mirror **and verified** | `normalize-i18n-fences.js` when it does the propagating; `tools/provenance-field.mjs` when you propagate by hand, after `check:fence-propagation` passes | Which of those applies depends on **what you edited**, and getting this wrong is how a provenance field becomes a false claim: - **Prose only** — neither field moves. The mirror is genuinely stale afterwards, `npm run validate:translations` is right to say so, and bumping `source_commit` would assert a translation event that never happened, suppressing the one signal that would have surfaced the drift (#405, #616). - **A frozen fence** — `source_commit` still does not move, but the mirrors' fence bodies just changed, so every `fence_basis_commit` naming the old revision is now false. Step 2 below restamps them. Leaving them is the failure this table exists to prevent. - **A retranslation of one locale** — that locale's `source_commit` moves, in the commit carrying the prose, and the others' do not. `normalize-i18n-fences.js` is named above for the case where it does the propagating. It does **not** fire on a hand propagation — measured on this skill's own rewrite, where a preview reported five files to change and not one was a mirror of these skills. Do not wait for it to restamp what you copied by hand. Never repair a provenance field in bulk with `sed`. The form this step used to carry was a substitution anchored at `^source_commit` — column 0 — which silently no-ops on every mirror that nests provenance under `metadata:` at two-space indent: wrong and unreliable at once. Route any bulk field edit through `tools/provenance-field.mjs`, which is indent-aware and refuses to move `source_commit` unless you declare you are the human retranslating. (That anchored form is deliberately not reproduced here. #616's acceptance criterion is a grep, and prose quoting the thing it forbids would defeat the check that proves the thing is gone.) 1. Read which mirrors this change made stale, and leave them stale: ```bash npm run validate:translations ``` 2. If you edited a **frozen fence** in English, its bytes must reach all four mirrors in this same commit, verified by bytes rather than by the fence gate — that gate accepts a body from any English revision, so it cannot tell you whether your edit landed. Then restamp the mirrors you touched, because their old `fence_basis_commit` now names a revision whose fences they no longer carry: ```bash npm run check:fence-propagation -- --id <agent-name> node tools/provenance-field.mjs --field fence_basis_commit --set $(git rev-parse --short HEAD) <mirror paths> ``` 3. Flag the affected locales in the commit message, naming what changed: ```text evolve(<agent-name>): <description of changes> Translations now stale, source_commit deliberately NOT bumped: de, zh-CN, ja, es Changed sections: <list sections that changed> ``` 4. Regenerate the translation status files: ```bash npm run translation:status ``` #### If no translations exist No action needed. Proceed to Step 5. #### For variants Defer translation of new variants until the variant stabilizes (1-2 versions). Add translations after the variant has been refined at least once. **Expected:** `source_commit` unchanged everywhere. `npm run validate:translations` reports more stale mirrors than before — that count rising is the correct outcome of an evolve run, not a failure to repair. If you edited a frozen fence, `fence_basis_commit` on the mirrors you touched names the commit carrying the new bytes; if you edited only prose, no provenance field moved at all. If a frozen fence was edited, `check:fence-propagation` shows every mirror carrying the new bytes. `npm run translation:status` exits 0. **On failure:** If `check:fence-propagation` reports a mirror whose fence body differs, the byte-copy did not reach it: copy the English fence body verbatim into that mirror and re-run — and read its output rather than its exit code, which it shares with the `unalignable` case. If a frontmatter field genuinely needs a bulk edit, use `tools/provenance-field.mjs`; a substitution anchored at column 0 matches nothing in a mirror that nests provenance under `metadata:`, and reports success while changing nothing. ### Step 5: Update Version and Metadata Bump the `version` field in frontmatter following semantic versioning: | Change Type | Version Bump | Example | |---|---|---| | Typo fix, wording clarification | Patch: 1.0.0 → 1.0.1 | Fixed unclear limitation | | New skills added, capability expanded | Minor: 1.0.0 → 1.1.0 | Added 3 new skills from library | | Restructured purpose, changed model | Major: 1.0.0 → 2.0.0 | Narrowed scope, upgraded to opus | Also update: - `updated` date to the current date - `tags` if the agent's domain coverage changed - `description` if the purpose is materially different - `priority` if the agent's importance relative to others changed **Expected:** Frontmatter `version` and `updated` reflect the magnitude and date of changes. New variants start at `"1.0.0"`. **On failure:** If you forget to bump the version, the next evolution will have no way to distinguish the current state from the previous one. Always bump before committing. ### Step 6: Update Registry and Cross-References #### For Refinements Update the existing entry in `agents/_registry.yml` to match the revised frontmatter: ```bash # Find the agent's registry entry grep -A 10 "id: <agent-name>" agents/_registry.yml ``` Update `description`, `tags`, `tools`, and `skills` fields to match the agent file. No count change is needed. Update cross-references in other files if the agent's capabilities or name changed: ```bash # Check if any team references this agent grep -r "<agent-name>" teams/*.md # Check if any guide references this agent grep -r "<agent-name>" guides/*.md ``` #### For Variants Add the new agent to `agents/_registry.yml` in alphabetical position: ```yaml - id: <agent-name>-advanced path: agents/<agent-name>-advanced.md description: One-line description of the advanced variant tags: [domain, specialty, advanced] priority: normal tools: [Read, Write, Edit, Bash, Grep, Glob] skills: - skill-id-one - skill-id-two ``` Then: 1. Increment `total_agents` at the top of the registry 2. Add See Also cross-reference in the original agent pointing to the variant 3. Add See Also cross-reference in the variant pointing to the original 4. The `.claude/agents/` symlink to `agents/` means the variant is automatically discoverable **Expected:** Registry entry matches the agent file frontmatter. For variants, `total_agents` equals the actual number of agent entries. **On failure:** Count entries with `grep -c "^ - id:" agents/_registry.yml` and verify it matches `total_agents`. ### Step 7: Validate the Evolved Agent Run the full validation checklist: - [ ] Agent file exists at the expected path - [ ] YAML frontmatter parses without errors - [ ] `version` was bumped (refinement) or set to "1.0.0" (variant) - [ ] `updated` date reflects today - [ ] All required sections present: Purpose, Capabilities, Available Skills, Usage Scenarios, Examples, Limitations, See Also - [ ] Skills in frontmatter match the Available Skills section - [ ] All skill IDs exist in `skills/_registry.yml` - [ ] Default skills (`meditate`, `heal`) are not listed unless core to methodology - [ ] Tools list follows least-privilege principle - [ ] Registry entry exists and matches frontmatter - [ ] For variants: `total_agents` count matches actual count on disk - [ ] Cross-references are bidirectional (original ↔ variant) - [ ] `git diff` shows no accidental deletions from the original content ```bash # Verify frontmatter head -20 agents/<agent-name>.md # Check skills exist for skill in skill-a skill-b; do grep "id: $skill" skills/_registry.yml done # Count agents on disk vs registry ls agents/*.md | grep -v template | wc -l grep total_agents agents/_registry.yml # Review all changes git diff ``` **Expected:** All checklist items pass. The evolved agent is ready to commit. **On failure:** Address each failing item individually. The most common post-evolution issues are stale skill IDs in the Available Skills section and a forgotten `updated` date. ## Validation - [ ] Agent file exists and has valid YAML frontmatter - [ ] `version` field reflects the changes made - [ ] `updated` date is current - [ ] All sections present and internally consistent - [ ] Frontmatter `skills` array matches the Available Skills section - [ ] All skill IDs exist in `skills/_registry.yml` - [ ] Default skills not listed unnecessarily - [ ] Registry entry matches the agent file - [ ] For variants: new entry in `agents/_registry.yml` with correct path - [ ] For variants: `total_agents` count updated - [ ] Cross-references are valid (no broken links in See Also) - [ ] For refinements with translations: no provenance field moved; the now-stale locales named in the commit message - [ ] `git diff` confirms no accidental content removal ## Common Pitfalls - **Forgetting to bump version**: Without version bumps, there is no way to track what changed or when. Always update `version` and `updated` in frontmatter before committing. - **Skills list drift**: The frontmatter `skills` array and the `## Available Skills` section must stay in sync. Updating one without the other creates confusion for both humans and tooling. - **Listing default skills unnecessarily**: Adding `meditate` or `heal` to the frontmatter when they are already inherited from the registry. Only list them if they are core to the agent's methodology (e.g., `mystic`, `alchemist`). - **Tool over-provisioning during evolution**: Adding `Bash` or `WebFetch` during an evolution "just in case." Every tool addition should be justified by a specific new capability. - **Stale See Also after variant creation**: When creating a variant, both the original and the variant need to reference each other. One-directional references leave the graph incomplete.