agent-swarm-repo

Ein generelles Git-Repo-Template für KI-Agenten-Arbeit. Das Repo ist die dauerhafte gemeinsame Erinnerung — Sessions sind flüchtig, der Stand lebt in den Dateien. Agenten koordinieren über Dateien, nicht über den Chat.

Aktoren & Modelle

Rolle	Modell	Aufgabe
Leader	Sonnet	Orchestrierung, Klassifikation, Integration
Worker / Porter	Sonnet	Implementierung mit klarer Spec, faithful Ports
Theorist	Opus	Formeln ableiten, Validation entwerfen
Prototyper (Spike)	Opus→Sonnet	Wegwerf Proof-of-Correctness vor Produktion
Reviewer (Gate)	Opus, immer	unabhängiger Review-Pass nach jedem Implement
Scholar / Doc	Haiku	Docs, Citations, CLI-Glue
Human	—	Richtung, Lizenz, Precision-Substrat, Freigabe

Vollständige Matrix + Entscheidungsregel: docs/roles/model-routing.md.

Zwei Loops (komposit)

• Feature-Loop (vorwärts): Roadmap → Port/Research-Klassifikation → [Research: Theorist → Spike → GO/NO-GO] → Worker parallel → Review-Gate (Opus) → Integration → Tests + Doku + Manifest → Quality-Gate.
• Audit-Loop (rückwärts): kalter Auditor (Opus) → Findings mit Model-Zuweisung → Implement-Sessions → Review-Gate (Opus, kalt) → Korrektur-Tasks → Observability-Gate.

Die Loops komplementieren sich: Feature-Dev produziert, Audit härtet ab. Jedes Merge triggert einen Audit-Backlog-Eintrag (expliziter Handoff).

Drei Schlüsselprinzipien

1. Review-Gate nach jeder Implement-Session — immer Opus, immer kalt (eigene Session). Implement-Modell ≠ Review-Modell ist eine Korrektheitseigenschaft.
2. Spike vor Research-Code — throwaway Proof-of-Correctness auf einem Wegwerf-Branch. NO-GO ist ein valides Ergebnis, kein Versagen. Schützt vor wochen-langen falschen Implementierungen.
3. Session-Prompts kaltstartfähig — jede Session hat einen vollständigen Prompt unter session-prompts/ (Modell, Branch, Scope, Befehle, Akzeptanzkriterien).

Clean-Start-Invariante

Am Ende jeder Session muss gelten: ein neuer Agent kann sich allein über AGENTS.md → STATE.md → CONVENTIONS.md orientieren. Das erzwingt das Session-Hygiene-Gate.

Loslegen (neues Projekt)

1. bash scripts/init.sh "Projektname" — macht den Klon zu deinem Projekt (Template-Overview wandert nach docs/about-template.md).
2. session-prompts/BOOTSTRAP.md in eine frische Leader-Session geben, Projekt-Brief anhängen → der Leader füllt Board (ROADMAP.md), STATE.md, CONVENTIONS.md und erzeugt die ersten Session-Prompts.
3. Die Gates sind dormant, bis die erste Session STATE.md befüllt — danach greifen sie automatisch.

Erst verstehen? examples/walkthrough/ zeigt ein komplett befülltes Beispiel (Board, Session-Log, Audit-Finding, ADR) an einer generischen Domäne.

Einstieg (jede Session)

Jeder Agent liest zuerst AGENTS.md. Methodik im Detail: docs/methodology.md.