feat: initial agent-swarm-repo template

Generelles Git-Repo-Template fuer KI-Agenten-Arbeit (multi-agent swarm pattern).

Enthaelt:
- Rollen-System (Leader, Worker, Reviewer) mit Model-Routing-Matrix (Tier-basiert)
- Zwei komplementaere Loops: Feature-Loop (vorwaerts) + Audit-Loop (rueckwaerts)
- Spike-Gate fuer Research-Items (GO/NO-GO vor Produktionscode)
- Obligatorische Opus-Review-Gate nach jeder Implement-Session
- Drei ausfuehrbare Gates: session-hygiene, ownership (Cross-Edit-Schutz), doc-drift
  -- alle dormant bis zur ersten Initialisierung, dann automatisch aktiv
- Bootstrap: scripts/init.sh + session-prompts/BOOTSTRAP.md
- Worked Example (URL-Shortener-Domaene): Board, Session-Log, Audit-Finding, ADR
- Token-Hygiene (3-Tier: Session-Schnitt / Command-Disziplin / Cache-Disziplin)
- GitHub Actions CI (gates.yml) laeuft auf jedem Push/PR

Muster destilliert aus produktiv-bewaehrten Patterns des ConformalLabpp-Projekts.

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,9 @@
+# 0001 — Entscheidungen als ADR festhalten
+
+- **Status:** accepted
+- **Kontext:** Agenten-Sessions sind flüchtig; ohne festgehaltenes *Warum*
+  entstehen Drift und Wiederholungsfehler.
+- **Entscheidung:** Tragende Entscheidungen werden als ADR unter `docs/adr/`
+  dokumentiert und in `CONVENTIONS.md` als verbindlich referenziert.
+- **Konsequenz:** Minimaler Schreibaufwand pro Entscheidung; dafür kalt lesbare
+  Begründungen und weniger Re-Litigation.

docs/adr/README.md

@@ -0,0 +1,5 @@
+# Architecture Decision Records (ADR)
+
+Jede tragende Entscheidung wird als kurzes, nummeriertes ADR festgehalten —
+so weiß jede künftige Session das *Warum*. Format: `NNNN-kurz-titel.md`.
+Status: proposed / accepted / superseded. Neues ADR statt altes umschreiben.

docs/gates/observability-gates.md

@@ -0,0 +1,20 @@
+# Observability-Gates
+
+Überwachen das **System**, nicht ein einzelnes Feature. Speisen den Audit-Loop.
+
+## 1. System-Effizienz (Metriken über Zeit)
+- Features pro Session · **Rework-Rate** (Commits, die frühere Arbeit korrigieren)
+- Test-Pass-Rate · **Tokens pro Feature** · Zykluszeit · Gate-Fehlerquote
+- Quelle: Session-Logs + Git-Log, aggregiert von `scripts/metrics.sh` nach
+  `metrics/`.
+
+## 2. Doku-Drift (automatisch erkennbar)
+- Jeder Manifest-Eintrag: referenzierte Datei existiert **und** Test grün?
+- `STATE.md` "Now" nicht älter als N Sessions (Stale-Signal).
+- Code ohne Doc-Änderung / Doc ohne Code-Änderung -> Drift-Verdacht (Heuristik
+  aus `git diff --name-only`).
+- Tote Links / referenzierte, aber fehlende ADRs.
+- Quelle: `scripts/gate-doc-drift.sh`. Befund -> sofortiger Audit-Trigger.
+
+## Schwellen (anpassbar)
+Rework-Rate > 20 %, Stale-State > 3 Sessions oder Drift-Treffer > 0 ⇒ Audit-Loop.

docs/gates/quality-gates.md

@@ -0,0 +1,26 @@
+# Quality-Gates
+
+Laufen am Session-Ende und in CI. Jedes Gate: **PASS/FAIL** + Checkliste.
+`FAIL` blockt den Merge bzw. erzeugt einen Korrektur-Task.
+
+## 1. Session-Hygiene
+- [ ] `STATE.md` in dieser Session aktualisiert.
+- [ ] Session-Log unter `sessions/` angelegt (mit Token-Verbrauch).
+- [ ] Working Tree sauber, Commits konventionskonform.
+- [ ] **Clean-Start-Invariante** erfüllt (Orientierung allein aus
+      AGENTS/STATE/CONVENTIONS).
+- Automatisierung: `scripts/gate-session-hygiene.sh`.
+
+## 2. Kontext-Pflege
+- [ ] Doku ist Single Source of Truth, keine Duplikate.
+- [ ] Doc-Größenbudget eingehalten (Drift-Risiko bei überlangen Docs).
+- [ ] Manifest deckt sich mit der Realität (Dateien/Tests existieren).
+- [ ] Keine toten Verweise.
+
+## 3. Token-Verbrauch
+- [ ] Session-Log enthält input/output/total Tokens und Tokens-pro-Task.
+- [ ] Budget nicht überschritten; auffälliges Re-Reading vermerkt.
+- [ ] Trend über Sessions in `metrics/` fortgeschrieben.
+
+→ Vollständige Tier-1/2/3-Anleitung (Session-Schnitt, Command-Disziplin,
+  Cache-Disziplin): **`docs/token-hygiene.md`** (Single Source of Truth).

docs/loops/audit-loop.md

@@ -0,0 +1,54 @@
+# Audit-Loop (rückwärts)
+
+Ziel: Korrektheit & Hygiene erhalten, Drift früh fangen.
+
+```
+Kalter Auditor (Opus, neue Session)
+  -> Orientierung allein aus AGENTS/STATE/CONVENTIONS pruefen
+    -> Manifest verifizieren + Tests ausfuehren
+      -> Drift & Hygiene-Befunde sammeln
+        -> audits/<datum>.md: Finding-Tabelle mit Severity + Model-Zuweisung
+          -> Korrektur-Tasks in ROADMAP/STATE einstellen
+            -> Observability-Gate (Effizienz + Doku-Drift) aktualisieren
+```
+
+## Trigger
+Nach N Feature-Zyklen, oder sofort bei Drift-Signal aus den Observability-Gates.
+
+## Finding-Orchestration
+
+Findings werden in `audits/<datum>.md` **mit Model-Zuweisung** erfasst:
+
+| ID | Typ | Sev | Status | Model | Session |
+|----|-----|-----|--------|-------|---------|
+| F-01 | drift | 🔴 | ⬜ | Sonnet | S1 |
+| F-02 | hygiene | 🟡 | ✅ abc123 | Haiku | S1 |
+
+Severity: 🔴 hoch · 🟡 mittel · 🔵 niedrig
+
+Model-Routing (s. `docs/roles/model-routing.md`):
+- **Haiku** — mechanisch, lokal, kein Risiko (Docs, Umbenennen, Konstanten)
+- **Sonnet** — klare Akzeptanzkriterien (Tests, Error-Handling, kleine API-Änderungen)
+- **Opus** — Numerik, Architektur, irreversible Entscheidungen + **jede Review-Gate-Session**
+
+Entscheidungs-Regel: nicht "wie schwer", sondern "wie viel muss **verstanden** werden,
+um es richtig zu machen."
+
+## Session-Sequenz
+
+Findings werden in Sessions gebündelt (ähnliche Model-Zuweisung, ähnlicher Scope).
+Nach jeder Implement-Session kommt eine **Opus-Review-Session** (kalt, unabhängig):
+
+```
+Implement-Session (Sonnet/Haiku)
+  -> dedizierten Review-Gate-Session (Opus, kalt)
+    APPROVE → Finding ✅ + Commit-Ref eintragen
+    CHANGES-REQUESTED → zurück zu Implement
+```
+
+Kaltstartfähige Prompts für jede Session: `session-prompts/`.
+
+## Ergebnis
+Priorisierte Korrektur-Tasks mit Model-Zuweisung, die der nächste Feature-Loop
+abräumt. Handoff zu Feature-Dev: jedes bereinigte Finding bestätigt, dass das
+Repo wieder der Clean-Start-Invariante genügt.

docs/loops/feature-loop.md

@@ -0,0 +1,62 @@
+# Feature-Loop (vorwärts)
+
+Ziel: neue Fähigkeit, sauber dokumentiert und belegt.
+
+## Kern-Pipeline
+
+```
+Roadmap-Item
+  -> Leader klassifiziert (port / research / infra)
+  -> Leader zerlegt in disjunkte Pakete (+ STATE-Ownership)
+
+  ┌── PORT ────────────────────────────────────────────┐
+  │  Worker (Sonnet): golden-oracle Implementierung    │
+  │  Validation (Sonnet): Parität-Tests                │
+  └────────────────────────────────────────────────────┘
+
+  ┌── RESEARCH ─────────────────────────────────────────────────────────┐
+  │  Theorist (Opus): Formeln aus Papers ableiten, Validation entwerfen │
+  │  Spike (Prototyper): Wegwerf-Implementierung auf scratch/**-Branch  │
+  │  GO/NO-GO-Gate: math korrekt? → GO: weiter; NO-GO: → Roadmap       │
+  │  Research-Implementer (Opus→Sonnet): produktiv umsetzen             │
+  └─────────────────────────────────────────────────────────────────────┘
+
+  -> Validation Engineer: Test-Batterie je Item-Typ bauen
+  -> Review-Gate (Opus, kalt): math korrekt? Parität? Public-API ok?
+       APPROVE → weiter | CHANGES-REQUESTED → zurück zu Implement
+  -> Leader integriert & löst Konflikte
+  -> Manifest + Docs + STATE aktualisiert
+  -> Quality-Gate (Hygiene/Kontext/Token)
+       PASS: Item nach "Done" | FAIL: Korrektur-Task
+```
+
+## Klassifikation Port vs. Research
+
+| Typ | Kriterium | Oracle | Validation-Pflicht |
+|---|---|---|---|
+| **Port** | hat Referenz-Implementierung (Java, Python, Pseudo-Code) | golden values bit-for-bit | FD-Gradient + Parität |
+| **Research** | kein direkter Vorläufer, nur Paper-Formeln | keine extern | Invarianten + analyt. Grenzfälle + Konvergenz |
+| **Infra** | kein fachlicher Inhalt (CLI, CI, Docs) | trivial | Smoke-Test |
+
+Regel: Research-Items **müssen** durch das Spike-Gate, bevor Produktions-Code
+geschrieben wird. Näheres: `docs/loops/spike-gate.md`.
+
+## Model-Routing (grobe Heuristik)
+
+Vollständige Matrix: `docs/roles/model-routing.md`. Kurzform:
+- Mechanische Arbeit (Umbenennen, Docs, CLI-Glue) → **Haiku**
+- Implementierung mit klarer Spec → **Sonnet**
+- Mathe, Architektur, jede Review-Gate-Session → **Opus**
+
+## Session-Prompts
+
+Kaltstartfähige Prompts je Phase/Paket unter `session-prompts/`.
+Template: `session-prompts/TEMPLATE.md`.
+
+## Eintrittskriterien
+Roadmap-Item priorisiert; Klassifikation (Port/Research/Infra) klar;
+betroffene Konventionen geklärt.
+
+## Austrittskriterien (Definition of Done, s. CONVENTIONS.md)
+Tests grün · Manifest `done` · Docs/STATE aktuell · Session-Log ·
+Review-Gate `APPROVE` · Hygiene-Gate `PASS`.

docs/loops/spike-gate.md

@@ -0,0 +1,55 @@
+# Spike-Gate (nur Research-Items)
+
+Bevor Research-Mathe produktivsiert wird: numerischer Proof-of-Correctness
+auf einem **Wegwerf-Branch**. Der Spike schützt davor, Wochen in eine
+mathematisch falsche Implementierung zu investieren.
+
+## Warum
+
+Research-Items haben keinen goldenen Oracle (keine Referenz-Implementierung).
+Eine Implementierung kann kompilieren, konvergieren und trotzdem **geometrisch
+falsch** sein. Invarianten-Checks und Konvergenz-Studien fangen das nur, wenn
+die zu prüfenden Invarianten vorab klar spezifiziert wurden.
+
+## Ablauf
+
+```
+Theorist (Opus):
+  Formeln aus Papers/Dissertation ableiten
+  Validation-Strategie entwerfen (Invarianten, analyt. Grenzfälle, Kreuzcheck)
+  LaTeX-Notiz / Spec-Dokument erstellen
+        ↓
+Prototyper (Opus → Sonnet):
+  Throwaway-Implementierung auf Branch `spike/<thema>`
+  Numerischen Korrektheitsnachweis führen (die vom Theorist entworfene Validation)
+        ↓
+GO/NO-GO-Gate:
+  GO  → Spike-Branch wird verworfen; Research-Implementer baut produktiv
+  NO-GO → Spike-Branch bleibt als Dokumentation des negativen Ergebnisses
+          → Eintrag in ROADMAP: "Spike <thema> FAILED — Grund: …"
+          → Zurück zum Theorist oder Human-Entscheidung
+```
+
+## NO-GO ist kein Versagen
+
+Ein NO-GO ist ein valides, wertvolles Ergebnis. Es dokumentiert, dass ein
+Ansatz numerisch nicht funktioniert, bevor Produktionscode und Tests dafür
+investiert wurden. **Negative Spikes müssen genauso sorgfältig dokumentiert
+werden wie erfolgreiche.**
+
+## Validation-Typen (gewählt vom Theorist)
+
+| Situation | Validation |
+|---|---|
+| Cross-Implementierung verfügbar (andere Bibliothek) | Übereinstimmung nach Normalisierung |
+| Analytische Grenzfälle bekannt (z. B. κ=0 ↔ Euklidisch) | Bit-for-bit-Übereinstimmung am Grenzfall |
+| Erhaltungsgrößen bekannt (Gauss-Bonnet, Holonomie-Closure) | Invarianten-Check unter Perturbation |
+| Analytisch vs. numerisch (FD vs. exakte Hessematrix) | Wert-Identität + Speed-Messung |
+| Kein direkter Check möglich | Konvergenz-unter-Verfeinerung-Studie |
+
+## Aufwand-Faustregel
+
+Ein Spike sollte **höchstens 20 % des Aufwands** einer vollständigen
+Implementierung kosten. Wenn er mehr braucht, ist das Scope entweder falsch
+klassifiziert (→ kleineres Research-Item) oder der Theorist hat die Spec
+nicht ausreichend präzisiert (→ zurück zum Theorist).

docs/methodology.md

@@ -0,0 +1,48 @@
+# Methodik — Betriebsmodell
+
+## Grundprinzip
+Das Repo ist die dauerhafte Erinnerung; Sessions sind flüchtig. Alles
+Entscheidungsrelevante liegt **auf Disk**, nie nur im Chat. So kann jede neue
+Session kalt starten.
+
+## Rollen
+- **Leader** (`docs/roles/leader.md`) — Orchestrierung & Integration.
+- **Worker** (`docs/roles/worker.md`) — disjunkte parallele Umsetzung.
+- **Reviewer** (`docs/roles/reviewer.md`) — kalter Audit in neuer Session; immer Opus.
+- **Model-Routing** (`docs/roles/model-routing.md`) — welches Modell für welche Arbeit.
+
+## Zwei Loops (Feature-Dev und Audit)
+
+- **Feature-Loop / vorwärts** (`docs/loops/feature-loop.md`): erzeugt Fähigkeit.
+  Enthält eine **Port/Research-Klassifikation** und (für Research) ein
+  **Spike-Gate** (`docs/loops/spike-gate.md`) bevor Produktionscode entsteht.
+- **Audit-Loop / rückwärts** (`docs/loops/audit-loop.md`): erhält Korrektheit &
+  Hygiene, speist Korrekturen mit Model-Zuweisung zurück in Roadmap/State.
+
+Die Loops **komplementieren sich**: Feature-Dev produziert Module; Audit härtet
+sie ab. Jedes Merge im Feature-Loop triggert einen Audit-Backlog-Eintrag.
+Die Loops wechseln sich ab: nach N Feature-Zyklen ein Audit-Zyklus (oder sofort
+bei Drift-Signal aus den Observability-Gates).
+
+## Review-Gate (eingebaut in beide Loops)
+
+Nach **jeder** Implement-Session kommt eine separate Opus-Session (kalt,
+unabhängig), die den Diff reviewt. Kein Merge ohne Review-Gate `APPROVE`.
+Details: `docs/roles/reviewer.md`.
+
+## Session-Prompts
+
+Für jede Session existiert ein kaltstartfähiger Prompt unter `session-prompts/`.
+Template: `session-prompts/TEMPLATE.md`. Der Prompt enthält: Modell, Branch,
+Scope, Befehle, Akzeptanzkriterien — alles was die Session ohne Vorkontext braucht.
+
+## Gates
+- **Quality-Gates** (`docs/gates/quality-gates.md`): Session-Hygiene,
+  Kontext-Pflege, Token-Verbrauch.
+- **Observability-Gates** (`docs/gates/observability-gates.md`): System-Effizienz
+  und Doku-Drift.
+- **Token-Hygiene** (`docs/token-hygiene.md`): 3-Tier-System zur Kostensteuerung.
+
+## Clean-Start-Invariante
+Session-Ende ⇒ neuer Agent orientiert sich allein über
+`AGENTS.md → STATE.md → CONVENTIONS.md`. Verletzung = Hygiene-Gate `FAIL`.

docs/roles/leader.md

@@ -0,0 +1,17 @@
+# Rolle: Leader
+
+## Auftrag
+Arbeit zerlegen, zuweisen, integrieren — nicht selbst alle Pakete bauen.
+
+## Ablauf (Feature-Loop)
+1. Oberstes Roadmap-Item ziehen, in **disjunkte Worker-Pakete** zerlegen
+   (klare Datei-Ownership, minimale Kopplung).
+2. Ownership-Tabelle in `STATE.md` eintragen; offene Fragen vorab in
+   `CONVENTIONS.md`/ADR klären, damit Worker nicht divergieren.
+3. Worker parallel dispatchen. Während sie laufen: nichts in ihren Dateien ändern.
+4. **Integrieren:** zusammenführen, Konflikte lösen, Schnittstellen prüfen.
+5. Manifest + Docs + `STATE.md` aktualisieren, Quality-Gate ausführen.
+
+## Regeln
+- Konflikte gehören dir, nicht den Workern.
+- Wenn ein Paket > 1 Worker-Session braucht: weiter zerlegen.

docs/roles/model-routing.md

@@ -0,0 +1,58 @@
+# Model-Routing — Zuweisung nach Aufgabentyp
+
+Vollständige Entscheidungsmatrix. Kurzform in `docs/loops/feature-loop.md`.
+
+> **Tier-Sprache statt feste Modellnamen:** Modellnamen veralten; die Tier-Logik
+> (klein/mittel/hoch) bleibt. Konkrete Modell-IDs (z. B. Haiku 4.5, Sonnet 4.6,
+> Opus 4.8) sind aktuelle Beispiele — beim Provider nachschlagen, wenn neue
+> Versionen verfügbar sind.
+
+## Tiers
+
+| Tier | Eigenschaft | Aktuelle Beispiele (Anthropic Claude) |
+|------|-------------|---------------------------------------|
+| **klein** | schnell, günstig, ausreichend für klar spezifizierte, mechanische Arbeit | Haiku |
+| **mittel** | ausgewogen; guter Coder bei klarer Spec | Sonnet |
+| **hoch** | höchste Reasoning-Kapazität; für Unklarheiten, Mathe, Review | Opus |
+
+## Routing-Matrix
+
+| Aufgabe | Rolle · Tier |
+|---|---|
+| Mechanisch, lokal, kein Risiko: Docs, Umbenennen, Konstanten, CLI-Glue | klein |
+| Faithful Translation von bekannter Referenz (Port, golden oracle) | Porter · mittel |
+| Implementierung mit klarer Spec + Akzeptanzkriterien: Tests, Error-Handling | mittel |
+| Numerik, Architektur, Mathe von Grund auf, irreversible Public-API-Entscheidungen | hoch |
+| Formeln aus Papers ableiten, Validation-Strategie entwerfen | Theorist · hoch |
+| Throwaway Proof-of-Correctness (Spike), bevor Produktionscode entsteht | Prototyper · hoch → mittel |
+| Test-Batterie für abgeschlossene Implementierung | Validation · mittel |
+| **Jede Review-Gate-Session** (unabhängig, kalt) | **Reviewer · hoch** |
+| Docs polieren, Referenz-Listen, Tutorials | Scholar · klein |
+| Branch/PR/CI/Rebase/Merge | Integrator · mittel |
+| Fachliche Richtungsentscheidungen, Lizenz, Precision-Substrat | Human |
+
+## Entscheidungsregel
+
+**Nicht** „wie schwer ist das Finding/Feature", sondern:
+**„Wie viel muss *verstanden* werden, um es richtig zu machen?"**
+
+- Eine 1-Zeilen-Korrektur mit klarer Spec → mittel (auch wenn 🔴 Severity).
+- Eine numerische Umformulierung mit Auswirkung auf Korrektheit → hoch
+  (auch wenn 🔵 Severity).
+
+## Review-Gate-Regel
+
+Die Review-Gate-Session ist **immer höchste Kapazitätsstufe und immer kalt**
+(eigene Session, kein Vorkontext aus der Implement-Session). Implement-Tier ≠
+Review-Tier ist keine Effizienzfrage, sondern eine Korrektheitseigenschaft.
+
+## Routing Port vs. Research
+
+```
+Gibt es eine Referenz-Implementierung / goldene Werte?
+  JA  → Port   → Porter (Sonnet), golden-oracle parity-Tests Pflicht
+  NEIN → Research → Theorist (Opus) ableiten → Spike → GO/NO-GO
+                    → Research-Implementer (Opus→Sonnet) produktivisieren
+```
+
+Details zum Spike-Gate: `docs/loops/spike-gate.md`.

docs/roles/reviewer.md

@@ -0,0 +1,41 @@
+# Rolle: Externer Reviewer (kalt)
+
+## Auftrag
+In einer **frischen Session ohne Vorkontext** verifizieren, ob das Repo stimmt
+und ob ein Neuling sich orientieren kann.
+
+**Modell: immer Opus.** Rationale: ein unabhängiger, kapazitätsstarker Pass
+nach jedem Implement findet systematisch andere Fehler als das implementierende
+Modell. Der Reviewer darf niemals dasselbe Modell in derselben Session gewesen sein.
+
+## Zwei Reviewer-Rollen
+
+### 1. Review-Gate (nach jeder Implement-Session, Feature- wie Audit-Loop)
+Geht den Diff durch — nicht das ganze Repo. Prüft:
+
+- [ ] Build sauber; Test-Suite grün (keine Regressions im Zählstand).
+- [ ] Keine golden-vector / Parität-Tests verändert, sofern nicht explizit begründet.
+- [ ] Numerische Änderungen sind wert-identisch wo behauptet, oder getestet.
+- [ ] Neue Public-Surface (Typen, Enums, API) ist absichtlich und dokumentiert.
+- [ ] Commit-Message enthält Model-Attribution des Implementers.
+- [ ] Finding / Phase als ✅ in der Orchestration-Tabelle mit Commit-Ref eingetragen.
+
+Ergebnis: **APPROVE** oder **CHANGES-REQUESTED** (mit konkreter Liste).
+
+### 2. Audit-Reviewer (periodisch, Audit-Loop)
+Startet komplett kalt — kein Vorkontext aus vorherigen Sessions.
+
+1. **Nur** `AGENTS.md → STATE.md → CONVENTIONS.md` lesen. Orientierung gelungen?
+   (Ja/Nein → erstes Finding.)
+2. `manifests/requirements.md` durchgehen: Dateien vorhanden? Tests lauffähig?
+3. **Drift suchen:** Docs vs. Code, ADRs vs. Realität, `STATE.md`-Aktualität,
+   tote Verweise, ungetestete Behauptungen.
+4. **Hygiene prüfen:** Ownership-Verstöße, Doppel-Dokumentation, Doc-Budget.
+5. Findings nach `audits/<datum>.md` (Template) mit Severity + Model-Zuweisung.
+   Korrektur-Tasks in `ROADMAP.md` / `STATE.md` einstellen.
+   Observability-Gate aktualisieren.
+
+## Prinzip
+Der Reviewer baut keine Features — er deckt Lücken zwischen *behauptet* und
+*belegt* auf. Er nimmt an, dass alle Aussagen im Repo falsch sind, bis er sie
+selbst verifiziert hat.

docs/roles/worker.md

@@ -0,0 +1,14 @@
+# Rolle: Worker
+
+## Auftrag
+Genau **ein** zugewiesenes Paket umsetzen — innerhalb der eigenen Dateigrenzen.
+
+## Ablauf
+1. `AGENTS.md`-Reihenfolge lesen, dann nur die für dein Paket relevanten Dateien.
+2. Gegen den Vertrag in `CONVENTIONS.md` bauen (Naming/Pfade/Schnittstellen).
+3. Tests für dein Paket schreiben; Manifest-Einträge auf `in_progress`/`done` setzen.
+4. **Niemals** Dateien außerhalb deines Pakets anfassen — sonst Notiz an den Leader.
+5. Session-Log schreiben (inkl. Token-Verbrauch), Hygiene-Gate ausführen.
+
+## Anti-Pattern
+- Scope-Creep, "mal eben" fremde Dateien anpassen, Doku "später".

docs/token-hygiene.md

@@ -0,0 +1,50 @@
+# Token-Hygiene — 3 Ebenen
+
+Jeder Turn schickt die ganze Konversations-History erneut. Kontextakkumulation
+ist der größte vermeidbare Kostenfaktor in Multi-Agenten-Setups.
+
+---
+
+## Tier 1 — Session-Schnitt (höchste Wirkung)
+
+- **Eine Session pro Aufgabe.** Nach einer abgeschlossenen Aufgabe `/clear` starten
+  statt zum nächsten Thema im selben Thread zu wechseln. Alter Kontext ist totes
+  Gewicht in jedem weiteren Turn.
+- **Proaktiv kompaktieren** an sauberen Übergabepunkten. `/compact <was wichtig ist>`
+  bevor die nächste Aufgabe startet — nicht warten bis auto-compaction einsetzt
+  (Zeitpunkt ist nicht kontrollierbar).
+- **Lese-intensive Sweeps delegieren.** Ein Explore/Plan-Subagent liest in seinem
+  eigenen Kontext und gibt eine kurze Zusammenfassung zurück — das Bulk landet nie
+  im Hauptkontext. Nur bei bekannten Pfaden direkt `Read` nutzen.
+
+## Tier 2 — Command-Disziplin (mittlere Wirkung)
+
+- **Scope + Filter gemeinsam.** Pfad-scopede Suchen (`grep -rn "symbol" src/`, nicht
+  Repo-weit). Test-Output filtern (`--filter "SuiteX"`, nicht alle Ergebnisse dumpen).
+- **Logs nie roh in Kontext.** In Datei umleiten, dann `grep`/`tail`. Bei
+  Hintergrund-Jobs Output-Datei selektiv lesen, nicht pauschal.
+- **Nicht zurück-lesen nach Edit.** `Edit` schlägt fehl bei inkonsistentem State —
+  ein erfolgreicher Edit braucht kein `Read` zur Verifikation.
+- **Referenz per Zeilennummer** (`datei.py:147`) statt Code-Blöcke neu einzufügen.
+
+## Tier 3 — Cache-Disziplin (Prompt-Cache, TTL 5 min)
+
+Der stabile Präfix jeder Anfrage (System-Prompt + CLAUDE.md / AGENTS.md) wird
+gecacht. Cache-Miss = der ganze Kontext wird uncached neu gelesen.
+
+- **Stabilen Präfix stabil halten.** `AGENTS.md`, `CLAUDE.md` und Projekt-Config
+  **nicht mitten in einer Arbeitssession editieren**. Änderungen sammeln und in
+  einem eigenen Durchgang machen.
+- **Keine Ketten kurzer Pausen.** Einzelne lange Pause (> 5 min) = ein Cache-Miss.
+  Viele kurze „warte-mal-kurz"-Turns mit Lücken > 5 min = jedes Mal ein neuer Miss.
+  Bei externem Warten (CI, Deploy): **einmal** lang warten statt mehrfach pollen.
+- **Eine Session pro Thema** (interagiert direkt mit Cache): frischer Thread = kleiner,
+  vollständig gecachter Präfix.
+
+---
+
+## Schnell-Check vor einer langen Session
+
+- [ ] Einzelnes Thema? Wenn nein → splitten.
+- [ ] AGENTS.md-Änderungen anstehend? → **vorher** erledigen, dann stabil lassen.
+- [ ] Lange Wartezeiten erwartet (CI/Build)? → Hintergrund-Job + **einmal** warten.