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.

examples/walkthrough/README.md

@@ -0,0 +1,30 @@
+# Worked Example — „DemoLinks" (ein URL-Shortener)
+
+Eine **befüllte Momentaufnahme** des Betriebsmodells, damit man sieht wie der
+ausgefüllte Zustand aussieht — nicht nur die Platzhalter. Erfundene, generische
+Domäne; nichts davon muss man bauen.
+
+## Was hier passiert ist (Story)
+1. **Bootstrap:** Leader hat aus dem Brief „kleiner URL-Shortener" das Board
+   ([`ROADMAP.md`](ROADMAP.md)) mit vier Items + Abhängigkeits-DAG erzeugt.
+2. **Feature-Loop, Zyklus 1:** Ready-Set war `{F-01}`. Worker (Sonnet) hat die
+   Storage-Schicht gebaut → Review-Gate (Opus) APPROVE → gemerged.
+   Belegt im Session-Log ([`sessions/2026-06-03-S1.md`](sessions/2026-06-03-S1.md))
+   und als Entscheidung im ADR ([`docs/adr/0002-storage-keyvalue.md`](docs/adr/0002-storage-keyvalue.md)).
+3. **Jetzt:** Ready-Set ist `{F-02, F-03}`. Für F-02 (🔌 Port) liegt ein fertiger
+   Session-Prompt bereit ([`session-prompts/F-02.md`](session-prompts/F-02.md)).
+   F-03 (🔬 Research) muss zuerst durch das Spike-Gate. Live-Stand:
+   [`STATE.md`](STATE.md).
+4. **Audit-Loop, parallel:** Ein kalter Auditor hat an F-01 ein „untested claim"
+   gefunden ([`audits/2026-06-04-storage.md`](audits/2026-06-04-storage.md)) und
+   eine Korrektur-Task mit Model-Zuweisung eingestellt.
+
+## Worauf man achten sollte
+- **Board als DAG:** F-04 ist `⏸` weil sein Prereq F-02 noch nicht `✅` ist — der
+  Leader dispatcht es gar nicht erst. F-03 zeigt die `🔬`-Spur (Spike vor Code).
+- **Port vs. Research:** F-02 hat eine Referenz-Impl (golden oracle) → Worker direkt.
+  F-03 hat keine → Theorist → Spike → GO/NO-GO.
+- **Ownership-Tabelle** in `STATE.md`: jedes Paket hat disjunkte Pfade (mit Slash) —
+  genau das prüft `scripts/gate-ownership.sh`.
+- **Spuren-Vollständigkeit:** ROADMAP (Plan) ↔ STATE (Live) ↔ Session-Log (was lief)
+  ↔ ADR (warum) ↔ Audit (was driftet). Ein kalter Agent rekonstruiert daraus alles.

examples/walkthrough/ROADMAP.md

@@ -0,0 +1,27 @@
+# ROADMAP — Board & Ready-Set  (Beispiel: DemoLinks)
+
+> Befülltes Beispiel-Board. Format-Referenz für das echte `ROADMAP.md` im Root.
+
+## Legende
+- **Typ:** 🔌 port · 🔬 research · 🧱 infra
+- **Status:** ✅ done · 🔲 ready · ⏸ blocked-by-prereq · ⛔ blocked-extern
+
+## Ready-Set-Regel
+`Ready-Set = { Items mit 🔲, deren Prereqs ALLE ✅ }` → aktuell: **{ F-02, F-03 }**.
+
+## Board
+| ID | Item | Typ | Status | Prereqs | Rolle · Modell | Aufwand |
+|----|------|-----|--------|---------|----------------|---------|
+| F-01 | Storage-Schicht (Key-Value Store + TTL) | 🧱 | ✅ | — | Worker · Sonnet | ~0.5 d |
+| F-02 | `POST /shorten` Endpoint | 🔌 | 🔲 | F-01 | Porter · Sonnet | ~0.5 d |
+| F-03 | Klick-Dedup-Analytik (neuartige Heuristik) | 🔬 | 🔲 | F-01 | Theorist · Opus → Spike | ~3 d |
+| F-04 | Rate-Limiter pro Client | 🧱 | ⏸ | F-02 | Worker · Sonnet | ~0.5 d |
+
+> F-03 ist `🔬`: vor Produktionscode erst **Spike** (`docs/loops/spike-gate.md`) —
+> numerischer Nachweis, dass die Dedup-Heuristik keine echten Klicks verwirft.
+> F-04 bleibt `⏸`, bis F-02 `✅` ist; der Leader dispatcht es nicht früher.
+
+## Done
+| ID | Item | Session | Commit |
+|----|------|---------|--------|
+| F-01 | Storage-Schicht | S1 (2026-06-03) | `a1b2c3d` |

examples/walkthrough/STATE.md

@@ -0,0 +1,29 @@
+# STATE — aktueller Stand  (Beispiel: DemoLinks)
+
+> Live-Ebene. Was *jetzt* läuft. Der Plan steht im Board (`ROADMAP.md`).
+
+**Letzte Session:** S1 / 2026-06-03 · **Aktive Rolle:** worker
+
+## Now (in dieser Session im Fokus)
+- F-02 `POST /shorten` vorbereiten (Session-Prompt liegt bereit).
+
+## In Progress (begonnen, nicht fertig)
+- _(keine — F-01 ist gemerged)_
+
+## Blocked
+- F-04 Rate-Limiter — wartet auf F-02 (`⏸` im Board).
+
+## Next (priorisiert)
+- F-02 dispatchen (Porter · Sonnet).
+- F-03 Spike anstoßen (Theorist · Opus) — Research, nicht direkt bauen.
+
+## Offene Audit-Findings
+- A-01 (`audits/2026-06-04-storage.md`, 🟡) — F-01 behauptet TTL-Eviction ohne
+  Test. Korrektur-Task: Haiku, Session S2.
+
+## Datei-Ownership (aktiv)
+| Paket | Dateien/Pfade | Owner |
+|---|---|---|
+| storage | `src/storage/` | worker-a |
+| api | `src/api/` | worker-b |
+| analytics | `src/analytics/` | theorist |

examples/walkthrough/audits/2026-06-04-storage.md

@@ -0,0 +1,19 @@
+# Audit storage — 2026-06-04
+
+- **Reviewer-Session:** kalt (kein Vorkontext), Modell Opus
+- **Orientierung allein aus AGENTS/STATE/CONVENTIONS gelungen?** Ja
+
+## Befunde
+| # | Typ | Beschreibung | Severity | Model | Korrektur-Task |
+|---|-----|--------------|----------|-------|----------------|
+| A-01 | untested | `store.py` dokumentiert TTL-Eviction, aber kein Test deckt das Ablaufen ab. Behauptung ohne Beleg. | 🟡 | Haiku | S2: Eviction-Test ergänzen, dann R-0001 bleibt `done` mit Beleg. |
+| A-02 | hygiene | `manifests/requirements.md` referenziert `tests/test_store.py` — existiert ✅. Keine tote Referenz. | 🔵 | — | keine (nur Notiz). |
+
+## Verifikation
+- Manifest geprüft: R-0001 Datei + Test existieren. ✅
+- Tests ausgeführt: `pytest tests/test_store.py` → 4 passed (Eviction-Pfad aber
+  nicht unter den 4).
+
+## Empfehlung
+- Audit-Loop nicht eskalieren (nur 1× 🟡). A-01 als Korrektur-Task in `STATE.md`
+  und ins Board (Wave „quick wins", Haiku). Feature-Loop bleibt freigegeben.

examples/walkthrough/docs/adr/0002-storage-keyvalue.md

@@ -0,0 +1,12 @@
+# 0002 — Storage zunächst In-Memory Key-Value, nicht SQLite
+
+- **Status:** accepted
+- **Kontext:** F-01 braucht einen Speicher für (Code → URL). Optionen: In-Memory
+  Dict mit TTL, oder SQLite. Der Shortener soll erst die API-Form (F-02) und die
+  Analytik (F-03) validieren; Persistenz ist noch nicht gefordert.
+- **Entscheidung:** In-Memory Key-Value Store mit optionaler TTL. SQLite wird
+  erst eingeführt, wenn ein Item Persistenz über Neustarts verlangt.
+- **Konsequenz:** Schnelle Iteration, keine Schema-Migration jetzt. Preis: Daten
+  überleben keinen Neustart — explizit als Nicht-Ziel der ersten Iteration
+  vermerkt. Re-Litigation vermieden, weil das *Warum* hier festgehalten ist.
+- **Superseded by:** _(noch keins)_

examples/walkthrough/session-prompts/F-02.md

@@ -0,0 +1,40 @@
+# Session-Prompt — F-02 `POST /shorten`  (befülltes Beispiel)
+
+```
+Modell: Sonnet
+
+Du arbeitest in /pfad/zu/DemoLinks auf einem neuen Branch `feat/api` (von `main`).
+
+## Aufgabe
+Implementiere den Endpoint `POST /shorten`: nimmt `{ "url": "<lang>" }`, erzeugt
+einen kurzen Code, speichert (Code → URL) über die Storage-Schicht (F-01) und gibt
+`{ "code": "<kurz>" }` zurück. AUSSERHALB des Scopes: Rate-Limiting (das ist F-04),
+Analytik (F-03), Auth.
+
+## Details
+Referenz-Implementierung (Port): `reference/flask_shortener.py` Zeilen 20–58
+(golden oracle — gleiche Code-Erzeugung, gleiche Kollisionsbehandlung).
+Storage-API: `src/storage/store.py` (`put(key, value)` / `get(key)`).
+
+## Akzeptanzkriterien
+- [ ] Gleiche Eingabe → gleicher Code wie die Referenz (golden-value-Test).
+- [ ] Kollision wird erkannt und neu gewürfelt (Test mit erzwungener Kollision).
+- [ ] Ungültige URL → 400 mit klarer Meldung.
+- [ ] Tests grün: `pytest tests/test_api.py`
+
+## Nicht anfassen
+`src/storage/` (Owner: worker-a) und `src/analytics/` (Owner: theorist).
+Nur `src/api/` + `tests/test_api.py`.
+
+## Commit & Push
+- `feat(api): add POST /shorten endpoint`
+- Trailer: `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`
+- Push nach `origin`, PR öffnen (Base `main`).
+
+## Abschluss
+1. `manifests/requirements.md` R-0002 → `done`.
+2. `STATE.md`: F-02 nach „In Progress", dann Handoff für Review.
+3. Session-Log aus `sessions/TEMPLATE.md`.
+4. `bash scripts/gate-session-hygiene.sh` und `bash scripts/gate-ownership.sh`.
+5. PR-URL + Testzahl reporten. Danach: Review-Gate (Opus).
+```

examples/walkthrough/sessions/2026-06-03-S1.md

@@ -0,0 +1,34 @@
+# Session S1 — 2026-06-03
+
+- **Rolle:** worker
+- **Modell:** Sonnet
+- **Ziel:** F-01 Storage-Schicht (Key-Value Store mit TTL) bauen.
+
+## Geändert (Dateien)
+- `src/storage/store.py` — In-Memory KV-Store, `put/get/expire`.
+- `src/storage/__init__.py`
+- `tests/test_store.py` — put/get-Roundtrip, Overwrite, Miss.
+- `manifests/requirements.md` — R-0001 → `done`.
+
+## Entscheidungen
+- In-Memory-Dict statt SQLite für die erste Iteration → ADR 0002 (accepted).
+
+## Tests
+- `pytest tests/test_store.py` → 4 passed.
+
+## Token-Verbrauch
+- input: 41k · output: 6k · total: 47k · tokens/Task: 47k
+- Auffälligkeiten: keine (kein Re-Reading, kein Schleifen).
+
+## Gates
+- Hygiene: PASS · Kontext: PASS · Token: PASS
+- Review-Gate: APPROVE (Opus-Session S1-review) — „TTL-Pfad korrekt, aber
+  Eviction ist ungetestet" → als Audit-Finding A-01 notiert, nicht blockierend.
+
+## Handoff / Next
+- F-02 ist jetzt ready (Prereq F-01 ✅). Prompt unter `session-prompts/F-02.md`.
+- F-03 ready, aber Research → erst Spike.
+- Review-Gate nötig? erledigt (APPROVE).
+
+## Clean-Start-Check
+- [x] Orientierung allein aus AGENTS/STATE/CONVENTIONS möglich.