Bestehendes Team weiterentwickeln

Ein Team verbessern, umstrukturieren oder eine spezialisierte Variante eines Teams erstellen, das urspruenglich mit create-team verfasst wurde. Dieses Verfahren behandelt die Wartungsseite des Team-Lebenszyklus: Luecken anhand der Vorlage und der Koordinationsmuster bewerten, gezielte Verbesserungen an Zusammensetzung und Workflow anwenden, Versionen erhoehen und Registry sowie Querverweise synchron halten.

Wann verwenden

• Das Mitglieder-Roster eines Teams ist veraltet, nachdem Agenten hinzugefuegt, entfernt oder weiterentwickelt wurden
• Nutzer-Feedback zeigt Workflow-Engpaesse, unklare Uebergaben oder fehlende Perspektiven
• Das Koordinationsmuster passt nicht mehr zum tatsaechlichen Workflow des Teams (z.B. hub-and-spoke sollte parallel sein)
• Eine spezialisierte Variante wird neben dem Original benoetigt (z.B. r-package-review und r-package-review-security-focused)
• Die Verantwortlichkeiten der Teammitglieder ueberschneiden sich und benoetigen schaerfere Grenzen
• Der CONFIG-Block ist nicht mehr synchron mit der Prosa-Beschreibung oder der Mitgliederliste
• Ein Team muss in zwei kleinere Teams aufgeteilt oder zwei Teams muessen zusammengefuehrt werden

Eingaben

• Erforderlich: Pfad zur bestehenden Teamdatei zur Weiterentwicklung (z.B. teams/r-package-review.md)
• Erforderlich: Weiterentwicklungsausloser (Feedback, neue Agenten, Koordinationsfehler, Umfangsueberschneidung, Leistungsprobleme, Agenten-Weiterentwicklung)
• Optional: Ziel-Versions-Bump-Groesse (patch, minor, major)
• Optional: Ob stattdessen eine spezialisierte Variante erstellt werden soll (Standard: direkt verfeinern)

Vorgehensweise

Schritt 1: Das aktuelle Team bewerten

Die bestehende Teamdatei lesen und jeden Abschnitt gegen die Teamvorlage (teams/_template.md) bewerten:

Abschnitt	Was pruefen	Haeufige Probleme
Frontmatter	Alle Pflichtfelder (name, description, lead, version, author, coordination, members[])	Fehlende tags, veraltete version, falsches coordination
Zweck	Klare Multi-Agenten-Begruendung (mindestens zwei unterschiedliche Spezialgebiete)	Koennte von einem einzelnen Agenten erledigt werden
Teamzusammensetzung	Tabelle stimmt mit Frontmatter-Mitgliedern ueberein, keine ueberlappenden Verantwortlichkeiten	Veraltete Tabelle, duplizierte Schwerpunkte
Koordinationsmuster	Stimmt mit tatsaechlichem Workflow ueberein, ASCII-Diagramm vorhanden	Falsches Muster fuer den Workflow
Aufgabenzerlegung	Phasengliederung mit konkreten Aufgaben pro Mitglied	Vage Aufgaben, fehlende Phasen
CONFIG-Block	Gueltiges YAML zwischen Markierungen, stimmt mit Frontmatter und Prosa ueberein	Nicht synchron, fehlendes blocked_by, ungueltiges YAML
Verwendungsszenarien	2-3 realistische Aktivierungsaufforderungen	Platzhaltertext
Einschraenkungen	3-5 ehrliche Beschraenkungen	Fehlend oder zu generisch
Siehe auch	Gueltige Links zu Mitglieder-Agenten, verwandten Teams, Leitfaeden	Veraltete Links

# Teamdatei lesen
cat teams/<team-name>.md

# Pruefen ob alle Mitglieder-Agenten noch existieren
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

# Pruefen ob das Team von einem Leitfaden referenziert wird
grep -r "<team-name>" guides/*.md

Erwartet: Eine Liste spezifischer Luecken, Schwachstellen oder Verbesserungsmoeglichkeiten, nach Abschnitt geordnet.

Bei Fehler: Falls die Teamdatei nicht existiert oder kein Frontmatter hat, ist dieser Skill nicht anwendbar — stattdessen create-team verwenden, um sie von Grund auf zu erstellen.

Schritt 2: Weiterentwicklungsanforderungen sammeln

Identifizieren und kategorisieren, was die Weiterentwicklung ausgeloest hat:

Ausloser	Beispiel	Typischer Umfang
Nutzer-Feedback	"Reviews dauern zu lang, Agenten duplizieren Aufwand"	Verantwortlichkeiten schaerfen oder Muster aendern
Neuer Agent verfuegbar	Agent api-security-analyst wurde erstellt	Mitglied hinzufuegen
Agent weiterentwickelt	code-reviewer hat neue Skills bekommen	Mitglieder-Verantwortlichkeiten aktualisieren
Agent entfernt	deprecated-agent wurde eingestellt	Mitglied entfernen, Aufgaben neu zuweisen
Koordinationsfehler	Sequenzielles Team hat unabhaengige Teilaufgaben	Auf parallel wechseln
Umfangserweiterung	Team muss auch Deployment abdecken, nicht nur Review	Mitglied hinzufuegen oder Variante erstellen
Team zu gross	6+ Mitglieder verursachen Koordinationsaufwand	In zwei Teams aufteilen
Team zu klein	Einzelnes Mitglied erledigt den Grossteil der Arbeit	Mit anderem Team zusammenfuehren oder Mitglieder hinzufuegen

Die spezifischen Aenderungen vor der Bearbeitung dokumentieren:

- Frontmatter: neues Mitglied `api-security-analyst` mit Rolle "API Security Reviewer" hinzufuegen
- Teamzusammensetzung: Zeile zur Zusammensetzungstabelle hinzufuegen
- Aufgabenzerlegung: API-Sicherheits-Review-Aufgaben zur Ausfuehrungsphase hinzufuegen
- CONFIG-Block: Mitglieds- und Aufgabeneintraege hinzufuegen
- Siehe auch: Link zur neuen Agentendatei hinzufuegen

Erwartet: Eine konkrete Liste von Aenderungen, jede einem spezifischen Abschnitt der Teamdatei zugeordnet.

Bei Fehler: Falls die Aenderungen unklar sind, den Benutzer um Klaerung bitten, bevor fortgefahren wird.

Schritt 3: Weiterentwicklungsumfang waehlen

Diese Entscheidungsmatrix verwenden, um zu bestimmen, ob direkt verfeinert oder eine Variante erstellt werden soll:

Kriterium	Verfeinerung (direkt)	Spezialisierte Variante (neues Team)
Team-ID	Unveraendert	Neue ID: <team>-<specialty>
Dateipfad	Dieselbe .md-Datei	Neue Datei in teams/
Versions-Bump	Patch oder Minor	Beginnt bei 1.0.0
Koordination	Kann sich aendern	Kann vom Original abweichen
Registry	Bestehenden Eintrag aktualisieren	Neuer Eintrag hinzugefuegt
Urspruengliches Team	Direkt modifiziert	Unveraendert, erhaelt Querverweise in Siehe-auch

Verfeinerung: Waehlen beim Anpassen von Mitgliedern, Schaerfen von Verantwortlichkeiten, Beheben des CONFIG-Blocks oder Aendern des Koordinationsmusters. Das Team behaelt seine Identitaet.

Variante: Waehlen wenn die weiterentwickelte Version einem wesentlich anderen Anwendungsfall dient, ein anderes Koordinationsmuster erfordert oder eine andere Zielgruppe anspricht. Das Original bleibt fuer seinen bestehenden Anwendungsfall unveraendert.

Zusaetzliche Umfangsentscheidungen:

Situation	Massnahme
Team hat 6+ Mitglieder und ist langsam	In zwei fokussierte Teams aufteilen
Zwei Teams mit je 2 Mitgliedern decken angrenzende Domains ab	In ein Team mit 3-4 Mitgliedern zusammenfuehren
Das Koordinationsmuster des Teams ist falsch	Verfeinerung — Muster direkt aendern
Team braucht voellig anderen Lead	Verfeinerung wenn Lead existiert; zuerst Agenten erstellen wenn nicht

Erwartet: Eine klare Entscheidung — Verfeinerung, Variante, Aufteilen oder Zusammenfuehren — mit Begruendung.

Bei Fehler: Im Zweifel Verfeinerung verwenden. Aufteilen oder Zusammenfuehren hat groessere Auswirkungen und sollte mit dem Benutzer bestaetigt werden.

Schritt 4: Aenderungen an der Teamdatei anwenden

Fuer Verfeinerungen

Die bestehende Teamdatei direkt bearbeiten. Konsistenz ueber alle Abschnitte hinweg wahren, die die Teamzusammensetzung referenzieren:

1. Frontmatter members[]: Mitgliedereintraege hinzufuegen, entfernen oder aktualisieren (jeweils mit id, role, responsibilities)
2. Teamzusammensetzungs-Tabelle: Muss genau mit Frontmatter-Mitgliedern uebereinstimmen
3. Koordinationsmuster: Prosa und ASCII-Diagramm aktualisieren, falls das Muster sich aendert
4. Aufgabenzerlegung: Phasen und Aufgaben pro Mitglied ueberarbeiten, um neue Zusammensetzung widerzuspiegeln
5. CONFIG-Block: members- und tasks-Listen aktualisieren (siehe Schritt 5)
6. Verwendungsszenarien: Ueberarbeiten, falls sich die Aktivierungsausloser des Teams geaendert haben
7. Einschraenkungen: Aktualisieren, um neue Beschraenkungen widerzuspiegeln oder geloeste zu entfernen
8. Siehe auch: Agenten-Links aktualisieren und Verweise auf neue verwandte Teams oder Leitfaeden hinzufuegen

Diese Bearbeitungsregeln befolgen:

• Alle bestehenden Abschnitte erhalten — Inhalte hinzufuegen, keine Abschnitte entfernen
• Beim Hinzufuegen eines Mitglieds es zu ALLEN hinzufuegen: Frontmatter, Zusammensetzungstabelle, Aufgabenzerlegung und CONFIG-Block
• Beim Entfernen eines Mitglieds aus ALLEN jenen Stellen entfernen und seine Aufgaben neu zuweisen
• Jedes Mitglied pruefen: grep "id: agent-name" agents/_registry.yml
• Lead in der Mitgliederliste behalten — der Lead ist immer ein Mitglied

Fuer Varianten

# Original als Ausgangspunkt kopieren
cp teams/<team-name>.md teams/<team-name>-<specialty>.md

# Variante bearbeiten:
# - `name` in `<team-name>-<specialty>` aendern
# - `description` aktualisieren um spezialisierten Umfang widerzuspiegeln
# - `coordination`-Muster bei Bedarf anpassen
# - `version` auf "1.0.0" zuruecksetzen
# - Mitglieder, Aufgaben und CONFIG-Block fuer spezialisierten Anwendungsfall anpassen
# - Original in Siehe-auch als Allzweck-Alternative referenzieren

Erwartet: Die Teamdatei (verfeinert oder neue Variante) besteht die Bewertungscheckliste aus Schritt 1, mit intern konsistenten Abschnitten.

Bei Fehler: Falls eine Bearbeitung interne Konsistenz bricht (z.B. CONFIG-Block listet ein Mitglied auf, das nicht im Frontmatter steht), das Frontmatter members[] mit der Teamzusammensetzungs-Tabelle, Aufgabenzerlegung und CONFIG-Block vergleichen, um die Diskrepanz zu finden.

Schritt 4.5: Uebersetzte Varianten synchronisieren

Erforderlich, wenn Uebersetzungen existieren. Dieser Schritt gilt sowohl fuer menschliche Autoren als auch fuer KI-Agenten, die dieser Vorgehensweise folgen. Nicht ueberspringen — veraltete source_commit-Werte fuehren dazu, dass npm run validate:translations falsche Stale-Warnungen ueber alle Locales hinweg meldet.

Pruefen, ob Uebersetzungen fuer das weiterentwickelte Team existieren, und sie auf den neuen Stand der Quelle aktualisieren:

# Auf vorhandene Uebersetzungen pruefen
ls i18n/*/teams/<team-name>.md 2>/dev/null

Falls Uebersetzungen existieren

1. Aktuellen Quell-Commit-Hash ermitteln:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. source_commit im Frontmatter jeder uebersetzten Datei aktualisieren:

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

3. Dateien zur Neu-Uebersetzung markieren, indem betroffene Locales in der Commit-Nachricht aufgefuehrt werden:

evolve-team(<team-name>): <Beschreibung der Aenderungen>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <Liste der geaenderten Abschnitte>

4. Uebersetzungs-Statusdateien neu generieren:

npm run translation:status

Falls keine Uebersetzungen existieren

Keine Aktion noetig. Mit Schritt 5 fortfahren.

Fuer Varianten

Die Uebersetzung neuer Varianten aufschieben, bis sich die Variante stabilisiert hat (1-2 Versionen). Eine v1.0-Variante zu uebersetzen, die sich bis v1.2 erheblich aendern kann, verschwendet Aufwand. Uebersetzungen hinzufuegen, nachdem die Variante mindestens einmal verfeinert wurde.

Erwartet: Alle uebersetzten Dateien haben source_commit auf den aktuellen Commit aktualisiert. Die Commit-Nachricht vermerkt, welche Locales neu uebersetzt werden muessen und welche Abschnitte sich geaendert haben. npm run translation:status beendet mit 0.

Bei Fehler: Falls sed das Frontmatter-Feld nicht matcht, hat die uebersetzte Datei moeglicherweise eine nicht standardisierte Formatierung. Manuell oeffnen und pruefen, ob source_commit in ihrem YAML-Frontmatter vorhanden ist. Falls das Feld fehlt, wurde die Datei nicht korrekt angelegt — mit npm run translate:scaffold -- teams neu anlegen.

Schritt 5: Den CONFIG-Block aktualisieren

Der CONFIG-Block zwischen <!-- CONFIG:START --> und <!-- CONFIG:END --> muss mit den Prosa-Abschnitten synchron bleiben. Nach jeder Mitglieds- oder Aufgabenaenderung:

1. Pruefen ob jeder agent in CONFIG members einem Mitglied im Frontmatter entspricht
2. Pruefen ob jeder assignee in CONFIG tasks einer Mitglieds-Agenten-ID entspricht
3. blocked_by-Abhaengigkeiten aktualisieren, falls sich die Aufgabenreihenfolge geaendert hat
4. Sicherstellen, dass die Synthese-/Abschlussaufgabe alle vorausgehenden Aufgaben referenziert

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: <einzeilig>
    - name: synthesize-results
      assignee: <lead-agent>
      description: Alle Mitglieder-Ausgaben sammeln und synthetisieren
      blocked_by: [<prior-task-names>]

Erwartet: CONFIG-YAML ist gueltig, alle Agenten und Aufgaben stimmen mit dem Rest der Datei ueberein und blocked_by bildet einen gueltigen DAG.

Bei Fehler: Den CONFIG-Block-YAML separat parsen, um Syntaxfehler zu finden. Jeden assignee gegen die members-Liste kreuztesten.

Schritt 6: Version und Metadaten aktualisieren

Das Feld version im Frontmatter gemaess semantischer Versionierung erhoehen:

Aenderungstyp	Versions-Bump	Beispiel
Formulierungskorrektur, Siehe-auch-Aktualisierung	Patch: 1.0.0 -> 1.0.1	Veralteten Agenten-Link behoben
Neues Mitglied hinzugefuegt, Aufgaben ueberarbeitet	Minor: 1.0.0 -> 1.1.0	security-analyst-Mitglied hinzugefuegt
Koordinationsmuster geaendert, Team umstrukturiert	Major: 1.0.0 -> 2.0.0	Von hub-and-spoke auf parallel gewechselt

Auch aktualisieren:

• updated-Datum auf das aktuelle Datum
• tags falls sich der Domain-Abdeckungsbereich des Teams geaendert hat
• description falls der Teamzweck wesentlich anders ist
• coordination falls das Muster sich geaendert hat

Erwartet: Frontmatter-version und updated spiegeln Groesse und Datum der Aenderungen wider. Neue Varianten beginnen bei "1.0.0".

Bei Fehler: Falls die Version vergessen wird zu erhoehen, gibt es keine Moeglichkeit, den aktuellen Stand vom vorherigen zu unterscheiden. Immer vor dem Committen erhoehen.

Schritt 7: Registry und Querverweise aktualisieren

Fuer Verfeinerungen

Den bestehenden Eintrag in teams/_registry.yml aktualisieren, um das ueberarbeitete Frontmatter widerzuspiegeln:

# Registry-Eintrag des Teams finden
grep -A 10 "id: <team-name>" teams/_registry.yml

Felder description, lead, members und coordination aktualisieren, um der Teamdatei zu entsprechen. Keine Zaehleraenderung erforderlich.

Fuer Varianten

Das neue Team zu teams/_registry.yml hinzufuegen:

- id: <team-name>-<specialty>
  path: <team-name>-<specialty>.md
  lead: <lead-agent>
  members: [agent-1, agent-2, agent-3]
  coordination: <pattern>
  description: Einzeilige Beschreibung der spezialisierten Variante

Dann:

1. total_teams am Anfang der Registry hochzaehlen
2. Querverweis in Siehe-auch des urspruenglichen Teams hinzufuegen, der auf die Variante zeigt
3. Querverweis in Siehe-auch der Variante hinzufuegen, der auf das Original zeigt

README-Automatisierung ausfuehren:

npm run update-readmes

Erwartet: Registry-Eintrag stimmt mit Teamdatei-Frontmatter ueberein. npm run update-readmes beendet mit 0. Fuer Varianten entspricht total_teams der tatsaechlichen Anzahl der Teameintraege.

Bei Fehler: Falls die Registry-Zaehlung falsch ist, Eintraege mit grep -c "^ - id:" teams/_registry.yml zaehlen und die Zaehlung korrigieren.

Schritt 8: Das weiterentwickelte Team validieren

Die vollstaendige Validierungscheckliste durchfuehren:

• Teamdatei existiert am erwarteten Pfad
• YAML-Frontmatter wird fehlerfrei geparst
• version wurde erhoehen (Verfeinerung) oder auf "1.0.0" gesetzt (Variante)
• updated-Datum spiegelt heute wider
• Alle Pflichtabschnitte vorhanden: Purpose, Team Composition, Coordination Pattern, Task Decomposition, Configuration, Usage Scenarios, Limitations, See Also
• Frontmatter members[] stimmt mit Teamzusammensetzungs-Tabelle ueberein
• CONFIG-Block-Mitglieder stimmen mit Frontmatter-Mitgliedern ueberein
• CONFIG-Block-Aufgaben haben gueltige Zugewiesene und blocked_by-Referenzen
• Alle Mitglieder-Agenten-IDs existieren in agents/_registry.yml
• Lead-Agent erscheint in der Mitgliederliste
• Keine zwei Mitglieder teilen dieselbe primaere Verantwortlichkeit
• Registry-Eintrag existiert und stimmt mit Frontmatter ueberein
• Fuer Varianten: total_teams-Zaehler stimmt mit tatsaechlicher Anzahl auf der Festplatte ueberein
• Querverweise sind bidirektional (Original <-> Variante)
• git diff zeigt keine versehentlichen Loeschungen aus dem urspruenglichen Inhalt

# Frontmatter pruefen
head -25 teams/<team-name>.md

# Alle Mitglieder-Agenten pruefen
for agent in agent-a agent-b agent-c; do
  grep "id: $agent" agents/_registry.yml
done

# Teams auf Festplatte vs. Registry zaehlen
ls teams/*.md | grep -v template | wc -l
grep total_teams teams/_registry.yml

# Alle Aenderungen ueberpruefen
git diff

Erwartet: Alle Checklistenelemente bestanden. Das weiterentwickelte Team ist bereit zum Committen.

Bei Fehler: Jeden fehlschlagenden Punkt einzeln adressieren. Die haeufigsten Post-Weiterentwicklungs-Probleme sind CONFIG-Block-Drift und ein vergessenes updated-Datum.

Validierung

• Teamdatei existiert und hat gueltiges YAML-Frontmatter
• version-Feld spiegelt die vorgenommenen Aenderungen wider
• updated-Datum ist aktuell
• Alle Abschnitte vorhanden und intern konsistent
• Frontmatter members[], Teamzusammensetzungs-Tabelle und CONFIG-Block sind synchron
• Alle Mitglieder-Agenten-IDs existieren in agents/_registry.yml
• Lead-Agent ist in der Mitgliederliste
• CONFIG-Block-YAML ist gueltig und parsebar
• Registry-Eintrag stimmt mit der Teamdatei ueberein
• Fuer Varianten: neuer Eintrag in teams/_registry.yml mit korrektem Pfad
• Fuer Varianten: total_teams-Zaehler aktualisiert
• Querverweise sind gueltig (keine fehlerhaften Links in Siehe-auch)
• git diff bestaetigt keine versehentliche Inhaltsentfernung

Haeufige Stolperfallen

• CONFIG-Block-Drift: CONFIG-Block, Frontmatter und Prosa-Abschnitte muessen alle ueber Mitglieder und Aufgaben uebereinstimmen. Eines ohne die anderen zu aktualisieren ist der haeufigste Team-Weiterentwicklungsfehler. Nach jeder Aenderung alle drei kreuztesten.
• Version zu erhoehen vergessen: Ohne Versions-Bumps gibt es keine Moeglichkeit zu verfolgen, was sich wann geaendert hat. version und updated immer im Frontmatter vor dem Committen aktualisieren.
• Verwaiste Mitgliederreferenzen: Beim Entfernen eines Mitglieds muessen seine Aufgaben in der Aufgabenzerlegung und im CONFIG-Block neu zugewiesen oder entfernt werden. Verwaiste Zugewiesene verursachen Aktivierungsfehler.
• Falsches Koordinationsmuster nach der Weiterentwicklung: Parallel-faehige Mitglieder zu einem sequenziellen Team hinzufuegen oder ein Hub-and-Spoke-Team machen, bei dem Agenten die Ausgaben der anderen benoetigen. Die Musterentscheidung aus Schritt 4 von create-team nach jeder strukturellen Aenderung neu bewerten.
• Team nach dem Hinzufuegen von Mitgliedern zu gross: Teams mit mehr als 5 Mitgliedern sind schwer zu koordinieren. Falls die Weiterentwicklung das Team ueber 5 treibt, erwaegen in zwei fokussierte Teams aufzuteilen.
• Veraltete Siehe-auch nach Variantenerstellung: Beim Erstellen einer Variante muessen sowohl das Original als auch die Variante aufeinander verweisen. Einseitige Verweise lassen den Graphen unvollstaendig.

Verwandte Skills

• create-team — Grundlage fuer das Verfassen neuer Teams; evolve-team setzt voraus, dass dies urspruenglich befolgt wurde
• evolve-skill — das Parallelverfahren fuer das Weiterentwickeln von SKILL.md-Dateien
• evolve-agent — das Parallelverfahren fuer das Weiterentwickeln von Agentendefinitionen
• commit-changes — das weiterentwickelte Team mit einer beschreibenden Nachricht committen