evolve-team

# Evolve an Existing Team 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. ## When to Use - A team's member roster is outdated after agents were added, removed, or evolved - User feedback reveals workflow bottlenecks, unclear handoffs, or missing perspectives - The coordination pattern no longer fits the team's actual workflow (e.g., hub-and-spoke should be parallel) - A specialized variant is needed alongside the original (e.g., `r-package-review` and `r-package-review-security-focused`) - Team members' responsibilities overlap and need sharper boundaries - The CONFIG block is out of sync with the prose description or the members list - A team needs to be split into two smaller teams or two teams need to be merged ## Inputs - **Required**: Path to the existing team file to evolve (e.g., `teams/r-package-review.md`) - **Required**: Evolution trigger (feedback, new agents, coordination mismatch, scope overlap, performance issues, agent evolution) - **Optional**: Target version bump magnitude (patch, minor, major) - **Optional**: Whether to create a specialized variant instead of refining in-place (default: refine in-place) ## Procedure ### Step 1: Assess the Current Team 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 | ```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 ``` **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. ### Step 2: Gather Evolution Requirements 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: ```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 ``` **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. ### Step 3: Choose Evolution Scope 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. ### Step 4: Apply Changes to the Team File #### For Refinements Edit the existing team file directly. Maintain consistency across all sections that reference team composition: 1. **Frontmatter `members[]`**: Add, remove, or update member entries (each with `id`, `role`, `responsibilities`) 2. **Team Composition table**: Must match frontmatter members exactly 3. **Coordination Pattern**: Update prose and ASCII diagram if the pattern changes 4. **Task Decomposition**: Revise phases and per-member tasks to reflect new composition 5. **CONFIG block**: Update `members` and `tasks` lists to match (see Step 5) 6. **Usage Scenarios**: Revise if the team's activation triggers changed 7. **Limitations**: Update to reflect new constraints or remove resolved ones 8. **See Also**: Update agent links and add references to new related teams or guides Follow these editing rules: - Preserve all existing sections — add content, do not remove sections - When adding a member, add them to ALL of: frontmatter, composition table, task decomposition, and CONFIG block - When removing a member, remove from ALL of those locations and reassign their tasks - Verify each member agent exists: `grep "id: agent-name" agents/_registry.yml` - Keep the lead in the members list — the lead is always a member #### For 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 ``` **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. ### 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 team. 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/*/teams/<team-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 <team-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(<team-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 the CONFIG Block The CONFIG block between `<!-- CONFIG:START -->` and `<!-- CONFIG:END -->` must stay in sync with the prose sections. After any member or task change: 1. Verify every `agent` in CONFIG `members` matches a member in the frontmatter 2. Verify every `assignee` in CONFIG `tasks` matches a member agent id 3. Update `blocked_by` dependencies if task ordering changed 4. Ensure the synthesis/final task references all prerequisite tasks ```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>] ``` **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. ### Step 6: Update Version and Metadata 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 date - `tags` if the team's domain coverage changed - `description` if the team's purpose is materially different - `coordination` if the pattern 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 7: Update Registry and Cross-References #### For Refinements Update the existing entry in `teams/_registry.yml` to match the revised frontmatter: ```bash # 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. #### For Variants Add the new team to `teams/_registry.yml`: ```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` at the top of the registry 2. Add See Also cross-reference in the original team pointing to the variant 3. Add See Also cross-reference in the variant pointing to the original Run the README automation: ```bash 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. ### Step 8: Validate the Evolved Team Run the full validation checklist: - [ ] Team 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, Team Composition, Coordination Pattern, Task Decomposition, Configuration, Usage Scenarios, Limitations, See Also - [ ] Frontmatter `members[]` matches Team Composition table - [ ] CONFIG block members match frontmatter members - [ ] CONFIG block tasks have valid assignees and `blocked_by` references - [ ] All member agent IDs exist in `agents/_registry.yml` - [ ] Lead agent appears in the members list - [ ] No two members share the same primary responsibility - [ ] Registry entry exists and matches frontmatter - [ ] For variants: `total_teams` 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 -25 teams/<team-name>.md # Verify all member agents exist