evolve-teamEvolve an existing team composition by refining its structure in-place or creating a specialized variant. Covers assessing the current team against template and coordination patterns, gathering evolution requirements, choosing scope (adjust members, change coordination pattern, split/merge teams), applying changes to the team file and CONFIG block, updating…
Independent GitHub snapshot · Automated classification · Original documentation governs
Improve, restructure, or create a specialized variant of a team that was originally authored with create-team. This procedure covers the maintenance side of the team lifecycle: assessing gaps against the template and coordination patterns, applying targeted improvements to composition and workflow, bumping versions, and keeping the registry and cross-references in sync.
r-package-review and r-package-review-security-focused)teams/r-package-review.md)Read the existing team file and evaluate each section against the team template (teams/_template.md):
| Section | What to Check | Common Issues |
|---|---|---|
| Frontmatter | All required fields (name, description, lead, version, author, coordination, members[]) | Missing tags, stale version, wrong coordination |
| Purpose | Clear multi-agent justification (at least two distinct specialties) | Could be handled by a single agent |
| Team Composition | Table matches frontmatter members, no overlapping responsibilities | Stale table, duplicated focus areas |
| Coordination Pattern | Matches actual workflow, ASCII diagram present | Wrong pattern for the workflow |
| Task Decomposition | Phased breakdown with concrete tasks per member | Vague tasks, missing phases |
| CONFIG Block | Valid YAML between markers, matches frontmatter and prose | Out of sync, missing blocked_by, invalid YAML |
| Usage Scenarios | 2-3 realistic activation prompts | Placeholder text |
| Limitations | 3-5 honest constraints | Missing or too generic |
| See Also | Valid links to member agents, related teams, guides | Stale links |
# Read the team file
cat teams/<team-name>.md
# Verify all member agents still exist
grep "id:" teams/<team-name>.md | while read line; do
agent=$(echo "$line" | grep -oP '(?<=id: )[\w-]+')
grep "id: $agent" agents/_registry.yml || echo "MISSING: $agent"
done
# Check if the team is referenced by any guide
grep -r "<team-name>" guides/*.md
Expected: A list of specific gaps, weaknesses, or improvement opportunities organized by section.
On failure: If the team file does not exist or has no frontmatter, this skill does not apply — use create-team instead to author it from scratch.
Identify and categorize what triggered the evolution:
| Trigger | Example | Typical Scope |
|---|---|---|
| User feedback | "Reviews take too long, agents duplicate effort" | Sharpen responsibilities or change pattern |
| New agent available | api-security-analyst agent was created | Add member |
| Agent evolved | code-reviewer gained new skills | Update member responsibilities |
| Agent removed | deprecated-agent was retired | Remove member, reassign tasks |
| Coordination mismatch | Sequential team has independent subtasks | Change to parallel |
| Scope expansion | Team needs to cover deployment, not just review | Add member or create variant |
| Team too large | 6+ members causing coordination overhead | Split into two teams |
| Team too small | Single member does most of the work | Merge with another team or add members |
Document the specific changes needed before editing:
- Frontmatter: add new member `api-security-analyst` with role "API Security Reviewer"
- Team Composition: add row to composition table
- Task Decomposition: add API security review tasks to execution phase
- CONFIG block: add member and tasks entries
- See Also: add link to new agent file
Expected: A concrete list of changes, each mapped to a specific section of the team file.
On failure: If the changes are unclear, consult the user for clarification before proceeding. Vague evolution goals produce vague improvements.
Use this decision matrix to determine whether to refine in-place or create a variant:
| Criteria | Refinement (in-place) | Specialized Variant (new team) |
|---|---|---|
| Team ID | Unchanged | New ID: <team>-<specialty> |
| File path | Same .md file | New file in teams/ |
| Version bump | Patch or minor | Starts at 1.0.0 |
| Coordination | May change | May differ from original |
| Registry | Update existing entry | New entry added |
| Original team | Modified directly | Left intact, gains See Also cross-reference |
Refinement: Choose when adjusting members, sharpening responsibilities, fixing the CONFIG block, or changing the coordination pattern. The team keeps its identity.
Variant: Choose when the evolved version would serve a substantially different use case, require a different coordination pattern, or target a different audience. The original stays as-is for its existing use case.
Additional scope decisions:
| Situation | Action |
|---|---|
| Team has 6+ members and is slow | Split into two focused teams |
| Two teams of 2 cover adjacent domains | Merge into one team of 3-4 |
| Team's coordination pattern is wrong | Refinement — change pattern in-place |
| Team needs entirely different lead | Refinement if lead exists; create agent first if not |
Expected: A clear decision — refinement, variant, split, or merge — with rationale.
On failure: If unsure, default to refinement. Splitting or merging teams has higher blast radius and should be confirmed with the user.
Edit the existing team file directly. Maintain consistency across all sections that reference team composition:
members[]: Add, remove, or update member entries (each with id, role, responsibilities)members and tasks lists to match (see Step 5)Follow these editing rules:
grep "id: agent-name" agents/_registry.yml# Copy the original as a starting point
cp teams/<team-name>.md teams/<team-name>-<specialty>.md
# Edit the variant:
# - Change `name` to `<team-name>-<specialty>`
# - Update `description` to reflect the specialized scope
# - Adjust `coordination` pattern if needed
# - Reset `version` to "1.0.0"
# - Modify members, tasks, and CONFIG block for the specialized use case
# - Reference the original in See Also as a general-purpose alternative
Expected: The team file (refined or new variant) passes the assessment checklist from Step 1, with all sections internally consistent.
On failure: If an edit breaks internal consistency (e.g., CONFIG block lists a member not in frontmatter), compare the frontmatter members[] against the Team Composition table, Task Decomposition, and CONFIG block to find the mismatch.
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 team. They are about to become stale, and this step is how you leave them honestly stale rather than falsely fresh:
# Check for existing translations
ls i18n/*/teams/<team-name>.md 2>/dev/null
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:
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).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.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.)
npm run validate:translations
fence_basis_commit now names a
revision whose fences they no longer carry:npm run check:fence-propagation -- --id <team-name>
node tools/provenance-field.mjs --field fence_basis_commit --set $(git rev-parse --short HEAD) <mirror paths>
evolve(<team-name>): <description of changes>
Translations now stale, source_commit deliberately NOT bumped: de, zh-CN, ja, es
Changed sections: <list sections that changed>
npm run translation:status
No action needed. Proceed to Step 5.
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.
The CONFIG block between <!-- CONFIG:START --> and <!-- CONFIG:END --> must stay in sync with the prose sections. After any member or task change:
agent in CONFIG members matches a member in the frontmatterassignee in CONFIG tasks matches a member agent idblocked_by dependencies if task ordering changedteam:
name: <team-name>
lead: <lead-agent>
coordination: <pattern>
members:
- agent: <agent-id>
role: <role-title>
subagent_type: <agent-id>
tasks:
- name: <task-name>
assignee: <agent-id>
description: <one-line>
- name: synthesize-results
assignee: <lead-agent>
description: Collect and synthesize all member outputs
blocked_by: [<prior-task-names>]
Expected: CONFIG YAML is valid, all agents and tasks are consistent with the rest of the file, and blocked_by forms a valid DAG.
On failure: Parse the CONFIG block YAML separately to find syntax errors. Cross-check every assignee against the members list.
Bump the version field in frontmatter following semantic versioning:
| Change Type | Version Bump | Example |
|---|---|---|
| Wording fix, See Also update | Patch: 1.0.0 → 1.0.1 | Fixed stale agent link |
| New member added, tasks revised | Minor: 1.0.0 → 1.1.0 | Added security-analyst member |
| Coordination pattern changed, team restructured | Major: 1.0.0 → 2.0.0 | Changed from hub-and-spoke to parallel |
Also update:
updated date to the current datetags if the team's domain coverage changeddescription if the team's purpose is materially differentcoordination if the pattern changedExpected: 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.
Update the existing entry in teams/_registry.yml to match the revised frontmatter:
# Find the team's registry entry
grep -A 10 "id: <team-name>" teams/_registry.yml
Update description, lead, members, and coordination fields to match the team file. No count change is needed.
Add the new team to teams/_registry.yml:
- id: <team-name>-<specialty>
path: <team-name>-<specialty>.md
lead: <lead-agent>
members: [agent-1, agent-2, agent-3]
coordination: <pattern>
description: One-line description of the specialized variant
Then:
total_teams at the top of the registryRun the README automation:
npm run update-readmes
Expected: Registry entry matches the team file frontmatter. npm run update-readmes exits 0. For variants, total_teams equals the actual number of team entries.
On failure: If the registry count is wrong, count entries with grep -c "^ - id:" teams/_registry.yml and correct the count. If README automation fails, verify package.json exists and js-yaml is installed.
Run the full validation checklist:
version was bumped (refinement) or set to "1.0.0" (variant)updated date reflects todaymembers[] matches Team Composition tableblocked_by referencesagents/_registry.ymltotal_teams count matches actual count on diskgit diff shows no accidental deletions from the original content# Verify frontmatter
head -25 teams/<team-name>.md
# Verify all member agents exist
for agent in agent-a agent-b agent-c; do
grep "id: $agent" agents/_registry.yml
done
# Count teams on disk vs registry
ls teams/*.md | grep -v template | wc -l
grep total_teams teams/_registry.yml
# Review all changes
git diff
Expected: All checklist items pass. The evolved team is ready to commit.
On failure: Address each failing item individually. The most common post-evolution issues are CONFIG block drift (members or tasks not matching the prose) and a forgotten updated date.
version field reflects the changes madeupdated date is currentmembers[], Team Composition table, and CONFIG block are in syncagents/_registry.ymlteams/_registry.yml with correct pathtotal_teams count updatedgit diff confirms no accidental content removalversion and updated in frontmatter before committing.create-team Step 4 after any structural change.create-team — foundation for authoring new teams; evolve-team assumes this was followed originallyevolve-skill — the parallel procedure for evolving SKILL.md filesevolve-agent — the parallel procedure for evolving agent definitionscommit-changes — commit the evolved team with a descriptive message