evolve-team

# 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 | ```bash # 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: ```text - 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 ```bash # 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: ```bash # Check for existing translations ls i18n/*/teams/<team-name>.md 2>/dev/null ``` #### If translations exist 1. Current commit: ```bash npm run validate:translations ``` 2. Update each: ```bash 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> ``` 3. Flag → commit msg: ```text evolve(<team-name>): <description of changes> Translations flagged for re-sync: de, zh-CN, ja, es Changed sections: <list sections that changed> ``` 4. Regenerate: ```bash 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 ```yaml 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: ```bash # 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: ```yaml - 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: ```bash 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 ```bash # 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