From efee259d01e7e3f0cc3bdf88905a1398967ed8c2 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Wed, 3 Jun 2026 06:55:39 +0200 Subject: [PATCH] feat: bootstrap jetson-ai-ollama from agent-swarm template Leader-Bootstrap (Planung) aus Template + Jetson-Meta-Prompt: - ROADMAP-Board W1-W6 als Abhaengigkeits-DAG (Ready-Set = {W1}) - STATE mit disjunkter Datei-Ownership W2-W6 - CONVENTIONS Projekt-Vertrag (Profile, Pfade, Ports, Daemon-Env, num_ctx, DVC, Scope) - manifests/requirements.md = kalt verifizierbares Review-Manifest (R-01..R-10) - REVIEW.md Kalt-Review-Einstieg; ADR 0002 (Ollama-nativ, kein Swapper/Gateway) - session-prompts/W1..W6 dispatch-fertig; .gitignore um Jetson-Ignores erweitert - examples/walkthrough entfernt (Projekt hat eigenes gefuelltes Board) Co-Authored-By: Claude Opus 4.8 --- .github/workflows/gates.yml | 16 ++++ .gitignore | 16 ++++ AGENTS.md | 38 +++++++++ CONVENTIONS.md | 64 +++++++++++++++ README.md | 46 +++++++++++ REVIEW.md | 29 +++++++ ROADMAP.md | 41 ++++++++++ STATE.md | 35 ++++++++ audits/README.md | 4 + audits/TEMPLATE.md | 15 ++++ docs/about-template.md | 58 +++++++++++++ .../adr/0001-record-architecture-decisions.md | 9 +++ docs/adr/0002-ollama-native.md | 18 +++++ docs/adr/README.md | 5 ++ docs/gates/observability-gates.md | 20 +++++ docs/gates/quality-gates.md | 26 ++++++ docs/loops/audit-loop.md | 54 +++++++++++++ docs/loops/feature-loop.md | 62 ++++++++++++++ docs/loops/spike-gate.md | 55 +++++++++++++ docs/methodology.md | 48 +++++++++++ docs/roles/leader.md | 17 ++++ docs/roles/model-routing.md | 58 +++++++++++++ docs/roles/reviewer.md | 41 ++++++++++ docs/roles/worker.md | 14 ++++ docs/token-hygiene.md | 50 ++++++++++++ manifests/requirements.md | 20 +++++ metrics/efficiency.csv | 2 + scripts/gate-doc-drift.sh | 58 +++++++++++++ scripts/gate-ownership.sh | 81 +++++++++++++++++++ scripts/gate-session-hygiene.sh | 41 ++++++++++ scripts/init.sh | 60 ++++++++++++++ scripts/metrics.sh | 11 +++ session-prompts/BOOTSTRAP.md | 61 ++++++++++++++ session-prompts/TEMPLATE.md | 77 ++++++++++++++++++ session-prompts/W1.md | 41 ++++++++++ session-prompts/W2.md | 44 ++++++++++ session-prompts/W3.md | 39 +++++++++ session-prompts/W4.md | 39 +++++++++ session-prompts/W5.md | 39 +++++++++ session-prompts/W6.md | 37 +++++++++ sessions/2026-06-03-bootstrap.md | 41 ++++++++++ sessions/README.md | 4 + sessions/TEMPLATE.md | 29 +++++++ 43 files changed, 1563 insertions(+) create mode 100644 .github/workflows/gates.yml create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CONVENTIONS.md create mode 100644 README.md create mode 100644 REVIEW.md create mode 100644 ROADMAP.md create mode 100644 STATE.md create mode 100644 audits/README.md create mode 100644 audits/TEMPLATE.md create mode 100644 docs/about-template.md create mode 100644 docs/adr/0001-record-architecture-decisions.md create mode 100644 docs/adr/0002-ollama-native.md create mode 100644 docs/adr/README.md create mode 100644 docs/gates/observability-gates.md create mode 100644 docs/gates/quality-gates.md create mode 100644 docs/loops/audit-loop.md create mode 100644 docs/loops/feature-loop.md create mode 100644 docs/loops/spike-gate.md create mode 100644 docs/methodology.md create mode 100644 docs/roles/leader.md create mode 100644 docs/roles/model-routing.md create mode 100644 docs/roles/reviewer.md create mode 100644 docs/roles/worker.md create mode 100644 docs/token-hygiene.md create mode 100644 manifests/requirements.md create mode 100644 metrics/efficiency.csv create mode 100755 scripts/gate-doc-drift.sh create mode 100755 scripts/gate-ownership.sh create mode 100755 scripts/gate-session-hygiene.sh create mode 100755 scripts/init.sh create mode 100755 scripts/metrics.sh create mode 100644 session-prompts/BOOTSTRAP.md create mode 100644 session-prompts/TEMPLATE.md create mode 100644 session-prompts/W1.md create mode 100644 session-prompts/W2.md create mode 100644 session-prompts/W3.md create mode 100644 session-prompts/W4.md create mode 100644 session-prompts/W5.md create mode 100644 session-prompts/W6.md create mode 100644 sessions/2026-06-03-bootstrap.md create mode 100644 sessions/README.md create mode 100644 sessions/TEMPLATE.md diff --git a/.github/workflows/gates.yml b/.github/workflows/gates.yml new file mode 100644 index 0000000..c850226 --- /dev/null +++ b/.github/workflows/gates.yml @@ -0,0 +1,16 @@ +name: gates +on: [push, pull_request] +jobs: + quality: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: { fetch-depth: 0 } + - name: Session-Hygiene-Gate + run: bash scripts/gate-session-hygiene.sh + - name: Ownership-Gate + run: bash scripts/gate-ownership.sh + - name: Doku-Drift-Gate + run: bash scripts/gate-doc-drift.sh + - name: Metriken sammeln + run: bash scripts/metrics.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3ba2047 --- /dev/null +++ b/.gitignore @@ -0,0 +1,16 @@ +__pycache__/ +*.py[cod] +.venv/ +.env +*.log +logs/ +.DS_Store +.idea/ +.vscode/ +# metrics/*.csv wird bewusst getrackt — die Observability-Story braucht den Trend. + +# --- Jetson AI / Ollama spezifisch --- +*.gguf +models/ +.dvc/cache/ +.dvc/tmp/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..58ecdbb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# AGENTS.md — Einstiegspunkt für jede Session + +> **Lies dies zuerst. Lies NICHT das ganze Repo.** Orientiere dich in dieser +> Reihenfolge und höre auf, sobald du genug Kontext für deine Aufgabe hast. + +## Lese-Reihenfolge (klarer Start) +1. **Dieses Dokument** — wer macht was, wo steht was. +2. **`STATE.md`** — *wo wir gerade stehen* (Now / In Progress / Blocked / Next / + offene Audit-Findings). Die einzige Quelle für den aktuellen Stand. +3. **`CONVENTIONS.md`** — verbindliche Regeln (Naming, Pfade, Commits, Ownership, + Model-Attribution, Review-Gate). +4. **Deine Rollen-Datei** — `docs/roles/{leader,worker,reviewer}.md`. + Welches Modell für welche Arbeit: `docs/roles/model-routing.md`. +5. **Die relevante Loop-Datei** — `docs/loops/{feature,audit}-loop.md`. + Bei Research-Items: `docs/loops/spike-gate.md`. +6. **Dein Session-Prompt** — `session-prompts/` (fertig ausgefüllter Prompt für + diese Session — kein Lesen des ganzen Repos nötig). +7. Nur bei Bedarf: `manifests/requirements.md`, betroffene ADRs, Code. + +## Wo finde ich was? +| Frage | Datei | +|---|---| +| Aktueller Stand / nächster Schritt | `STATE.md` | +| Regeln & gemeinsamer Vertrag | `CONVENTIONS.md` | +| Plan / Board / Ready-Set (DAG) | `ROADMAP.md` | +| Befülltes Beispiel zum Lernen | `examples/walkthrough/` | +| Warum wurde X so entschieden | `docs/adr/` | +| Anforderung → Datei → Test → Status | `manifests/requirements.md` | +| Was hat die letzte Session getan | `sessions/` (neuester Eintrag) | +| Offene Prüf-Befunde + Model-Zuweisung | `audits/` | +| Welches Modell für welche Arbeit | `docs/roles/model-routing.md` | +| Kaltstartfähige Session-Prompts | `session-prompts/` | +| Token-Kosten kontrollieren | `docs/token-hygiene.md` | + +## Pflicht am Session-Ende +- `STATE.md` aktualisieren · Session-Log aus `sessions/TEMPLATE.md` anlegen + (inkl. **Token-Verbrauch** + Model-Attribution) · betroffene Manifeste/Docs anpassen · + Quality-Gate ausführen (`scripts/gate-session-hygiene.sh`). diff --git a/CONVENTIONS.md b/CONVENTIONS.md new file mode 100644 index 0000000..b1661e6 --- /dev/null +++ b/CONVENTIONS.md @@ -0,0 +1,64 @@ +# CONVENTIONS.md — gemeinsamer Vertrag + +Verbindlich für **alle** Aktoren. Änderungen nur per ADR. + +## Ownership +- **Kein Paket editiert Dateien eines anderen.** Integration & Konfliktlösung + ausschließlich durch den Leader. +- Jede Datei hat genau ein zuständiges Worker-Paket (siehe `STATE.md`). + +## Git & Commits +- Branch je Paket: `feat/`, `audit/`, `fix/`. +- **Conventional Commits:** `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, + `chore:`. Der Git-Log ist Teil der Dokumentation. +- **Model-Attribution:** jeder Commit eines Agenten enthält einen Trailer: + `Co-Authored-By: Claude ` + Tier = Capability-Bezeichnung des eingesetzten Modells, z. B. „Sonnet 4.6" + für mittlere Kapazität oder „Opus 4.8" für maximale — nicht der interne + Modell-Name. Gilt für das zum Commit-Zeitpunkt eingesetzte Modell. + Ermöglicht nachträgliche Rückverfolgung welche Kapazitätsstufe was entschieden hat. + +## Review-Gate +- **Jede Implement-Session wird von einer separaten high-capacity-Session reviewed** + (aktuell: Opus-Tier). Der Review läuft kalt (eigene Session, kein Vorkontext), + prüft den Diff, und gibt APPROVE oder CHANGES-REQUESTED zurück. +- Implement-Kapazitätsstufe ≠ Review-Kapazitätsstufe: ein Modell, das sich selbst + reviewed, findet systematisch weniger als ein unabhängiger Pass auf höchster Stufe. +- Konkrete Tier-Zuordnungen: `docs/roles/model-routing.md`. +- Review-Gate-Checkliste: `docs/roles/reviewer.md`. + +## Dokumentation +- **Single Source of Truth** je Information — keine Duplikate über Docs hinweg. +- Doku ist knapp: ein Dokument, das man nicht mehr liest, driftet. Größenbudget + pro Doc beachten (Faustregel < 200 Zeilen). +- Jede Code-Änderung passt das passende Doc + Manifest **in derselben Session** an. + +## Definition of Done +1. Manifest-Eintrag (`manifests/requirements.md`) mit Test + Status `done`. +2. Tests grün. 3. Docs aktuell. 4. `STATE.md` aktualisiert. +5. Session-Log geschrieben. 6. Quality-Gate `PASS`. + +## Projekt-Vertrag: Jetson AI / Ollama +Verbindlich für alle Worker — Single Source of Truth dieser Werte. Änderungen nur per ADR. + +- **Hardware:** Jetson Orin Nano Super 8 GB (~7,4 GB nutzbar). Single-User → latenz-, + nicht durchsatzgebunden. Kein Batching, keine Inferenz-Skalierung. +- **Profilnamen (Ollama-Modellnamen):** `qwen-light`, `gemma`, `qwen-heavy`. +- **Pfade:** GGUF unter `/opt/jetson-ai/models/.gguf`; Ollama-Store + `/opt/ollama/models` (nur Laufzeit-Cache). +- **Ports / Endpoints:** Ollama `11434` (OpenAI `/v1/chat/completions`, Status + `/api/ps`); Exporter `/metrics` auf Port `8000`. +- **Daemon-Env (in `ollama/systemd/ollama.service.d/override.conf`):** + `OLLAMA_FLASH_ATTENTION=1`, `OLLAMA_KV_CACHE_TYPE=q8_0`, + `OLLAMA_MAX_LOADED_MODELS=1` (genau ein Modell resident, 8-GB-Schutz), + `OLLAMA_KEEP_ALIVE=30s`, `OLLAMA_MODELS=/opt/ollama/models`, + `OLLAMA_HOST=0.0.0.0:11434` (nur LAN, Firewall auf den Proxy beschränken). +- **`num_ctx` je Modelfile explizit** (Ollama kürzt sonst still): light/gemma 16384, + heavy 8192. +- **Env-Variablen Single Source:** `.env.example` — nur Platzhalter, **nie Secrets**. +- **DVC = Modell-Source-of-Truth.** `build-models.sh` baut alle drei Profile + reproduzierbar aus den DVC-getrackten GGUFs. +- **Scope-Grenze (out of repo):** nginx-Reverse-Proxy (TLS + OAuth) und + Prometheus/Grafana laufen **off-box**. Ollama hat **keine eigene Auth** → nie + direkt ins Internet binden. +- **Code:** Type Hints, Docstrings. diff --git a/README.md b/README.md new file mode 100644 index 0000000..64d04b8 --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +# Jetson AI / Ollama (MLOps) + +Lokal laufendes **Single-User-AI-System** auf einem **Jetson Orin Nano Super (8 GB)**: +Ollama-Daemon serviert drei Modell-Profile (OpenAI-kompatibel), ein schlanker +Exporter-Sidecar exponiert `/metrics`. Modellwechsel passiert **nativ über den +Modellnamen** — kein eigener Swapper, kein Gateway (siehe `docs/adr/0002-ollama-native.md`). + +- **Profile:** `qwen-light` (Daily-Driver) · `gemma` (Creative/Chat, multimodal) · + `qwen-heavy` (harte Reasoning-Fälle). `OLLAMA_MAX_LOADED_MODELS=1` hält genau ein + Modell resident → drei Profile sind quasi gratis. +- **Optimierung:** `q8_0`-KV-Cache + Flash Attention, `num_ctx` je Profil explizit. +- **Daten:** DVC ist Modell-Source-of-Truth; Ollamas Blob-Store nur Laufzeit-Cache. + +> **Scope:** Dieses Repo deckt **nur den Jetson** ab. nginx (TLS + OAuth) und +> Prometheus/Grafana laufen off-box. Ollama hat keine eigene Auth → nur ans LAN +> binden, Firewall auf den Proxy. Voller Vertrag: [`CONVENTIONS.md`](CONVENTIONS.md). + +--- + +## Arbeitsmodell (agent-swarm) +Dieses Repo wurde aus dem **agent-swarm-Template** gebootstrapt: ein Leader/Worker- +Agentensystem, dessen Stand komplett auf Disk lebt — kalt lesbar ohne Vorkontext. +Methodik: [`docs/methodology.md`](docs/methodology.md) · Herkunft: +[`docs/about-template.md`](docs/about-template.md). + +| Wo | Datei | +|---|---| +| Stand & nächster Schritt | [`STATE.md`](STATE.md) | +| Plan / Board / Ready-Set (DAG) | [`ROADMAP.md`](ROADMAP.md) | +| Gemeinsamer Vertrag | [`CONVENTIONS.md`](CONVENTIONS.md) | +| Kalt-Review-Einstieg | [`REVIEW.md`](REVIEW.md) | +| Dispatch-fertige Worker-Prompts | [`session-prompts/`](session-prompts/) | + +## Sofort bauen +Die Planung ist fertig (W1–W6 im Board). So baust du es: + +1. **W1 zuerst** — frische Session öffnen, Modell **Sonnet**, Inhalt von + [`session-prompts/W1.md`](session-prompts/W1.md) einfügen → legt das Grundgerüst an. +2. **Review-Gate** (Opus, kalt) → mergen → W1 im Board auf `✅`. +3. **W2–W5 parallel** — je eigene Session (`session-prompts/W2.md` … `W5.md`), + disjunkte Datei-Ownership, laufen unabhängig. +4. **W6 zuletzt** — Docs, integriert die Realität der anderen Pakete. + +Jeder Worker-Prompt ist self-contained (Modell, Branch, Dateien, Akzeptanzkriterien, +Abschluss-Gates). Die Gates (`scripts/gate-*.sh`) sind aktiv und prüfen Ownership, +Hygiene und Doku-Drift bei jedem Schritt. diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 0000000..c4c43c3 --- /dev/null +++ b/REVIEW.md @@ -0,0 +1,29 @@ +# REVIEW — Kalt-Review-Einstieg + +Dieses Repo ist so gebaut, dass ein Reviewer **ohne jeden Vorkontext** in einer +frischen Session verifizieren kann, ob alles stimmt. Du musst nichts glauben — +führe die Prüfbefehle aus. + +## In dieser Reihenfolge +1. **`AGENTS.md` → `STATE.md` → `CONVENTIONS.md`** lesen. Kannst du dich allein + damit orientieren? (Wenn nein → erstes Finding.) +2. **`manifests/requirements.md`** ist das Verifikations-Manifest: je Erfolgs- + kriterium eine Zeile *Anforderung → Datei(en) → Prüfbefehl → Status*. Gehe es + Zeile für Zeile durch und führe den Prüfbefehl jeder `done`-Zeile aus. +3. **Tests kodieren die Kriterien** (Modelfile-Build, Endpoint-Smoke) — ausführen + statt glauben: `pytest tests/ -q`. +4. **Git-Log** (Conventional Commits + Model-Attribution) erzählt die Reihenfolge. + +## Automatische Gates (lokal lauffähig) +```bash +bash scripts/gate-session-hygiene.sh # STATE/Session-Log/Commits sauber? +bash scripts/gate-ownership.sh # kein Cross-Editing über Paket-Grenzen? +bash scripts/gate-doc-drift.sh # done-Zeilen belegen ihre Dateien? +``` + +## Was „fertig" heißt +Alle Zeilen in `manifests/requirements.md` auf `done`, ihre Prüfbefehle grün, +`tests/` grün, die drei Gates `PASS`. Die Erfolgskriterien selbst stehen — Single +Source of Truth — im Manifest und in `CONVENTIONS.md` (Projekt-Vertrag), nicht hier. + +> Reviewer-Rolle und Checkliste im Detail: `docs/roles/reviewer.md`. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..2cfc366 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,41 @@ +# ROADMAP — Board & Ready-Set (Jetson AI / Ollama) + +Eingang des Feature-Loops **und** der Abhängigkeits-DAG. Der Leader berechnet jeden +Zyklus das **Ready-Set** und dispatcht nur daraus. + +> **ROADMAP vs. STATE:** ROADMAP = der ganze geplante Graph. `STATE.md` = was +> *gerade jetzt* läuft. Item wandert: `🔲` → beim Dispatch in STATE „In Progress" → +> bei Merge zurück als `✅` in „Done". + +## Legende +- **Typ:** 🔌 port · 🔬 research · 🧱 infra +- **Status:** ✅ done · 🔲 ready · ⏸ blocked-by-prereq · ⛔ blocked-extern + +## Ready-Set-Regel +``` +Ready-Set = { Items mit 🔲, deren Prereqs ALLE ✅ } → aktuell: { W1 } +``` +1. Ready-Set bilden. 2. Modell aus `docs/roles/model-routing.md`. 3. Prompt aus +`session-prompts/.md`. 4. Worker bauen. 5. Review-Gate (hoch) → Merge → ✅. + +> **Dieses Projekt ist rein 🧱 infra/config** — kein 🔬-Item, daher kein Spike-Gate. +> Die Kopplung der Pakete läuft ausschließlich über `CONVENTIONS.md`. + +## Board +| ID | Item | Typ | Status | Prereqs | Rolle · Tier | Aufwand | +|----|------|-----|--------|---------|--------------|---------| +| W1 | Grundgerüst: Struktur, README-Skelett, LICENSE, `.gitignore`, `.env.example` | 🧱 | 🔲 | — | Worker · mittel | ~0.5 d | +| W2 | Ollama-Profile: Modelfiles light/gemma/heavy, systemd-override, `build-models.sh`, DVC | 🧱 | ⏸ | W1 | Worker · mittel | ~1 d | +| W3 | Exporter-Sidecar: `/metrics`:8000 + systemd-Service | 🧱 | ⏸ | W1 | Worker · mittel | ~0.5 d | +| W4 | Setup & CI/CD: `setup-jetson.sh`, `benchmark.sh`, Workflows | 🧱 | ⏸ | W1 | Worker · mittel | ~1 d | +| W5 | Client & Tests: `client/`, `tests/`, Requirements | 🧱 | ⏸ | W1 | Worker · mittel | ~1 d | +| W6 | Docs: architecture/api/deployment/troubleshooting + README-Finalisierung | 🧱 | ⏸ | W2,W3,W4,W5 | Scholar · klein | ~0.5 d | + +**Wellen:** W1 zuerst (alleine) → dann **W2–W5 parallel** (disjunkte Ownership, +nur über `CONVENTIONS.md` gekoppelt) → W6 zuletzt (integriert die Realität der +anderen). Session-Prompts liegen fertig unter `session-prompts/W1…W6.md`. + +## Done +| ID | Item | Session | Commit | +|----|------|---------|--------| +| — | _(noch nichts gemerged — W1 ist als nächstes dran)_ | — | — | diff --git a/STATE.md b/STATE.md new file mode 100644 index 0000000..fe60a14 --- /dev/null +++ b/STATE.md @@ -0,0 +1,35 @@ +# STATE — aktueller Stand (Jetson AI / Ollama) + +> Live-Ebene. Was *jetzt* läuft. Plan steht im Board (`ROADMAP.md`). + +**Letzte Session:** bootstrap / 2026-06-03 · **Aktive Rolle:** leader + +## Now (in dieser Session im Fokus) +- Bootstrap fertig (Planung). Nächster Dispatch: **W1 Grundgerüst** (`session-prompts/W1.md`). + +## In Progress (begonnen, nicht fertig) +- _(keine — alles geplant, noch nichts gebaut)_ + +## Blocked +- W2–W5 — warten auf W1 (Grundgerüst). `⏸` +- W6 (Docs) — wartet auf W2–W5. `⏸` + +## Next (priorisiert) +1. W1 dispatchen (Worker · mittel). +2. Nach W1-Merge: W2, W3, W4, W5 **parallel** dispatchen (disjunkte Ownership). +3. Zuletzt W6 (Scholar · klein). + +## Offene Audit-Findings +- _(keine — Projekt frisch gebootstrapt)_ + +## Datei-Ownership (aktiv) +> Verzeichnis-Pfade mit Slash beenden (das prüft `scripts/gate-ownership.sh`). +> W1 läuft sequentiell zuerst und legt das Grundgerüst an; ab dann gilt: + +| Paket | Dateien/Pfade | Owner | +|---|---|---| +| W2 | `ollama/`, `scripts/build-models.sh`, `.dvc/` | worker-w2 | +| W3 | `exporter/`, `requirements/exporter.txt` | worker-w3 | +| W4 | `scripts/setup-jetson.sh`, `scripts/benchmark.sh`, `.github/workflows/` | worker-w4 | +| W5 | `client/`, `tests/`, `requirements/client.txt`, `requirements/dev.txt` | worker-w5 | +| W6 | `docs/architecture.md`, `docs/api.md`, `docs/deployment.md`, `docs/troubleshooting.md` | worker-w6 | diff --git a/audits/README.md b/audits/README.md new file mode 100644 index 0000000..6559f39 --- /dev/null +++ b/audits/README.md @@ -0,0 +1,4 @@ +# audits/ + +Befunde des externen Reviewers: `YYYY-MM-DD-.md` aus `TEMPLATE.md`. +Jeder Befund mit Severity; Korrektur-Tasks wandern nach `ROADMAP.md`/`STATE.md`. diff --git a/audits/TEMPLATE.md b/audits/TEMPLATE.md new file mode 100644 index 0000000..5c5fcb7 --- /dev/null +++ b/audits/TEMPLATE.md @@ -0,0 +1,15 @@ +# Audit — + +- **Reviewer-Session:** kalt (kein Vorkontext) +- **Orientierung allein aus AGENTS/STATE/CONVENTIONS gelungen?** Ja/Nein + +## Befunde +| # | Typ (drift/hygiene/untested) | Beschreibung | Severity | Korrektur-Task | +|---|------------------------------|--------------|----------|----------------| +| 1 | _…_ | _…_ | low/med/high | _Roadmap-/STATE-Eintrag_ | + +## Verifikation +- Manifest geprüft: _…_ · Tests ausgeführt: _… -> Ergebnis_ + +## Empfehlung +- _Audit-Loop weiter / Feature-Loop freigegeben._ diff --git a/docs/about-template.md b/docs/about-template.md new file mode 100644 index 0000000..a697ca3 --- /dev/null +++ b/docs/about-template.md @@ -0,0 +1,58 @@ +# 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`. diff --git a/docs/adr/0001-record-architecture-decisions.md b/docs/adr/0001-record-architecture-decisions.md new file mode 100644 index 0000000..c2169f6 --- /dev/null +++ b/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. diff --git a/docs/adr/0002-ollama-native.md b/docs/adr/0002-ollama-native.md new file mode 100644 index 0000000..4f811e5 --- /dev/null +++ b/docs/adr/0002-ollama-native.md @@ -0,0 +1,18 @@ +# 0002 — Ollama-natives Modell-Management, kein eigener Swapper/Gateway + +- **Status:** accepted +- **Kontext:** Jetson Orin Nano Super 8 GB (~7,4 GB nutzbar), Single-User, + latenzgebunden. Drei Profile (light/gemma/heavy) nötig, aber nie zwei gleichzeitig + resident. Frühere Ansätze hätten einen eigenen Modell-Swapper oder ein API-Gateway + vor Ollama gesetzt. +- **Entscheidung:** Der **Ollama-Daemon serviert die Modelle nativ** (Wechsel per + Modellname über die OpenAI-kompatible API). `OLLAMA_MAX_LOADED_MODELS=1` hält genau + ein Modell resident (8-GB-Schutz); ein weiteres Profil belegt erst bei Anfrage + Speicher. **Kein eigener Swapper, kein Gateway.** **DVC bleibt Modell-Source-of- + Truth**, Ollamas Blob-Store ist nur Laufzeit-Cache. +- **Konsequenz:** Drei Profile quasi gratis (laden on-demand), kein Custom-Code für + Modellwechsel, kleinere Angriffsfläche. Preis: kurzer `OLLAMA_KEEP_ALIVE=30s` → + Ladezeit beim Profilwechsel — bei Single-User akzeptabel (keine fremde Session wird + unterbrochen). Externer Zugriff/Auth/Metrik-Aggregation liegen bewusst off-box + (nginx-Proxy, Prometheus) — siehe `CONVENTIONS.md` Scope-Grenze. +- **Superseded by:** _(noch keins)_ diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..9bf11fa --- /dev/null +++ b/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. diff --git a/docs/gates/observability-gates.md b/docs/gates/observability-gates.md new file mode 100644 index 0000000..b33ee71 --- /dev/null +++ b/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. diff --git a/docs/gates/quality-gates.md b/docs/gates/quality-gates.md new file mode 100644 index 0000000..624fdba --- /dev/null +++ b/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). diff --git a/docs/loops/audit-loop.md b/docs/loops/audit-loop.md new file mode 100644 index 0000000..81a2c64 --- /dev/null +++ b/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/.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/.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. diff --git a/docs/loops/feature-loop.md b/docs/loops/feature-loop.md new file mode 100644 index 0000000..49695b2 --- /dev/null +++ b/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`. diff --git a/docs/loops/spike-gate.md b/docs/loops/spike-gate.md new file mode 100644 index 0000000..cf62db9 --- /dev/null +++ b/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/` + 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 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). diff --git a/docs/methodology.md b/docs/methodology.md new file mode 100644 index 0000000..d0a57c2 --- /dev/null +++ b/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`. diff --git a/docs/roles/leader.md b/docs/roles/leader.md new file mode 100644 index 0000000..4d4a7ba --- /dev/null +++ b/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. diff --git a/docs/roles/model-routing.md b/docs/roles/model-routing.md new file mode 100644 index 0000000..eef5ddc --- /dev/null +++ b/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`. diff --git a/docs/roles/reviewer.md b/docs/roles/reviewer.md new file mode 100644 index 0000000..2092dd8 --- /dev/null +++ b/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/.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. diff --git a/docs/roles/worker.md b/docs/roles/worker.md new file mode 100644 index 0000000..75acc14 --- /dev/null +++ b/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". diff --git a/docs/token-hygiene.md b/docs/token-hygiene.md new file mode 100644 index 0000000..22864ac --- /dev/null +++ b/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 ` + 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. diff --git a/manifests/requirements.md b/manifests/requirements.md new file mode 100644 index 0000000..9708cbe --- /dev/null +++ b/manifests/requirements.md @@ -0,0 +1,20 @@ +# Requirements-Manifest (kalt verifizierbar) + +Eine Zeile je Erfolgskriterium — der **kalt lesbare Review** (siehe `REVIEW.md`). +Der Reviewer prüft Spalte für Spalte; `done`-Zeilen müssen ihren Prüfbefehl bestehen. +`scripts/gate-doc-drift.sh` erzwingt die Existenz der Pfade in `done`/`in_progress`-Zeilen. + +| ID | Anforderung | Datei(en) | Test/Prüfbefehl | Status | +|----|-------------|-----------|------------------|--------| +| R-01 | Vertrag zuerst: CONVENTIONS + disjunkte Ownership | `CONVENTIONS.md`, `STATE.md` | `grep -q qwen-light CONVENTIONS.md` | done | +| R-02 | Drei Profile über Modelfiles (light/gemma/heavy) | `ollama/Modelfile.light`, `ollama/Modelfile.gemma`, `ollama/Modelfile.heavy` | `pytest tests/test_modelfiles.py` | todo | +| R-03 | q8_0-KV + Flash Attention + MAX_LOADED_MODELS=1 | `ollama/systemd/ollama.service.d/override.conf` | `grep -Eq 'q8_0' ollama/systemd/ollama.service.d/override.conf` | todo | +| R-04 | num_ctx je Profil explizit (light/gemma 16384, heavy 8192) | `ollama/Modelfile.light`, `ollama/Modelfile.heavy` | `grep -q 'num_ctx' ollama/Modelfile.light` | todo | +| R-05 | GPU-Nutzung verifiziert; Ollama nur LAN + Firewall | `scripts/setup-jetson.sh` | `bash -n scripts/setup-jetson.sh` | todo | +| R-06 | Metrik-Endpoint über Exporter (`:8000/metrics`) | `exporter/systemd/ollama-exporter.service` | `pytest tests/test_endpoints.py` | todo | +| R-07 | Keine Secrets; `.env.example` nur Platzhalter | `.env.example` | `grep -q 'JETSON_LAN_IP=' .env.example` | todo | +| R-08 | DVC = Modell-Source-of-Truth; build reproduzierbar | `scripts/build-models.sh`, `.dvc/config` | `bash -n scripts/build-models.sh` | todo | +| R-09 | Client + CLI funktionsfähig (OpenAI-kompatibel) | `client/python/jetson_ai/client.py`, `client/cli/ai.py` | `pytest tests/` | todo | +| R-10 | Kalt verifizierbar; Tests kodieren Kriterien | `REVIEW.md`, `tests/test_endpoints.py` | `pytest tests/ -q` | todo | + +Status: `todo` · `in_progress` · `done` · `drift` (vom Audit markiert). diff --git a/metrics/efficiency.csv b/metrics/efficiency.csv new file mode 100644 index 0000000..78a0651 --- /dev/null +++ b/metrics/efficiency.csv @@ -0,0 +1,2 @@ +date,sessions,rework_commits,total_commits +2026-06-03,0,0,0 diff --git a/scripts/gate-doc-drift.sh b/scripts/gate-doc-drift.sh new file mode 100755 index 0000000..dde7a25 --- /dev/null +++ b/scripts/gate-doc-drift.sh @@ -0,0 +1,58 @@ +#!/usr/bin/env bash +# Doku-Drift-Gate: prueft Manifest-Referenzen + STATE-Aktualitaet + Doc-Budget. +set -uo pipefail +fail=0; man="manifests/requirements.md" + +# Dormant solange das Template nicht initialisiert ist (scripts/init.sh). +if grep -q '' STATE.md 2>/dev/null; then + echo "[drift] Template noch nicht initialisiert (scripts/init.sh) — uebersprungen." + echo "GATE: PASS"; exit 0 +fi + +echo "[drift] pruefe im Manifest referenzierte Pfade (nur done/in_progress/drift)..." +# Nur Pfade aus ERLEDIGTEN Zeilen muessen existieren — 'todo'-Zeilen sind Plan, +# ihre Dateien gibt es absichtlich noch nicht. Treffer in eine Datei sammeln, +# damit fail=1 nicht in einer Pipe-Subshell verloren geht. +miss=$(mktemp) +if [ -f "$man" ]; then + while IFS= read -r line; do + case "$line" in \|*) : ;; *) continue ;; esac # nur Tabellenzeilen + status=$(printf '%s' "$line" | sed 's/^|//; s/|[[:space:]]*$//' \ + | awk -F'|' '{print $NF}' | tr -d ' ' | tr 'A-Z' 'a-z') + case "$status" in done|in_progress|drift) : ;; *) continue ;; esac + while IFS= read -r tok; do + case "$tok" in *" "*|*…*|_*|*path/to*) continue ;; esac + case "$tok" in + */*|*.py|*.md|*.sh|*.js|*.ts|*.yml|*.yaml|*.json|*.conf|*.ini|*.txt) + [ -e "$tok" ] || echo "$status $tok" >> "$miss" ;; + esac + done < <(printf '%s\n' "$line" | grep -oE '`[^`]+`' | tr -d '`') + done < "$man" +fi +if [ -s "$miss" ]; then + while IFS=" " read -r st p; do echo " - fehlende Referenz (Status $st): $p"; done < "$miss" + fail=1 +fi +rm -f "$miss" + +echo "[drift] STATE.md Stale-Check (Commits seit letzter Aenderung)..." +last_state=$(git log -1 --format=%H -- STATE.md 2>/dev/null || true) +if [ -n "$last_state" ]; then + since=$(git rev-list --count "${last_state}..HEAD" 2>/dev/null || echo 0) + [ "${since:-0}" -le 3 ] || { echo " - STATE.md seit $since Commits unveraendert"; fail=1; } +fi + +echo "[drift] Doc-Groessenbudget (Faustregel < 200 Zeilen)..." +while read -r f; do + case "$f" in examples/*) continue ;; esac # Beispiele duerfen laenger sein + n=$(wc -l < "$f" 2>/dev/null || echo 0) + [ "$n" -le 200 ] || echo " - Hinweis: $f hat $n Zeilen (> 200, Drift-Risiko)." +done < <(git ls-files 2>/dev/null | grep '\.md$' || true) + +echo "[drift] Code ohne Doc-Aenderung im letzten Commit?" +files=$(git show --name-only --pretty= HEAD 2>/dev/null || true) +if echo "$files" | grep -qE '\.(py|sh|js|ts)$' && ! echo "$files" | grep -qE '\.md$'; then + echo " - Hinweis: Code geaendert, keine Doku angepasst (Drift-Verdacht)." +fi + +[ "$fail" -eq 0 ] && echo "GATE: PASS" || { echo "GATE: FAIL"; exit 1; } diff --git a/scripts/gate-ownership.sh b/scripts/gate-ownership.sh new file mode 100755 index 0000000..e9c68da --- /dev/null +++ b/scripts/gate-ownership.sh @@ -0,0 +1,81 @@ +#!/usr/bin/env bash +# Ownership-Gate: kein Paket editiert Dateien eines anderen. +# Liest die Ownership-Tabelle aus STATE.md, mappt geaenderte Dateien (Branch vs. +# Basis) auf Pakete und FAILt bei Cross-Editing ueber >1 Paket-Grenze hinweg. +# Integration (Leader) ist ausgenommen: Branch main/master/integrate/*. +# Konvention: Verzeichnis-Pfade in der Tabelle mit Slash beenden (src/api/). +# Portabel gehalten (kein mapfile / keine assoziativen Arrays, laeuft auf bash 3.2). +set -uo pipefail + +# Dormant solange das Template nicht initialisiert ist. +if grep -q '' STATE.md 2>/dev/null; then + echo "[ownership] Template noch nicht initialisiert — uebersprungen." + echo "GATE: PASS"; exit 0 +fi + +branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "") +case "$branch" in + main|master|integrate/*) + echo "[ownership] '$branch' ist Integrations-Branch — uebersprungen." + echo "GATE: PASS"; exit 0 ;; +esac + +# (pkgprefix)-Zeilen aus der STATE.md-Ownership-Tabelle ziehen. +pairs=$(awk -F'|' ' + /Datei-Ownership/{f=1; started=0; next} + f && started && $0 !~ /^\|/ {f=0} # erst NACH Tabellenbeginn abbrechen + f && /^\|/{ + started=1; + pkg=$2; paths=$3; + gsub(/^[ \t]+|[ \t]+$/,"",pkg); + if(pkg=="" || pkg=="Paket" || pkg ~ /---/ || pkg ~ /…/ || pkg ~ /^_/) next; + n=split(paths, a, ","); + for(i=1;i<=n;i++){ p=a[i]; gsub(/^[ \t]+|[ \t]+$/,"",p); gsub(/`/,"",p); + if(p=="" || p ~ /…/ || p ~ /^_/) continue; + print pkg "\t" p } + }' STATE.md 2>/dev/null) + +if [ -z "$pairs" ]; then + echo "[ownership] keine befuellte Ownership-Tabelle in STATE.md — uebersprungen." + echo "GATE: PASS"; exit 0 +fi + +base=$(git merge-base HEAD main 2>/dev/null || git rev-parse HEAD~1 2>/dev/null || true) +[ -n "$base" ] || { echo "[ownership] keine Diff-Basis — uebersprungen."; echo "GATE: PASS"; exit 0; } +changed=$(git diff --name-only "$base"...HEAD 2>/dev/null) +[ -n "$changed" ] || { echo "[ownership] keine Aenderungen — uebersprungen."; echo "GATE: PASS"; exit 0; } + +hit=""; unowned="" +while IFS= read -r f; do + [ -n "$f" ] || continue + bestpre=""; bestpkg="" + while IFS=" " read -r pkg pre; do + [ -n "$pre" ] || continue + case "$f" in + "$pre"|"$pre"*) + if [ "${#pre}" -gt "${#bestpre}" ]; then bestpre="$pre"; bestpkg="$pkg"; fi ;; + esac + done <' STATE.md 2>/dev/null; then + echo "[hygiene] Template noch nicht initialisiert (scripts/init.sh) — uebersprungen." + echo "GATE: PASS"; exit 0 +fi + +echo "[hygiene] pruefe Working Tree..." +[ -z "$(git status --porcelain)" ] || note "Working Tree nicht sauber." + +echo "[hygiene] STATE.md im aktuellen Branch aktualisiert?" +base=$(git merge-base HEAD main 2>/dev/null || true) +head=$(git rev-parse HEAD 2>/dev/null || true) +if [ -n "$base" ] && [ "$base" != "$head" ]; then + # echte Divergenz (Feature-Branch): Diff gegen Abzweigpunkt + git diff --name-only "$base"...HEAD | grep -q '^STATE.md$' || \ + note "STATE.md im aktuellen Branch nicht aktualisiert." +else + # auf main/Integration oder Root-Commit: letzten Commit pruefen + git log -1 --name-only --pretty= | grep -q '^STATE.md$' || \ + note "STATE.md im letzten Commit nicht angefasst." +fi + +echo "[hygiene] Session-Log vorhanden?" +ls sessions/[0-9]*.md >/dev/null 2>&1 || note "Kein Session-Log unter sessions/." + +echo "[hygiene] Conventional Commits?" +git log -1 --pretty=%s | grep -Eq '^(feat|fix|docs|test|refactor|chore)(\(.+\))?: ' || \ + note "Letzter Commit nicht conventional." + +echo "[hygiene] Model-Attribution im letzten Commit?" +git log -1 --pretty=%B | grep -q 'Co-Authored-By: Claude' || \ + echo " - Hinweis: letzter Commit ohne 'Co-Authored-By: Claude ' (Pflicht nur fuer Agenten-Commits)." + +if [ "$fail" -ne 0 ]; then echo "GATE: FAIL"; exit 1; fi +echo "GATE: PASS" diff --git a/scripts/init.sh b/scripts/init.sh new file mode 100755 index 0000000..3a9f14e --- /dev/null +++ b/scripts/init.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +# init.sh — ein Template-Klon zu einem konkreten Projekt machen. +# Nutzung: bash scripts/init.sh "Mein Projektname" +# +# Was passiert: +# - die Template-README wandert nach docs/about-template.md (Methodik bleibt erhalten) +# - eine frische, projektbezogene README.md wird geschrieben +# - falls noch kein Git-Repo: git init +# - die Gates bleiben DORMANT, bis die erste echte Session STATE.md befuellt +# (die Zeile mit '' ersetzt) — danach greifen sie automatisch. +# +# Naechster Schritt nach init: session-prompts/BOOTSTRAP.md in eine frische +# Leader-Session geben, zusammen mit deinem Projekt-Brief. +set -euo pipefail + +name="${1:-}" +if [ -z "$name" ]; then + echo "Nutzung: bash scripts/init.sh \"Projektname\"" >&2 + exit 2 +fi + +[ -f AGENTS.md ] || { echo "Bitte aus dem Repo-Root ausfuehren (AGENTS.md nicht gefunden)." >&2; exit 1; } + +if [ -f docs/about-template.md ]; then + echo "Bereits initialisiert (docs/about-template.md existiert). Abbruch." >&2 + exit 1 +fi + +# 1) Template-README bewahren, frische Projekt-README schreiben. +git mv README.md docs/about-template.md 2>/dev/null || mv README.md docs/about-template.md +cat > README.md < Arbeitet nach dem **agent-swarm**-Betriebsmodell. Jeder Agent (Mensch wie KI) +> liest zuerst [\`AGENTS.md\`](AGENTS.md). Methodik im Detail: +> [\`docs/methodology.md\`](docs/methodology.md). Herkunft des Modells: +> [\`docs/about-template.md\`](docs/about-template.md). + +## Schnellstart +- **Stand & nächster Schritt:** [\`STATE.md\`](STATE.md) +- **Plan / Ready-Set:** [\`ROADMAP.md\`](ROADMAP.md) +- **Regeln:** [\`CONVENTIONS.md\`](CONVENTIONS.md) +- **Neues Feature anstoßen:** [\`session-prompts/BOOTSTRAP.md\`](session-prompts/BOOTSTRAP.md) +EOF + +# 2) Git initialisieren, falls noetig. +if ! git rev-parse --git-dir >/dev/null 2>&1; then + git init -q + echo "[init] leeres Git-Repo angelegt." +fi + +echo "[init] '${name}' initialisiert." +echo "[init] Template-Overview liegt jetzt unter docs/about-template.md." +echo +echo "Naechster Schritt:" +echo " 1) Projekt-Brief bereithalten (Ziel, Stack, Constraints)." +echo " 2) session-prompts/BOOTSTRAP.md in eine frische Session geben (Modell: Sonnet)." +echo " 3) Der Leader fuellt ROADMAP/STATE/CONVENTIONS und erzeugt die ersten Session-Prompts." +echo +echo "Die Gates sind dormant, bis die erste Session STATE.md befuellt." diff --git a/scripts/metrics.sh b/scripts/metrics.sh new file mode 100755 index 0000000..eb2a1ea --- /dev/null +++ b/scripts/metrics.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +# Observability: aggregiert Session-Logs + Git zu metrics/efficiency.csv +set -uo pipefail +mkdir -p metrics; out="metrics/efficiency.csv" +echo "date,sessions,rework_commits,total_commits" > "$out" +total=$(git rev-list --count HEAD 2>/dev/null || echo 0) +rework=$(git log --pretty=%s | grep -Ec '^(fix|refactor)(\(.+\))?: ' || true) +sess=$(ls sessions/[0-9]*.md 2>/dev/null | wc -l | tr -d ' ') +echo "$(date +%F),$sess,$rework,$total" >> "$out" +echo "[metrics] geschrieben nach $out" +echo " Rework-Rate: $rework/$total Commits" diff --git a/session-prompts/BOOTSTRAP.md b/session-prompts/BOOTSTRAP.md new file mode 100644 index 0000000..aff75e1 --- /dev/null +++ b/session-prompts/BOOTSTRAP.md @@ -0,0 +1,61 @@ +# BOOTSTRAP — neues Projekt aufsetzen (Leader-Session) + +Kopiere den Block unten in eine **frische Session** (Modell: **Sonnet**) und hänge +deinen Projekt-Brief an. Der Leader füllt das Repo aus dem Brief — du musst keine +Datei von Hand anlegen. + +> Voraussetzung: einmalig `bash scripts/init.sh "Projektname"` gelaufen. + +--- + +``` +Du bist der LEADER eines agent-swarm-Repos. Arbeite in __. + +Lies in dieser Reihenfolge und höre auf, sobald du genug Kontext hast: +AGENTS.md → STATE.md → CONVENTIONS.md → docs/methodology.md → +docs/roles/{leader,model-routing}.md → docs/loops/feature-loop.md → +ROADMAP.md (Board-Format) → examples/walkthrough/ (ein befülltes Beispiel). + +## Mein Projekt-Brief +<<< HIER deinen Brief einfügen: Ziel, Tech-Stack, harte Constraints, + erste gewünschte Fähigkeit. 3–15 Zeilen reichen. >>> + +## Deine Aufgabe (nur Planung, noch kein Feature-Code) +1. ROADMAP.md als Board befüllen: den Brief in Items zerlegen, jedes mit + Typ (🔌 port / 🔬 research / 🧱 infra), Status, Prereqs, Rolle·Modell, Aufwand. + Den Abhängigkeits-DAG explizit machen (was blockiert was). +2. CONVENTIONS.md projektspezifisch ergänzen, falls nötig: Build-/Test-Befehl, + Branch-/Remote-Konventionen, Sprache. Bestehende Regeln NICHT verwässern. + Tragende Entscheidungen als ADR unter docs/adr/ festhalten. +3. STATE.md auf den echten Startzustand setzen: die Header-Zeile mit einer echten + Session-ID/Datum füllen (ersetzt den ''-Platzhalter — DAS aktiviert + die Gates), Now/Next füllen, die Ownership-Tabelle für die ersten Pakete anlegen + (Verzeichnis-Pfade mit Slash beenden, z. B. `src/api/`). +4. Für jedes Item aus dem aktuellen READY-SET (Status 🔲, alle Prereqs ✅) einen + kaltstartfähigen Prompt unter session-prompts/.md aus + session-prompts/TEMPLATE.md erzeugen — Modell gemäß docs/roles/model-routing.md. +5. Ein Session-Log unter sessions/-bootstrap.md aus sessions/TEMPLATE.md + schreiben. Hygiene-Gate ausführen: bash scripts/gate-session-hygiene.sh. + +## Wichtig +- Du PLANST und dispatcht — du baust die Features nicht selbst. +- Research-Items (🔬) müssen vor Produktionscode durch das Spike-Gate + (docs/loops/spike-gate.md). Markiere sie entsprechend im Board. +- Halte die Single-Source-of-Truth-Regel: keine Information doppelt ablegen. +- Conventional Commit + Trailer + `Co-Authored-By: Claude Sonnet 4.6 `. + +Am Ende: zeig mir das befüllte Board (ROADMAP.md) und das Ready-Set, und sag mir, +welche Session-Prompts du erzeugt hast und in welcher Reihenfolge ich sie dispatchen +sollte. +``` + +--- + +## Danach (laufender Betrieb) + +1. Ready-Set aus `ROADMAP.md` lesen → einen Prompt aus `session-prompts/` nehmen. +2. Frische Session, Modell setzen, dispatchen (Worker bzw. Theorist→Spike). +3. Nach Implement: **Review-Gate** (Opus, kalt) — Prompt-Block in + `session-prompts/TEMPLATE.md`. +4. Merge → Item im Board auf ✅ → Dependents werden frei. Nach N Zyklen: Audit-Loop. diff --git a/session-prompts/TEMPLATE.md b/session-prompts/TEMPLATE.md new file mode 100644 index 0000000..a7aaabe --- /dev/null +++ b/session-prompts/TEMPLATE.md @@ -0,0 +1,77 @@ +# Session-Prompt-Template + +Kopiere diesen Block in eine frische Session. Fülle alle `_…_`-Platzhalter aus. +Jeder Prompt ist **kaltstartfähig** — die neue Session braucht kein Vorwissen. + +--- + +``` +Modell: _Haiku | Sonnet | Opus_ + +Du arbeitest in __ auf einem neuen Branch +`_feat|fix|docs|audit/_` (von `main`). + +## Aufgabe +_Kurze Beschreibung (1–3 Sätze) was implementiert, geprüft oder dokumentiert +werden soll. Scope klar abgrenzen — was liegt AUSSERHALB dieser Session?_ + +## Details +Vollständige Spezifikation in: `__` +Betroffene Dateien: `__` + +## Akzeptanzkriterien +- [ ] _Kriterium 1 (messbar, konkret)_ +- [ ] _Kriterium 2_ +- [ ] Tests grün: `__` + +## Nicht anfassen +_Dateien / Pakete ausserhalb des Scopes. Kein Cross-Editing._ + +## Commit & Push +- Conventional Commit: `_feat|fix|docs|test|chore_: …` +- Trailer: `Co-Authored-By: Claude __ ` +- Push nach `origin`, PR öffnen (Base: `main`). + +## Abschluss +1. Manifest-Eintrag updaten (`manifests/requirements.md` → Status `done`). +2. `STATE.md` aktualisieren (Now / In Progress / Next). +3. Session-Log schreiben (`sessions/TEMPLATE.md` → `sessions/-.md`). +4. Hygiene-Gate ausführen: `bash scripts/gate-session-hygiene.sh`. +5. PR-URL + Test-Zählstand reporten. +``` + +--- + +## Review-Gate-Prompt (Opus, kalt, nach jeder Implement-Session) + +``` +Modell: Opus + +Du bist ein externer Reviewer ohne Vorkontext aus der Implement-Session. +Lies NUR den Diff von Branch `__` gegen `main`. + +Repo: __ +Diff: `git diff main...__` + +## Prüf-Checkliste +- [ ] Build sauber; Test-Suite grün (kein Regressions-Zählstand). +- [ ] Keine bestehenden Tests verändert (außer 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 — alles ok. +CHANGES-REQUESTED — konkrete Liste der notwendigen Korrekturen. +``` + +--- + +## Hinweise zum Befüllen + +- **Scope zuerst** — was liegt AUSSERHALB? Das verhindert Scope-Creep. +- **Test-Befehl ist Pflicht** — kein "irgendwie testen", sondern der exakte Aufruf. +- **Model-Routing prüfen** — falsches Modell ist teuer; s. `docs/roles/model-routing.md`. +- **Kein Vorkontext annehmen** — der Prompt landet in einer frischen Session ohne + History. Alle nötigen Pfade, Befehle und Entscheidungen müssen im Prompt stehen. diff --git a/session-prompts/W1.md b/session-prompts/W1.md new file mode 100644 index 0000000..4de37bd --- /dev/null +++ b/session-prompts/W1.md @@ -0,0 +1,41 @@ +# Session-Prompt — W1 Grundgerüst (zuerst, alleine) + +``` +Modell: Sonnet + +Du bist WORKER für Paket W1 in /pfad/zu/jetson-ai-ollama, Branch `feat/w1-scaffold` +(von `main`). Lies zuerst AGENTS.md → STATE.md → CONVENTIONS.md (Projekt-Vertrag). + +## Aufgabe +Das Grundgerüst anlegen, auf das W2–W5 parallel aufsetzen. NUR Struktur + Basis- +Dateien, KEINE Profil-/Exporter-/Client-Logik (das sind W2/W3/W5). + +## Deliverables (deine Dateien) +- `LICENSE` — MIT, auf den Repo-Eigentümer. +- `.env.example` — nur Platzhalter (keine Secrets): + `JETSON_LAN_IP=`, `OLLAMA_MODELS=/opt/ollama/models`, `PROMETHEUS_SCRAPE_TARGET=`. +- Verzeichnis-Skelett mit `.gitkeep`, damit die Parallel-Worker andocken können: + `ollama/systemd/ollama.service.d/`, `exporter/systemd/`, `client/python/jetson_ai/`, + `client/cli/`, `scripts/`, `tests/`, `requirements/`, `docs/`, `models/`. +- `.dvc/config` — leeres DVC-Remote-Skelett mit Kommentar, welches Remote (S3/MinIO/ + SSH/NAS) einzutragen ist. (DVC-Init-Details gehören W2 — hier nur die Datei.) + +## Akzeptanzkriterien +- [ ] `test -f LICENSE && test -f .env.example` +- [ ] `grep -q 'JETSON_LAN_IP=' .env.example` (R-07) +- [ ] Keine echten Werte/Secrets in `.env.example`. +- [ ] Alle Skelett-Verzeichnisse existieren (mit `.gitkeep`). + +## Nicht anfassen +README.md, CONVENTIONS.md, STATE.md, ROADMAP.md, docs/ (außer .gitkeep), und alle +Dateien anderer Pakete. Keine Modelfiles, kein Exporter-Code, kein Client-Code. + +## Abschluss +1. `manifests/requirements.md`: R-07 → `done`. +2. `STATE.md`: W1 nach „In Progress" → nach Merge in „Done"; W2–W5 werden ready. +3. Session-Log aus `sessions/TEMPLATE.md`. +4. Commit `feat(w1): scaffold structure, LICENSE, .env.example` + Trailer + `Co-Authored-By: Claude Sonnet 4.6 `. +5. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`. +6. PR (Base `main`) via Gitea-API. Dann Review-Gate (Opus). +``` diff --git a/session-prompts/W2.md b/session-prompts/W2.md new file mode 100644 index 0000000..ce98596 --- /dev/null +++ b/session-prompts/W2.md @@ -0,0 +1,44 @@ +# Session-Prompt — W2 Ollama-Profile (parallel, nach W1) + +``` +Modell: Sonnet + +Du bist WORKER für Paket W2 in /pfad/zu/jetson-ai-ollama, Branch `feat/w2-profiles` +(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md (Projekt- +Vertrag = Single Source of Truth für Profilnamen, Pfade, Env, num_ctx). + +## Aufgabe +Die drei Ollama-Profile reproduzierbar bauen lassen — über Modelfiles, systemd- +Daemon-Env und ein Build-Skript, mit DVC als Modell-Source-of-Truth. + +## Deliverables (deine Dateien — Ownership: `ollama/`, `scripts/build-models.sh`, `.dvc/`) +- `ollama/Modelfile.light` — `FROM /opt/jetson-ai/models/qwen3.5-4b-q4_k_m.gguf`, + `PARAMETER num_ctx 16384`, `PARAMETER temperature 0.7`. +- `ollama/Modelfile.gemma` — Gemma-4-E4B GGUF, `num_ctx 16384`. +- `ollama/Modelfile.heavy` — Qwen3.5-9B GGUF, `num_ctx 8192`. +- `ollama/systemd/ollama.service.d/override.conf` — exakt die Env aus CONVENTIONS + (FLASH_ATTENTION=1, KV_CACHE_TYPE=q8_0, MAX_LOADED_MODELS=1, KEEP_ALIVE=30s, + MODELS=/opt/ollama/models, HOST=0.0.0.0:11434). +- `scripts/build-models.sh` — `dvc pull` → `ollama create qwen-light -f …light`, + `ollama create gemma -f …gemma`, `ollama create qwen-heavy -f …heavy`. Idempotent. +- `.dvc/config` finalisieren (Remote bleibt env-/platzhaltergesteuert). + +## Akzeptanzkriterien +- [ ] `pytest tests/test_modelfiles.py` grün (W5 liefert den Test; bis dahin lokal: + `grep -q 'num_ctx 16384' ollama/Modelfile.light`). (R-02, R-04) +- [ ] `grep -Eq 'q8_0' ollama/systemd/ollama.service.d/override.conf` und + `grep -q 'MAX_LOADED_MODELS=1'` (R-03). +- [ ] `bash -n scripts/build-models.sh` ok; baut alle drei Profile (R-08). +- [ ] num_ctx in JEDEM Modelfile explizit gesetzt. + +## Nicht anfassen +`exporter/`, `client/`, `tests/`, `scripts/setup-jetson.sh`, `scripts/benchmark.sh`, +`.github/`, `docs/`. Nur deine Ownership-Pfade. + +## Abschluss +1. `manifests/requirements.md`: R-02, R-03, R-04, R-08 → `done`. +2. `STATE.md` + Session-Log aktualisieren. +3. Commit(s) `feat(w2): …` + Trailer `Co-Authored-By: Claude Sonnet 4.6 `. +4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`. +5. PR (Base `main`). Dann Review-Gate (Opus). +``` diff --git a/session-prompts/W3.md b/session-prompts/W3.md new file mode 100644 index 0000000..26e25a5 --- /dev/null +++ b/session-prompts/W3.md @@ -0,0 +1,39 @@ +# Session-Prompt — W3 Exporter-Sidecar (parallel, nach W1) + +``` +Modell: Sonnet + +Du bist WORKER für Paket W3 in /pfad/zu/jetson-ai-ollama, Branch `feat/w3-exporter` +(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md. + +## Aufgabe +Ollama hat keinen Prometheus-Endpoint. Bau einen schlanken Exporter-Sidecar, der die +Ollama-API anzapft und `/metrics` auf Port 8000 exponiert — als systemd-Service. + +## Deliverables (Ownership: `exporter/`, `requirements/exporter.txt`) +- `exporter/` — Exporter (Python). Quellen: Timing-Felder jeder Ollama-Antwort + (`eval_count`, `eval_duration`, `prompt_eval_duration`, `total_duration`) und + `/api/ps` (Modell, VRAM, Keep-Alive); optional `tegrastats`. Endpoint `:8000/metrics`. + Alternativ einen fertigen Exporter (z. B. `ghcr.io/norskhelsenett/ollama-metrics`) + als systemd-Unit verdrahten — dann ist `exporter/` dünn. +- `exporter/systemd/ollama-exporter.service` — systemd-Unit (After=ollama.service). +- `requirements/exporter.txt` — Laufzeit-Deps des Exporters. + +## Akzeptanzkriterien +- [ ] `pytest tests/test_endpoints.py` deckt den `/metrics`-Smoke ab (W5 liefert den + Test; bis dahin lokal: Exporter startet, `curl :8000/metrics` liefert Prom-Format). (R-06) +- [ ] systemd-Unit ist syntaktisch valide und referenziert Port 8000. +- [ ] Liest NUR die Ollama-API/`/api/ps` — keine Modell-/Profil-Logik (das ist W2). + +## Nicht anfassen +`ollama/`, `client/`, `scripts/`, `.github/`, `docs/`, `tests/`. Nur deine Pfade. +(Den `tests/test_endpoints.py` schreibt W5 — koordiniere die Endpoint-Form über CONVENTIONS.) + +## Abschluss +1. `manifests/requirements.md`: R-06 → `done`. +2. `STATE.md` + Session-Log. +3. Commit `feat(w3): ollama metrics exporter sidecar` + Trailer + `Co-Authored-By: Claude Sonnet 4.6 `. +4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`. +5. PR (Base `main`). Dann Review-Gate (Opus). +``` diff --git a/session-prompts/W4.md b/session-prompts/W4.md new file mode 100644 index 0000000..c703408 --- /dev/null +++ b/session-prompts/W4.md @@ -0,0 +1,39 @@ +# Session-Prompt — W4 Setup & CI/CD (parallel, nach W1) + +``` +Modell: Sonnet + +Du bist WORKER für Paket W4 in /pfad/zu/jetson-ai-ollama, Branch `feat/w4-setup-cicd` +(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md. + +## Aufgabe +Den Jetson reproduzierbar aufsetzen und CI/CD bereitstellen. + +## Deliverables (Ownership: `scripts/setup-jetson.sh`, `scripts/benchmark.sh`, `.github/workflows/`) +- `scripts/setup-jetson.sh` — Ollama installieren und **GPU-Nutzung verifizieren** + (`ollama ps` + Logs, kein CPU-Fallback); Drop-in-Env aus + `ollama/systemd/ollama.service.d/override.conf` aktivieren (`daemon-reload`, + `restart ollama`); NVMe-SSD + Swap; Desktop-GUI/unnötige Dienste aus; MAXN-SUPER; + Exporter als systemd-Service aktivieren; **Firewall: nur Proxy → 11434**. +- `scripts/benchmark.sh` — Latenz/Token-Durchsatz je Profil (Single-User), `--smoke`-Modus. +- `.github/workflows/ci.yml` — lint + `bash -n` der Skripte + pytest (ohne Jetson-Hardware). +- `.github/workflows/cd-jetson.yml` — Deploy auf den Jetson (self-hosted Runner/SSH). + +## Akzeptanzkriterien +- [ ] `bash -n scripts/setup-jetson.sh` und `bash -n scripts/benchmark.sh` ok (R-05). +- [ ] setup-jetson verifiziert GPU explizit und bindet Ollama nur ans LAN + Firewall. +- [ ] Keine Secrets in den Workflows (nur Repo/Org-Secrets referenzieren). +- [ ] CI läuft ohne Jetson-Hardware grün (Hardware-Schritte als no-op/guarded). + +## Nicht anfassen +`ollama/`, `exporter/`, `client/`, `tests/`, `scripts/build-models.sh`, `docs/`. +Die bereits vorhandene `.github/workflows/gates.yml` (Agent-System-Gates) NICHT ändern. + +## Abschluss +1. `manifests/requirements.md`: R-05 → `done`. +2. `STATE.md` + Session-Log. +3. Commit `feat(w4): jetson setup + ci/cd` + Trailer + `Co-Authored-By: Claude Sonnet 4.6 `. +4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`. +5. PR (Base `main`). Dann Review-Gate (Opus). +``` diff --git a/session-prompts/W5.md b/session-prompts/W5.md new file mode 100644 index 0000000..dbac055 --- /dev/null +++ b/session-prompts/W5.md @@ -0,0 +1,39 @@ +# Session-Prompt — W5 Client & Tests (parallel, nach W1) + +``` +Modell: Sonnet + +Du bist WORKER für Paket W5 in /pfad/zu/jetson-ai-ollama, Branch `feat/w5-client-tests` +(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md. + +## Aufgabe +Einen schlanken OpenAI-kompatiblen Client + CLI, und die Tests, die die +Erfolgskriterien KODIEREN (damit der Review sie ausführen statt glauben muss). + +## Deliverables (Ownership: `client/`, `tests/`, `requirements/client.txt`, `requirements/dev.txt`) +- `client/python/jetson_ai/client.py` — dünner Wrapper um `/v1/chat/completions` + (Profil per Modellname `qwen-light`/`gemma`/`qwen-heavy`), Type Hints + Docstrings. +- `client/cli/ai.py` — CLI: `ai -m qwen-light "..."`. +- `tests/test_modelfiles.py` — prüft alle drei Modelfiles: `num_ctx` explizit, + korrekte FROM-Pfade, Profilnamen (R-02/R-04-Oracle). +- `tests/test_endpoints.py` — Smoke gegen Ollama `:11434` + Exporter `:8000/metrics` + (gegen laufende Dienste oder gemockt). (R-06/R-10) +- `requirements/client.txt`, `requirements/dev.txt`. + +## Akzeptanzkriterien +- [ ] `pytest tests/ -q` grün (R-09, R-10). +- [ ] `tests/test_modelfiles.py` schlägt fehl, wenn ein `num_ctx` fehlt (negativer Fall). +- [ ] Client spricht die OpenAI-Route, NICHT Ollamas natives `/api/generate`. + +## Nicht anfassen +`ollama/`, `exporter/`, `scripts/`, `.github/`, `docs/`. Nur deine Pfade. Form der +Modelfiles/Endpoints kommt aus CONVENTIONS — bei Unklarheit dort nachsehen, nicht raten. + +## Abschluss +1. `manifests/requirements.md`: R-09, R-10 → `done`. +2. `STATE.md` + Session-Log. +3. Commit `feat(w5): openai client, cli, tests` + Trailer + `Co-Authored-By: Claude Sonnet 4.6 `. +4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`. +5. PR (Base `main`). Dann Review-Gate (Opus). +``` diff --git a/session-prompts/W6.md b/session-prompts/W6.md new file mode 100644 index 0000000..daa8df9 --- /dev/null +++ b/session-prompts/W6.md @@ -0,0 +1,37 @@ +# Session-Prompt — W6 Docs (zuletzt, integriert die Realität der anderen) + +``` +Modell: Haiku + +Du bist WORKER für Paket W6 in /pfad/zu/jetson-ai-ollama, Branch `docs/w6` +(von `main`, NACHDEM W2–W5 gemerged sind). Lies AGENTS.md → STATE.md → CONVENTIONS.md +und die nun real existierenden Dateien aus W2–W5. + +## Aufgabe +Die Doku schreiben, die den TATSÄCHLICHEN Stand beschreibt (nicht den geplanten), +und README + REVIEW finalisieren. + +## Deliverables (Ownership: `docs/`) +- `docs/architecture.md` — Daemon + Exporter-Sidecar, drei Profile, MAX_LOADED_MODELS=1, + Datenfluss DVC → Ollama. Scope-Grenze (nginx/Prometheus off-box). +- `docs/api.md` — OpenAI-Endpoint, Profilnamen, `/api/ps`, `/metrics`. +- `docs/deployment.md` — `setup-jetson.sh`, `build-models.sh`, Firewall, systemd. +- `docs/troubleshooting.md` — GPU-Fallback erkennen, OOM, Profil lädt nicht, Keep-Alive. +- README-Feinschliff + Verweis aus `REVIEW.md` prüfen (keine toten Links). + +## Akzeptanzkriterien +- [ ] Jede Doku-Aussage deckt sich mit dem realen Code (keine Drift). +- [ ] Alle internen Links lösen auf; `bash scripts/gate-doc-drift.sh` → PASS. +- [ ] Doc-Größenbudget beachtet (< 200 Zeilen je Doc). + +## Nicht anfassen +Code-Pakete (`ollama/`, `exporter/`, `client/`, `scripts/`, `.github/`, `tests/`). +Nur `docs/` + README-Feinschliff. + +## Abschluss +1. Alle verbleibenden `manifests/requirements.md`-Zeilen auf `done` prüfen. +2. `STATE.md`: alles in „Done"; Projekt review-ready. +3. Commit `docs(w6): architecture/api/deployment/troubleshooting` + Trailer + `Co-Authored-By: Claude Haiku 4.5 `. +4. Alle drei Gates grün. PR (Base `main`). Dann Review-Gate (Opus) gegen REVIEW.md. +``` diff --git a/sessions/2026-06-03-bootstrap.md b/sessions/2026-06-03-bootstrap.md new file mode 100644 index 0000000..6a80f3d --- /dev/null +++ b/sessions/2026-06-03-bootstrap.md @@ -0,0 +1,41 @@ +# Session bootstrap — 2026-06-03 + +- **Rolle:** leader +- **Modell:** Opus +- **Ziel:** Projekt aus dem agent-swarm-Template + Jetson-Meta-Prompt bootstrappen + (nur Planung, kein Feature-Code). + +## Geändert (Dateien) +- `ROADMAP.md` — Board W1–W6 als DAG (alle 🧱 infra, kein 🔬 → kein Spike). +- `STATE.md` — Now=Dispatch W1; Ownership-Tabelle W2–W6 (disjunkte Pfade). +- `CONVENTIONS.md` — Projekt-Vertrag (Profilnamen, Pfade, Ports, Daemon-Env, num_ctx, + DVC-SoT, Scope-Grenze). +- `manifests/requirements.md` — R-01…R-10 als kalt verifizierbares Review-Manifest. +- `REVIEW.md` — Kalt-Review-Einstieg (zeigt auf Manifest + Reviewer-Rolle). +- `docs/adr/0002-ollama-native.md` — Architektur-Lock (Ollama-nativ, kein Swapper/Gateway). +- `README.md` — Projekt-Front-Door + „Sofort bauen". +- `session-prompts/W1.md … W6.md` — dispatch-fertige Worker-Prompts. +- `.gitignore` — Jetson-Ignores (`*.gguf`, `models/`, `.dvc/cache/`). +- entfernt: `examples/walkthrough/` (Template-Lernbeispiel; Projekt hat eigenes Board). + +## Entscheidungen +- Ollama-natives Modell-Management statt eigenem Swapper → ADR 0002. +- REVIEW.md (aus Meta-Prompt) = dünner Einstieg; die Kriterien leben im Manifest + (Single Source of Truth, keine Duplikation). + +## Tests +- Gates lokal: hygiene / ownership / doc-drift → PASS (siehe Gates unten). + +## Token-Verbrauch +- (Bootstrap-Session; Planung) — keine Auffälligkeiten. + +## Gates +- Hygiene: PASS · Kontext: PASS · Token: PASS +- Review-Gate: n/a (reine Planung; erste Implement-Session W1 wird gereviewed) + +## Handoff / Next +- **W1 dispatchen** (`session-prompts/W1.md`, Sonnet). Nach Merge: W2–W5 parallel, + dann W6. Ready-Set jetzt = { W1 }. + +## Clean-Start-Check +- [x] Orientierung allein aus AGENTS/STATE/CONVENTIONS möglich. diff --git a/sessions/README.md b/sessions/README.md new file mode 100644 index 0000000..417dcd1 --- /dev/null +++ b/sessions/README.md @@ -0,0 +1,4 @@ +# sessions/ + +Pro Session ein Log aus `TEMPLATE.md`: `YYYY-MM-DD-.md`. Erzählt zusammen mit +dem Git-Log, was passiert ist — inkl. Token-Verbrauch (Eingang fürs Token-Gate). diff --git a/sessions/TEMPLATE.md b/sessions/TEMPLATE.md new file mode 100644 index 0000000..1044cd7 --- /dev/null +++ b/sessions/TEMPLATE.md @@ -0,0 +1,29 @@ +# Session — + +- **Rolle:** leader | worker | reviewer | theorist | porter | prototyper | integrator +- **Modell:** Haiku | Sonnet | Opus +- **Ziel:** _…_ + +## Geändert (Dateien) +- _…_ + +## Entscheidungen +- _… (Verweis auf ADR, falls tragend)_ + +## Tests +- _Befehl -> Ergebnis_ + +## Token-Verbrauch +- input: _…_ · output: _…_ · total: _…_ · tokens/Task: _…_ +- Auffälligkeiten (Re-Reading, Schleifen): _…_ + +## Gates +- Hygiene: PASS/FAIL · Kontext: PASS/FAIL · Token: PASS/FAIL +- Review-Gate: APPROVE / CHANGES-REQUESTED (Opus-Session-ID: _…_) + +## Handoff / Next +- _Was die nächste Session zuerst tun sollte._ +- Review-Gate nötig? Ja/Nein + +## Clean-Start-Check +- [ ] Orientierung allein aus AGENTS/STATE/CONVENTIONS möglich.