Evolve an Existing Team

Improve, restructure, or create specialized variant of team originally made w/ create-team. Covers maintenance: assess gaps vs template + coordination patterns, apply targeted improvements to composition + workflow, bump versions, sync registry + cross-refs.

Use When

• Roster outdated after agents added/removed/evolved
• Feedback → workflow bottlenecks, unclear handoffs, missing perspectives
• Coordination pattern no longer fits workflow (hub-and-spoke should be parallel)
• Specialized variant needed alongside original (e.g., r-package-review + r-package-review-security-focused)
• Member responsibilities overlap → need sharper boundaries
• CONFIG block out of sync w/ prose or members
• Team needs split into 2 smaller or 2 teams need merge

In

• Required: Path to existing team file (e.g., teams/r-package-review.md)
• Required: Evolution trigger (feedback, new agents, coordination mismatch, scope overlap, perf issues, agent evolution)
• Optional: Version bump magnitude (patch, minor, major)
• Optional: Create specialized variant instead refine (default: refine in-place)

Do

Step 1: Assess Current

Read existing + eval each section vs template (teams/_template.md):

Section	Check	Common Issues
Frontmatter	Required fields (name, description, lead, version, author, coordination, members[])	Missing tags, stale version, wrong coordination
Purpose	Clear multi-agent justification (≥2 specialties)	Could be 1 agent
Team Composition	Table matches frontmatter, no overlap	Stale table, duplicated focus
Coordination Pattern	Matches workflow, ASCII diagram present	Wrong pattern
Task Decomposition	Phased breakdown + concrete per-member	Vague, missing phases
CONFIG Block	Valid YAML between markers, matches frontmatter + prose	Out of sync, missing blocked_by, invalid YAML
Usage Scenarios	2-3 realistic activation prompts	Placeholder
Limitations	3-5 honest	Missing/generic
See Also	Valid links to agents, teams, guides	Stale

# 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

→ List specific gaps by section.

If err: no file or no frontmatter → skill N/A, use create-team.

Step 2: Gather Reqs

Identify + categorize trigger:

Trigger	Example	Scope
User feedback	"Reviews too long, agents duplicate"	Sharpen responsibilities or pattern
New agent	api-security-analyst created	Add member
Agent evolved	code-reviewer new skills	Update member responsibilities
Agent removed	deprecated-agent retired	Remove + reassign tasks
Coordination mismatch	Sequential team has indep subtasks	Change to parallel
Scope expansion	Cover deployment not just review	Add member or variant
Team too large	6+ members coordination overhead	Split into 2
Team too small	Single member does most	Merge w/ another or add

Document changes + sections:

- 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

→ Concrete list mapped to sections.

If err: unclear → consult user. Vague → vague.

Step 3: Choose Scope

Decision matrix:

Criteria	Refinement (in-place)	Specialized Variant (new)
Team ID	Unchanged	<team>-<specialty>
File path	Same .md	New file teams/
Version bump	Patch/minor	Starts 1.0.0
Coordination	May change	May differ
Registry	Update existing	New entry
Original	Modified directly	Left intact, gains See Also

Refinement: Adjust members, sharpen responsibilities, fix CONFIG, change coordination. Keeps identity.

Variant: Diff use case, diff coordination, diff audience. Original stays for existing use.

Additional:

Situation	Action
6+ members, slow	Split into 2 focused
2 teams of 2 adjacent domains	Merge into 1 of 3-4
Wrong coordination	Refinement — change in-place
Different lead	Refinement if lead exists; create agent first if not

→ Clear decision — refine, variant, split, merge — rationale.

If err: unsure → default refinement. Split/merge higher blast radius → confirm w/ user.

Step 4: Apply Changes

Refinements

Edit directly. Consistency across all sections referencing composition:

1. Frontmatter members[]: Add/remove/update (each id, role, responsibilities)
2. Team Composition table: Match frontmatter exactly
3. Coordination Pattern: Update prose + ASCII if changes
4. Task Decomposition: Revise phases + per-member
5. CONFIG block: Update members + tasks (Step 5)
6. Usage Scenarios: Revise if triggers changed
7. Limitations: Update new constraints, remove resolved
8. See Also: Update agent links, new refs

Rules:

• Preserve all sections — add not remove
• Adding member → add ALL: frontmatter, composition table, task decomposition, CONFIG
• Removing → remove ALL + reassign tasks
• Verify each: grep "id: agent-name" agents/_registry.yml
• Lead stays in members — lead always a member

Variants

# 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

→ File (refined/variant) passes Step 1, all sections internally consistent.

If err: edit breaks consistency (CONFIG lists member not in frontmatter) → compare frontmatter members[] vs Composition + Decomposition + CONFIG → find mismatch.

Step 4.5: Sync Translated Variants

Required when translations exist. Human authors + AI agents. No skip — stale source_commit → npm run validate:translations false staleness.

Check + update:

# Check for existing translations
ls i18n/*/teams/<team-name>.md 2>/dev/null

If translations exist

1. Current commit:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. Update each:

for locale_file in i18n/*/teams/<team-name>.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done

3. Flag → commit msg:

evolve(<team-name>): <description of changes>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <list sections that changed>

4. Regenerate:

npm run translation:status

If no translations exist

No action. Step 5.

Variants

Defer until stabilize (1-2 versions). Add after ≥1 refinement.

→ All translated source_commit updated. npm run translation:status exits 0.

If err: sed fails → open manually, verify source_commit in YAML. Missing → re-scaffold npm run translate:scaffold -- teams <team-name> <locale>.

Step 5: CONFIG Block

CONFIG between <!-- CONFIG:START --> + <!-- CONFIG:END --> must sync w/ prose. After member/task change:

1. Every agent in CONFIG members matches frontmatter member
2. Every assignee in CONFIG tasks matches member id
3. Update blocked_by if ordering changed
4. Synthesis/final task references all prereq

team:
  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>]

→ CONFIG valid YAML, agents + tasks consistent, blocked_by valid DAG.

If err: parse CONFIG YAML separately → syntax errs. Cross-check every assignee vs members.

Step 6: Version + Metadata

Bump version semver:

Change	Bump	Example
Wording fix, See Also update	Patch: 1.0.0 → 1.0.1	Fixed stale agent link
New member, tasks revised	Minor: 1.0.0 → 1.1.0	Added security-analyst
Coordination changed, restructured	Major: 1.0.0 → 2.0.0	hub-and-spoke → parallel

Also update:

• updated date = today
• tags if coverage changed
• description if purpose materially diff
• coordination if pattern changed

→ version + updated reflect magnitude + date. Variants start "1.0.0".

If err: forget bump → no track. Always before commit.

Step 7: Registry + Cross-Refs

Refinements

Update existing in teams/_registry.yml → match frontmatter:

# Find the team's registry entry
grep -A 10 "id: <team-name>" teams/_registry.yml

Update description, lead, members, coordination → match file. No count change.

Variants

Add new to registry:

- 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:

1. Increment total_teams top
2. Add See Also in original → variant
3. Add See Also in variant → original

README automation:

npm run update-readmes

→ Registry matches frontmatter. npm run update-readmes exits 0. Variants: total_teams matches actual.

If err: count wrong → grep -c "^ - id:" teams/_registry.yml + correct. README automation fails → verify package.json + js-yaml installed.

Step 8: Validate

Full checklist:

• File exists expected path
• YAML frontmatter parses
• version bumped (refinement) or "1.0.0" (variant)
• updated today
• All sections: Purpose, Team Composition, Coordination, Task Decomposition, Configuration, Usage Scenarios, Limitations, See Also
• Frontmatter members[] matches Composition table
• CONFIG members match frontmatter
• CONFIG tasks valid assignees + blocked_by refs
• All member IDs in agents/_registry.yml
• Lead in members list
• No 2 members share same primary responsibility
• Registry matches frontmatter
• Variants: total_teams matches disk
• Cross-refs bidirectional (original ↔ variant)
• git diff no accidental deletions

# 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

→ All pass. Ready commit.

If err: address each. Most common: CONFIG block drift (members or tasks not matching prose) + forgotten updated.

Check

• File exists + valid YAML
• version reflects changes
• updated current
• All sections consistent
• Frontmatter members[], Composition, CONFIG in sync
• All member IDs in registry
• Lead in members
• CONFIG YAML valid + parseable
• Registry matches file
• Variants: new entry correct path
• Variants: total_teams updated
• Cross-refs valid (no broken See Also)
• Refinements w/ translations: source_commit updated all locales
• git diff no accidental removal

Traps

• CONFIG block drift: CONFIG + frontmatter + prose must agree on members + tasks. Update 1 w/o others = most common team evolution err. After every change → cross-check all 3.
• Forget version bump: No track. Always version + updated before commit.
• Stale translations: Every evolution → up to 4 locale stale. Check ls i18n/*/teams/<team-name>.md + update source_commit or flag.
• Orphaned member refs: Remove member → tasks in Decomposition + CONFIG must reassign/remove. Orphan assignees → activation failures.
• Wrong coordination post-evolution: Adding parallel-capable to sequential, or hub-and-spoke where agents need each other's output. Re-evaluate pattern decision create-team Step 4 after structural change.
• Team too large after add: >5 members hard coordinate. Past 5 → split into 2 focused.
• Stale See Also after variant: Original + variant reference each other. One-directional → incomplete.

→

• create-team — foundation new teams; evolve-team assumes this followed
• evolve-skill — parallel for SKILL.md
• evolve-agent — parallel for agents
• commit-changes — commit evolved team w/ descriptive msg