# 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`.