Repository Agent Team Orchestration (Meta-Projekt-Team-Orchestr…

Repository Agent Team Orchestrierung (Meta-Projekt-Team-Orchestrierung)

Autonome Fertigkeit zum Zusammenstellen, Prüfen und Optimieren eines spezialisierten Agententeams, das auf das Projekt zugeschnitten ist. Die Fertigkeit analysiert die Repository-Struktur, identifiziert erforderliche Spezialisierungen (GitHub-Manager, DevOps, QA, UI/UX, Sicherheit, Produktanalyst, Recht, Schiedsrichter usw.), materialisiert isolierte Profile in .agents/team/ und richtet strenge Koordinationsprotokolle ein (Human-in-the-Loop, benutzergesteuerte Übergaben, unveränderliche Notizen, evidenzbasierte Schiedsgerichtsbarkeit).

---

Wann die Fertigkeit aufgerufen werden sollte

• Der Benutzer fordert: "Agententeam zusammenstellen", "Projekt mit Rollen besetzen", "Agentenrollen konfigurieren", "Teamaktivität prüfen", "Teamrollen überprüfen", "Agententeamzusammensetzung aktualisieren".
• Neue wichtige Technologieebenen werden in das Projekt eingeführt (Docker, CI/CD, mobile UI, Datenbank, externe Zahlungsintegrationen), die eine dedizierte Bereichsverwaltung erfordern.

---

Ausführungsschritte

Phase 1: Schneller Repository-Scan (Marker-Inspektion)

Bevor Rollen definiert werden, muss der Agent wichtige Projektmarker inspizieren:

1. Hosting- und CI-Infrastruktur: Vorhandensein von .github/-Verzeichnis, Workflows, Pull-Request-Vorlagen, Issue-Vorlagen.
2. Lizenzen und Open-Source-Governance: Vorhandensein von LICENSE, Copyrights, CONTRIBUTING.md, Abhängigkeitsmanifesten.
3. Containerisierung und Orchestrierung: Dockerfile, docker-compose*.yml, k8s/, helm/.
4. Testinfrastruktur: tests/-Verzeichnis, pytest.ini, vitest.config.*, Test-Fixtures.
5. Sicherheit und sensible Daten: auth/, security/-Verzeichnisse, Token-Handling, Sitzungsverwaltung, Verschlüsselungslogik.
6. Benutzeroberfläche und Design: Frontend-Module, HTML/CSS, Bot-Tastaturlayouts, Assets, Design-Tokens.
7. Aktueller Projektpass: Lesen von AGENTS.md und .agents/project_knowledge/-Ausschnitten (falls bereits initialisiert).
8. Sekundäre / Polyglotte Stacks: Unterverzeichnisse, die kompilierte oder alternative Sprachquelldateien enthalten (z. B. .cpp, .c, .h, .rs, .go, .swift in client/, native/, core/, desktop/).

---

Phase 2: Skalenadaptive Größenbestimmung & Offene Kompetenzmatrix

Bevor Rollen vorgeschlagen werden, muss der Agent den Repository-Umfang bewerten und ein minimal ausreichendes Team synthetisieren.

1. Repository-Größenbestimmung & Rollensynthese

Der Agent schätzt das Codebase-Volumen (LOC, Verzeichnistiefe, technologische Vielfalt):

• Mikro / Kleines Repository (<10k Zeilen, Solo-Entwickler, 1–2 primäre Stacks): Synthetisiere 2–3 kombinierte Rollen, indem Kompetenzblöcke aus der Matrix in vereinheitlichte Profile gebündelt werden.

  • Kanonisches kompaktes Trio:
    1. agent-dev-lead: Kombiniert Intake-Analyse, Aufgabenzerlegung und allgemeine Code-Implementierung (agent-intake-dispatcher + agent-general-worker).
    2. agent-quality-guardian: Kombiniert Pass-/Wissensintegrität, Unit-Test-Suiten und Dead-Code-Audit (agent-meta-guardian + agent-qa-engineer + agent-deep-auditor).
    3. agent-github-steward: Git-Hygiene, Conventional Commits, Code-to-README-Wahrheitsparität und CI/CD.

• Mittleres Repository (10k–50k Zeilen, kleines Team, mehrere Dienste): Stelle 3–5 dedizierte Rollen bereit, die auf Schlüsselkomponenten zugeschnitten sind.

• Großes / Unternehmens-Repository (>50k Zeilen, Monorepos, Microservices): Stelle 6+ granulare Rollen mit strenger Trennung der Zuständigkeiten bereit.

• Polyglotter Stack-Isolationsregel (Keine toxischen Bündel): Verbiete strikt die Bündelung sekundärer kompilierter oder spezialisierter Stacks (C/C++, Rust, Go, native GUI) in agent-general-worker ohne dedizierte Fertigkeiten. Wenn ein polyglotter Stack erkannt wird, synthetisiere entweder eine dedizierte Rolle (z. B. agent-native-desktop mit nativen Compilern und Toolchains) oder weise die nativen Verzeichnisse explizit der Roten Zone mit einem obligatorischen Übergabe-Trigger zu.

• Obligatorische Dispatcher-Regel (Kein Multi-Rollen-Chaos): Wenn 3 oder mehr spezialisierte Rollen bereitgestellt werden, ist die Bereitstellung eines Intake-Dispatchers (agent-intake-dispatcher oder eines integrierten Dispatchers in agent-dev-lead) strikt obligatorisch. Verbiete, den Benutzer mit einem ungerouteten Bündel mehrerer isolierter Rollen ohne einen einzelnen Einstiegspunkt zurückzulassen.

2. Offener Kompetenzkatalog (Rollenmatrix)

[!IMPORTANT] Die folgende Tabelle ist ein Offener Kompetenzkatalog, kein unveränderliches geschlossenes Enum. Agenten haben die volle Autonomie, kombinierte Rollen zu synthetisieren oder benutzerdefinierte, domänenspezifische Rollen (z. B. agent-solana-smart-contracts, agent-3d-designer, agent-data-pipeline) zu erfinden, die der tatsächlichen Architektur des Repositorys entsprechen.

Kategorie	Kompetenzblock / Rolle	Repository-Marker	Spezialisierte Fähigkeiten	Verantwortungsgrenzen
Basisrolle	agent-general-worker(Standard-Worker / Generalist)	Jedes Projekt (grundlegende Standardrolle)	clean-codecode-reviewersystematic-debugging + Stack-Fähigkeiten	Grün: Feature-Implementierung, Skripte, Tests, Bugfixes.Gelb: Ändern von API-Verträgen und Abhängigkeiten.Rot: Destruktive Aktionen und spezialisierte Domänenmodule ohne Übergabe.
Orchestrierung	agent-intake-dispatcher(Intake-Dispatcher)	Jedes Projekt mit 2+ Rollen	prompt-engineeringbrainstorming	Grün: Anfragezerlegung, Prompt-Vorbereitung, Fast-Track-Ausführung.Rot: Direkte Änderung von Projektquellcode.
Orchestrierung	agent-meta-guardian(Meta-Projekt-Wächter)	Vorhandensein von meta-project-Struktur	clean-codecode-reviewer	Grün: Pass-Audit, Rollentelemetrie, Wissensdatenbankwartung.Gelb: Archivierung inaktiver Rollen.Rot: Löschen der Wissensdatenbank ohne Benutzerbestätigung.
Orchestrierung	agent-consensus-judge(Schiedsrichter & Konsensrichter)	Projekte mit umstrittenen Entscheidungen	architecture-decision-recordsapi-design-principles	Grün: Vergleich von Argumenten, empirische Testverifikation.Gelb: Verfassen von ADRs.Rot: Entscheidungen ohne empirische Beweise treffen.
Orchestrierung	agent-deep-auditor(Tiefenprüfer des gesamten Repositorys)	Reife Codebasis (>500 Zeilen)	systematic-debuggingcode-reviewer	Grün: Erstellung von Auditberichten, Erkennung von totem Code, Prüfung der Link-/Ankerintegrität.Gelb: Protokollieren von Erkenntnissen in Beobachtungen.Rot: Destruktive Refactorings, autonomes Löschen von Dateien.
Produkt & Business	agent-product-roaster(Produktanalyst & Roaster)	Produktdienste, Startups	search_webbrainstorming	Grün: Wettbewerbsanalyse, Stresstest von Hypothesen.Rot: Ändern der Geschäftslogik ohne Spezifikationen.
Produkt & Business	agent-creative-director(Kreativdirektor)	UI-Komponenten, Web, Themes, Icons	image-generatorcss-tokens	Grün: Generieren von Farbpaletten, Icons, Bannern.Gelb: Bearbeiten globaler Styles.Rot: Ersetzen der Markenidentität ohne Bestätigung.
Produkt & Business	agent-ui-ux-engineer(UI/UX-Ingenieur)	Frontend, Bots, Schnittstellen	semantic-htmlcss-coderui-ux-invariants	Grün: Komponentenlayout, FSM-Zustände.Gelb: Bildschirmnavigationsänderungen.Rot: Entfernen von Bestätigungen für destruktive Aktionen.
Produkt & Business	agent-legal-compliance(Rechts- & Compliance-Prüfer)	LICENSE, öffentliche Repositorys	SPDX/SBOM-Audit	Grün: Abhängigkeitslizenz-Audit.Gelb: Aktualisieren von NOTICE und Header-Copyrights.Rot: Ändern der Repository-Lizenz.
Engineering	agent-github-steward(GitHub-Guru & Release-Kapitän)	.github/, git-remotes	github-managementgithub-actions-creatorclean-codecode-reviewer	Grün: Git-Hygiene, Conventional Commits, Branch-Management, Issue-Triage, Release-Entwürfe.Gelb: Code-to-README-Paritätsprüfung (sicherstellen, dass README-Anweisungen/CLI mit tatsächlichem Code übereinstimmen), CI/CD-Abstimmung.Rot: Force-Push, Mergen in main ohne Review, Ändern von Secrets.
Engineering	agent-devops-infra(Infrastrukturarchitekt)	Dockerfile, docker-compose*	docker-expertkubernetes-architectbash-linux	Grün: Dev-Container, Konfigurations-Linting.Gelb: Optimierung von Multi-Stage-Builds.Rot: Produktions-Secrets, .env*, Produktions-k8s.
Engineering	agent-qa-engineer(Zuverlässigkeits- & QA-Ingenieur)	tests/, Test-Frameworks	test-driven-developmentverification-before-completion	Grün: Schreiben von Unit-/Integrationstests, Überprüfen von Testläufen.Gelb: Konfigurieren von Test-Runnern und Vertragsassertionen.Rot: Deaktivieren von Tests in CI.
Engineering	agent-tech-writer(Technischer Redakteur)	docs/, OpenAPI, Swagger	mermaid-diagram-specialistopenapigoogle-style-guide	Grün: Dokumentieren von Funktionen, README, Diagrammen.Gelb: Bearbeiten von API-Spezifikationen.Rot: Veröffentlichen nicht überprüfter Dokumente.

---

Phase 3: Audit des bestehenden Teams (Rollenbereinigung & Garbage Collection)

Wenn das Verzeichnis .agents/team/ bereits existiert:

1. Scanne alle Ordner: .agents/team/*/profile.md.
2. Überprüfe die Tabelle Rollenaufrufprotokoll (Telemetrie) in jedem Profil.
3. Identifiziere inaktive oder veraltete Rollen:
   • Rolle wurde initialisiert, aber das Protokoll enthält nur den ersten Eintrag und es fanden >30 Tage lang keine echten Aufrufe statt.
   • Der zugrunde liegende Technologie-Stack der Rolle wurde vollständig aus dem Projekt entfernt (z. B. Docker wurde stillgelegt, aber agent-devops-infra blieb bestehen).
4. Erstelle eine Kandidatenliste für die Archivierung in .agents/team/archive/<rollen_id>/.
5. Verbot der autonomen Löschung: Das Archivieren von Rollen erfordert explizite Benutzerfreigabe!

---

Phase 4: Dialog und Benutzerabstimmung

Erstelle einen prägnanten Beratungsvorschlag für den Benutzer:

1. Erkannte Marker: Liste identifizierter Projektkomponenten.
2. Empfohlene zu aktivierende Rollen: Basis-Worker (agent-general-worker) + 2–4 kritischste Bereichsrollen, die den erkannten Markern entsprechen, mit kurzen Begründungen.
3. Archivkandidaten: (falls inaktive Rollen existieren).
4. Freigabeaufforderung: "Bereitstellung der folgenden Rollen genehmigen: [...]?"

---

Phase 5: Materialisieren von Profilen und Registrieren im Pass

Nach Benutzerbestätigung die Produktionsschreibvorgänge durchführen:

1. Erstelle Verzeichnisse für jede genehmigte Rolle: .agents/team/<rollen_id>/.
2. Erstelle .agents/team/<rollen_id>/profile.md mit der Referenzvorlage templates/team/profile.md (oder der eingebetteten Vorlage unten):
   • Fülle Rollen-ID, Umfang, Aufrufauslöser, aktive Fertigkeiten und Berechtigungsgrenzen aus.
   • Initialisiere die Telemetrietabelle mit dem aktuellen Datum.
3. Erstelle eine private Notizendatei: .agents/team/<rollen_id>/notes.md mit der Referenzvorlage templates/team/notes.md (oder der eingebetteten Vorlage unten).
4. Generiere den anfänglichen, gebrauchsfertigen Systemprompt .agents/team/<rollen_id>/system_prompt.md mit templates/team/system_prompt.md (oder der eingebetteten Vorlage unten):
   • Fülle Rollennamen, Zweck, Fertigkeits-Stack und kanonische Berechtigungsgrenzen (Grün / Gelb / Rot) aus.
5. Registriere Rollen in der Wurzeldatei AGENTS.md unter dem Abschnitt:

   ## 6. Projekt-Agententeam (.agents/team/)
   - [{{ROLLEN_TITEL}}](.agents/team/{{ROLLEN_ID}}/profile.md) — {{ROLLEN_UMFANG}} (aufgerufen von: {{ROLLEN_AUSLÖSER}})
   

6. Generiere und zeige dem Benutzer eine kompakte Quick-Launch-Tabelle an, ohne den Chat mit langem Prompt-Text zu überladen:

   | Rolle | Zweck | Systempfad | Auslöse-Schlüsselwörter |
   | :--- | :--- | :--- | :--- |
   | `agent-qa-engineer` | Tests & Verifikation | `.agents/team/agent-qa-engineer/system_prompt.md` | "führe Tests aus", "überprüfe Validierung" |
   

---

Phase 6: Team-Einsatzregeln

Jeder Team-Agent muss grundlegende Koordinationsprinzipien einhalten:

1. Benutzergesteuerte Passivität: Agenten führen niemals Hintergrundaktionen ohne explizite Benutzeranweisungen aus.
2. Benutzergesteuerte Übergaben: Agenten übertragen die Kontrolle nicht direkt aneinander und umgehen dabei den Benutzer. Wenn eine Aufgabe eine andere Domäne erfordert, gibt der Agent ein strukturiertes Übergabepaket an den Benutzer zurück:

   ### Aufgabenübergabepaket: [Agent-A -> Agent-B]
   - Ursprüngliches Ziel: <was angefordert wurde>
   - Abgeschlossene Arbeit: <Liste der bearbeiteten Dateien>
   - Übergabegrenze: <warum der aktuelle Agent aufgehört hat>
   - Empfohlener Prompt für Agent-B: <gebrauchsfertiger Prompt-Text>
   

3. Übergabekettenlimit: Maximal 2 aufeinanderfolgende Übergaben (Hops = 2). Beim 3. Schritt muss die Kontrolle an den Menschen zurückgegeben werden.
4. Unantastbarkeit gemeinsamer Dateianmerkungen: Das Bearbeiten von Notizen anderer in tasks.md, observations.md und architecture.md ist verboten. Nur der eigene Status/eigene Aufgaben können aktualisiert werden. Bei Konflikten dem Benutzer eine klare Beschreibung des Zielkonflikts präsentieren.
5. Exklusives Eigentum an notes.md: Nur der Rolleninhaber kann .agents/team/<rolle>/notes.md ändern.
6. Evidenzbasierte Schiedsgerichtsbarkeit: agent-consensus-judge fällt Urteile strikt auf der Grundlage von Testergebnissen, Benchmark-Messungen und offiziellen Spezifikationen.
7. Parallele Subagenten-Delegation (dispatching-parallel-agents): Bei der Bearbeitung repetitiver, paralleler oder mehrverzeichnisübergreifender Batch-Workloads (z. B. Dateimigrationen, Generieren mehrerer Testsuiten, Bulk-Linting/Audits) MÜSSEN primäre Agenten die Fertigkeit dispatching-parallel-agents aufrufen. Der übergeordnete Agent partitioniert die Arbeitslast über nicht überlappende Verzeichnisse oder Aufgaben auf temporäre Subagenten und übergibt Projektinvarianten aus AGENTS.md und Rollengrenzen. Der übergeordnete Agent koordiniert den Abschluss, führt Integritätstests durch und gibt einen konsolidierten Bericht an den Benutzer zurück, ohne den Menschen mit Zwischen-Subagenten-Übergaben zu belasten.
8. Leistungsschalter (Arbeitsstopp bei 2. Iteration): Wenn ein Bugfix eine 2. aufeinanderfolgende Bearbeitung im selben Modul erfordert oder eine sekundäre Regression in benachbartem Code verursacht, höre auf, Code zu schreiben. Trete einen Schritt zurück, verfolge den gesamten Datenlebenszyklus vom Ursprung bis zum Verbraucher, identifiziere die architektonische Grundursache und präsentiere eine systemische Analyse, bevor ein neues Diff vorgeschlagen wird.
9. Zielzustandsprüfung: Vor dem Ändern nichttrivialer Module in gelben oder roten Zonen bestimme den erwarteten Zielzustand (z. B. Metriken, Verhalten, Verträge) und dokumentiere ihn in klaren, überprüfbaren Aussagen. Führe dann eine Vorher-/Nachher-Bewertung durch, um die Übereinstimmung zu bestätigen.