# Planer

Ein System, mit dem ich alle meine Projekte **verstehe, orchestriere und weiterentwickle** —
ohne je die Übersicht zu verlieren, was ein Projekt kann. Wiedereinlesen nach Monaten in
Minuten; Änderungen laufen über ein Agenten-Team, das wie ein Entwicklungsunternehmen
arbeitet, in dem ich der Geschäftsführer bin.

Dieses Dokument ist die **Referenz der Planung** (Stand 2026-07-09). Das System ist noch
nicht gebaut; wir implementieren schrittweise entlang der Phasen am Ende. Nichts hier ist
Code-Realität, bis es umgesetzt und abgehakt ist.

Referenz-Projekt: `../creator` — dort sind die Kern-Muster bereits validiert
(generische Kanban-Engine `kanban.py`, Provider-Layer `agents.py`, Judge-Gates,
Resume, Events-Telemetrie, Fake-Agenten für Tests).

---

## Leitprinzipien

1. **Die Wahrheit wohnt im Projekt-Repo.** Artefakte sind Dateien unter `.planer/` im
   jeweiligen Projekt, versioniert mit dem Code. Code-Änderung + Artefakt-Update = ein
   Commit (atomarer Sync). Der Planer ist Viewer + Orchestrator, nie Wahrheitsbesitzer;
   seine DB hält nur wegwerfbaren Lauf-Zustand und Telemetrie.
2. **Kein LLM als Default oder Fallback — nirgendwo.** Jeder LLM-Schritt hat eine benannte
   Rolle; die Zuordnung Rolle → Modell steht ausschließlich in einer zentralen Config, vom
   Nutzer per UI gesetzt. Unkonfigurierte Rolle oder Provider nicht erreichbar = Lauf
   pausiert mit sichtbarer Meldung. Niemals stiller Wechsel. (Hintergrund: ein stiller
   Fallback hat einmal ~40 % des Claude-Abo-Kontingents gekostet.) Mechanisch absichern:
   Test greppt nach Modell-IDs außerhalb der Config.
3. **Provider-Unabhängigkeit.** Eigenes Agentensystem (Creator-Bausteine wiederverwenden),
   damit jederzeit zwischen Claude (Fable/Opus/Sonnet/Haiku) und MiniMax (M3/M2.7-HS/M2.7)
   gewechselt werden kann — später auch lokale LLMs. Der Provider-Fallback in
   `creator/backend/agents.py` („routed provider unavailable → run provider") wird NICHT
   übernommen.
4. **Mechanisch vor LLM.** Alles, was Skripte prüfen können (Anker-Existenz, Tests, Lint,
   Diff-Umfang), läuft ohne Token und vor jedem LLM-Urteil.
5. **Messinvarianz.** Telemetrie und QA messen nur; sie sind nie Teil einer Optimierung.
6. **Die UI zeigt, was Handlung braucht — nicht alles, was passiert.** Autonome Agenten
   bleiben Hintergrundrauschen; nur Entscheidungen, Drift und Ergebnisse drängen sich vor.
7. **YAGNI.** Zielbild vollständig planen (dieses Dokument), aber jede Phase baut nur, was
   sie braucht. Wachstum gesteuert durch Telemetrie und tatsächlichen Gebrauch.
8. **Scan-Ausschlussliste, Secrets nie lesen.** Der Scan liest `.env`, `node_modules`,
   Build-Artefakte etc. grundsätzlich nicht — Fakten zitieren Code, und ein zitierter
   API-Key stünde sonst im Klartext im Artefakt (Repo!) und in den Agent-Transkripten.

---

## Wissensschichten (Dateien in `<projekt>/.planer/`)

Drei Schichten beantworten drei Fragen:

### 1. Einheiten — *was der Code tut* (Beleg-Schicht)

Atomare Codebereiche, MECE über den Code: jede Code-Stelle gehört zu genau einer Einheit.
Schnittregel: das Kleinste mit eigener Verantwortung, in einem Satz beschreibbar — mal
eine Funktion, mal eine Klasse, mal ein zusammengehöriger Block. Der Scan-Agent schneidet
nach dieser Regel (kein Parser); v1 beginnt auf Symbol-Ebene, Kleinkram (Imports, Config)
darf anfangs unzugeordnet bleiben.

Jede Einheit trägt:
- **Anker**: Pfad + Symbol + Commit-Hash des letzten Scans (stabile Identität; bei
  Moves/Renames matcht der Re-Scan nach, statt gelöscht+neu zu melden)
- **Ein-Satz-Beschreibung** (die Verantwortung)
- **Fakten**: belegte Aussagen über das Verhalten
- **Beziehungen/Kanten**: ruft auf / importiert / wird ausgelöst von → andere Einheiten

### 2. Artefakt-Sichten — *was das Projekt kann*

Überlappende Sichten auf die Einheiten. Sichten **referenzieren** Einheiten, kopieren nie —
jede Aussage existiert genau einmal. MECE gilt **pro Ebene innerhalb eines Typs**, nie über
Typen hinweg.

- **Kern**: wenige Sätze + die tragenden Einheiten
- **Features**: Funktionsbereiche (6–10) → Features → Teilfeatures → Einheiten-Referenzen;
  jedes Feature mit Flag `kern|rand`. Auf jeder Aufklapp-Ebene stehen 5–15 Dinge, nie 100.
- **Flows**: Titel + Beschreibung + Schrittfolge (jeder Schritt → Einheiten)
- **Architektur**: Komponenten (jede Komponente → Einheiten), Beziehungen aus den Kanten

### 3. Entscheidungen — *warum es so ist*

Decision Records in `.planer/entscheidungen/`, eine Datei pro Entscheidung: Frage, Kontext,
Optionen, Wahl, Begründung, betroffene Einheiten/Artefakte. Entstehen aus Eskalationen und
strategischen Weichenstellungen. Fließen als Kontext in künftige Aufgaben, deren
Einheiten/Thema sie berühren — Filter und Verifizierer prüfen auch dagegen. Effekt: die
Eskalationsrate sinkt über die Zeit von selbst.

### Weitere Dateien

- `.planer/pruefung.md` — Prüf-/Betriebsanleitung des Projekts: Build-, Test-, Lint- und
  Start-Kommandos, bekannte Eigenheiten. Wird beim Scan erfasst; Voraussetzung für die
  mechanischen Gates und den Verifizierer. Fehlen Tests, degradiert das Gate **sichtbar**
  („keine Tests vorhanden"), nie still.
- `.planer/strategie/<name>.md` — benannte Soll-Entwürfe (siehe Strategie-Bereich)
- `.planer/ideen.md` — Ideen-Backlog, wird im Jour Fixe wieder aufgelegt
- `.planer/jourfixe/` — Kurzprotokolle der Sitzungen (Anknüpfpunkt für die nächste)

---

## Scan & Drift

- **Erst-Scan**: Voll-Analyse des Repos → Einheiten schneiden → Fakten + Kanten extrahieren
  → Sichten aggregieren (Barriere: braucht alle Einheiten) → QA. Läuft als Kanban-Board.
- **Re-Scan**: `git diff` seit dem letzten Scan gegen die Anker → nur berührte Einheiten
  neu prüfen → nur Artefakte prüfen, die diese Einheiten referenzieren. Billig.
- **Qualitätssicherung zweistufig**: mechanische Gates zuerst und tokenfrei (existiert der
  Anker? steht an der Stelle dieser Code? Abdeckung?), LLM-Judge nur für Semantik (stimmt
  Beschreibung, sind Fakten korrekt gefolgert). Dadurch ist MiniMax als Scan-Generator gut
  abgesichert.
- **Drift-Anzeige**: veraltete Artefakte tragen ein Badge mit Re-Scan-Knopf; Drift-Ampel
  je Projekt auf der Startseite.

---

## Der Änderungs-Kreislauf (Kern-Flow)

```
Ich entscheide (Strategie / Jour Fixe / Chatbox)
  → bestätigter Soll-Diff (Artefakt-Ebene: Features neu/geändert/entfernt)
  → Plan-Agent zerlegt in kleine Aufgaben (Schnittgrenze = Einheiten,
    prüfbares Fertig-Kriterium, relevante Decision Records angehängt)
  → Team-Board arbeitet ab (siehe unten), Eskalationen landen bei mir
  → Integrations-Verifikation gegen den urspr. Soll-Diff
    (fängt Zerlegungsfehler, die Einzel-Verifizierer nicht sehen)
  → Artefakt-Sync (Re-Scan des Diffs, Einheiten + Sichten aktualisieren)
  → Commit (Code + Artefakte atomar), Anker auf neuen Commit-Hash
```

Scan, Board und Sync arbeiten **nur auf sauberem Working Tree** — uncommittete Änderungen
im Projekt = Abbruch mit Meldung, sonst vermischen sich Agenten-Diffs mit Handarbeit und
der Anker-Commit stimmt nicht mehr.

Der Commit passiert **immer erst nach dem Artefakt-Sync** — sonst bricht „der Planer hat
die Wahrheit" bei jeder Änderung. Änderungen über den Planer halten die Artefakte per
Konstruktion aktuell; der Drift-Check ist nur das Netz für Änderungen daran vorbei
(die dank Artefakten im Repo + Projekt-Skill ebenfalls mitpflegen können).

## Team-Board (Ausführung)

Kanban-Board (Engine aus dem Creator): Karten = Aufgaben, Stufen:

1. **Umsetzer** ändert Code für genau seine Aufgabe
2. **Mechanische Gates** (tokenfrei, Kommandos aus `.planer/pruefung.md`): Tests grün,
   Lint/Format, Diff berührt nur die Einheiten der Aufgabe (Scope-Creep-Check),
   Diff-Größe plausibel
3. **LLM-Stil-Filter** (je eigene Rolle, billige Modelle): kein Aufblähen, minimale
   Änderung, voller Umfang der Aufgabe — *erst ab v2, wenn Telemetrie zeigt, welche*
4. **Verifizierer** (starkes Modell, frischer Kontext — nie der Umsetzer-Kontext): führt
   aus/testet, prüft Verhalten gegen Aufgabe + Soll-Artefakte + Decision Records

Regeln:
- **Ablehnung** → Befunde-Liste zurück an den Umsetzer (Repair-Muster: Befunde gezielt
  abarbeiten, nicht neu würfeln). **Max 2 Runden**, dann Eskalation (Kostenschutz).
- **Fehlende Info/Entscheidung** = sofortige Eskalation, ohne Rate-Runden.
- **Eskalationen kommen entscheidungsreif** an: Blocker + 2–3 Optionen mit Trade-offs +
  Empfehlung. Meine Antwort wird automatisch Decision Record, die Karte läuft damit weiter.
- Aufgaben mit **disjunkten Einheiten dürfen parallel** laufen (ab v2; v1 sequenziell).
- Filter, die wiederholt ablehnen, was ich durchwinke → Prompt schärfen statt mehr Runden
  (Judges rauschen — Creator-Lehre).

## Gesprächsmodi (vier, klar getrennt)

| Modus | Zweck | Ergebnis fließt in |
|---|---|---|
| **Chatbox** | jetzt ändern: Änderung beschreiben → Soll-Diff-Vorschau in den Artefakten → bestätigen → Board | Auftrag |
| **Strategie** | Zukunft entwerfen: mit Agent (`stratege`) Soll-Entwürfe ausarbeiten; Live-Vorschau = Feature-Baum mit neu/geändert/entfernt-Badges; mehrere benannte Szenarien, reifen über Sitzungen | etappenweise Soll-Diffs (Roadmap), Decision Records |
| **Jour Fixe** | rückblickend verbessern: Agent (`berater`) eröffnet datenbasiert (Agenda aus Telemetrie: Eskalationen/Runden, Drift, Kosten, Ideen-Backlog) | Aufträge, Decision Records, `ideen.md`, Protokoll |
| **Eskalation** | blockierte Entscheidung aus dem Board | Decision Record, Karte läuft weiter |

Chatbox und Strategie sind technisch **eine Komponente in zwei Modi** (sofort ausführen
vs. Entwurf pflegen) — gleiche Diff-Engine, gleiche Vorschau.

## Rollen & Modelle

Zentrale Rollen-Tabelle (einzige Stelle mit Modellnamen), per UI-Switch gesetzt, Override
pro Lauf möglich. Rollen mindestens: `scan-schneiden`, `fakten`, `judge`, `plan`,
`umsetzer`, `stil-filter-*`, `verifizierer`, `integrations-verifizierer`, `executor`,
`chat`, `stratege`, `berater`.

- **Start-Belegung: ALLE Rollen auf MiniMax** (der Betreiber hat dort viele Tokens zum
  Testen). Claude kommt nur in eine Rolle, wenn der Betreiber sie bewusst umschaltet.
- Erwartung aus Phase 0: Für Plan/Verifizierer/Stratege/Berater wird sich ein stärkeres
  Modell lohnen — aber der Wechsel passiert datenbasiert per Telemetrie, nicht vorab.
- Vor jedem Lauf zeigt die UI die komplette Rollen-Belegung zum Bestätigen; jeder laufende
  Agent zeigt sein Modell

## Telemetrie (Planer-DB, nicht Repo)

- Je Call: Rolle, Modell, Provider, Tokens rein/raus, Dauer, Status, Projekt, Karte, Stufe
- Je Aufgabe: Runden, Filter-/Verifizierer-Urteile mit Grund, eskaliert + Grund
- Je Eskalation: meine Entscheidung (Muster-Erkennung: gleiche Frage-Kategorie mehrfach →
  Kandidat für Decision Record/Regel)
- Agent-Transkripte je Lauf aufbewahren (prunebar) — Urteile müssen nachlesbar sein
- Zweck: datenbasierte Modellwahl je Rolle („MiniMax 1,6 Runden vs. Sonnet 1,1 bei 40 %
  der Kosten"), Filter-Tuning, Kosten-Dashboard, Jour-Fixe-Agenda

## UI

- **Startseite = Geschäftsführer-Schreibtisch** (Orchestrieren): oben Entscheidungsliste
  (Eskalationen, entscheidungsreif), darunter laufende Aufträge über alle Projekte
  (Fortschritt, Modelle, Token), darunter Projektliste mit Drift-Ampel und letztem Scan.
- **Projektansicht** (Verstehen): Einstieg über den Kern, aufklappbare Hierarchie
  Funktionsbereiche → Features → Teilfeatures → Einheiten (Fakten, Anker); Tabs für Flows,
  Architektur, Entscheidungen; Drift-Badges inline mit Re-Scan-Knopf.
- **Doku-Sicht** (Wiedereinlesen): Lesemodus derselben Daten in Einlese-Reihenfolge
  (Kern → Architektur → Bereiche in Abhängigkeitsreihenfolge aus den Kanten). Reine Sicht,
  keine eigenen Inhalte — kann nie veralten.
- **Chatbox** in der Projektansicht; Soll-Diff-Vorschau direkt in den Artefakten.
- **Strategie-Bereich**: Chat links, Feature-Baum mit Live-Änderungs-Badges in der Mitte.
- **Rechte Seitenleiste**: Live-Status des Boards (Karten je Stufe, aktive Agenten mit
  Modell/Laufzeit, Befunde); Eskalationen erscheinen hier UND auf der Startseite.

## Verwendete Systeme

Bewusst der Creator-Stack — der Planer unterscheidet sich durch sein Konzept, nicht durch
seine Technik; neue Technologie wäre Lernaufwand an der falschen Stelle.

- **Backend**: Python, FastAPI, uvicorn, aiosqlite — gesetzt durch die Wiederverwendung
  von `kanban.py`/`agents.py`; Fake-Agenten-Ansatz für Tests übernehmen.
- **LLM-Anbindung**: CLI-Subprozesse, keine direkten APIs. `claude`-CLI (läuft über das
  Abo via OAuth-Token — die Anthropic-API würde separat kosten), `opencode`-CLI für
  MiniMax. Der Executor ist dieselbe Claude-CLI headless (`claude -p`).
- **Frontend**: Vue 3 + Vite, ohne UI-Framework (Muster für Live-Fortschritt, laufende
  Agenten, Dark Mode aus dem Creator kopieren; `marked` fürs Artefakt-Rendering).
  Komponentenbibliothek erst, wenn konkret etwas fehlt.
- **Daten**: SQLite nur für Betrieb (Telemetrie, Karten, Lauf-Zustand — wegwerfbar).
  Artefakte als Markdown mit YAML-Frontmatter in `.planer/` (menschenlesbar, parsebar,
  diff-freundlich; Format-Details in Phase 0).
- **Git**: nackte git-CLI + Worktrees für den Executor, keine Bibliothek.
- **Deployment**: Makefile lokal, Docker optional für den Server (Setup vom Creator).
- **Projekt-Verortung**: Projekte bleiben, wo sie sind (z. B. `~/projects/*`) — der Planer
  hält nur eine konfigurierte Pfadliste, kein Unterordner-Zwang.

## Spiel-Verpackung (reine Präsentationsschicht)

Umschaltbarer Skin über derselben UI und denselben Daten — **keine eigene Mechanik, keine
Punkte/Levels/Achievements** (Goodhart-Gefahr, verletzt Messinvarianz). Metaphern sind 1:1
isomorph zur Realität:
- Budget = echte Token-Kosten (einziges festes „Spielsystem", weil real)
- Einstellen = Rollen-Tabelle („teurer Senior Fable oder Junior M2.7?"),
  Leistungsbeurteilung = Telemetrie je Modell
- Personas mit festen Namen je Rolle (macht Logs/Seitenleiste lesbarer)
- Werkbank = Chatbox, Vorstandsklausur = Strategie, Quartalsgespräch = Jour Fixe,
  Posteingang = Eskalationen, Abteilungen = Projekte

---

## Dogfooding: der Planer ist das erste Projekt des Systems

Der Planer verwaltet sich selbst — gestaffelt, um das Henne-Ei-Problem zu umgehen:

- **Phase 0 validiert am Creator** (der Planer hat noch keinen Code; der Scan muss sich an
  einem großen, gewachsenen Repo beweisen).
- **Ab Phase 1** ist der Planer erstes gescanntes Projekt: Er scannt sich selbst, die
  Artefakte werden gegen diese README geprüft — Abweichung heißt Scan schlecht ODER Plan
  veraltet, beides will man wissen. Die `.planer/`-Artefakte wachsen ab Commit eins mit
  (Soll-first: die Feature-Sicht kann aus dieser README abgeleitet werden, bevor der Code
  existiert).
- **Ab Phase 3** laufen Änderungen am Planer durch den Planer selbst.

**Regel für Selbst-Änderungen** (Creator-Lehre „kein Backend-Edit bei laufendem Flow"):
Der Executor arbeitet immer in einem Worktree/Branch — nie im laufenden Checkout. Gemergt
und neu gestartet wird erst, wenn das Board durch ist; sonst killt der Server-Reload die
eigenen Läufe.

## Implementierungsphasen

Jede Phase liefert eigenständigen Nutzen. Erst abhaken, dann weiter.

### Phase 0 — Scan validieren (kein App-Code) ✅ (2026-07-09)
Die einzige Komponente ohne Creator-Präzedenzfall ist die Scan-Qualität. Alles steht auf ihr.
- [x] `.planer/`-Dateiformat definieren (Einheiten, Sichten — Markdown/YAML) → `docs/format.md`
- [x] Scan-Prompts von Hand am Creator-Repo ausprobieren (MiniMax) → `phase0/` (Prompts, Beispiele)
- [x] Mechanische Prüfskripte: Anker-Existenz, Zitat-Treue → `phase0/pruefe.py`
- [x] Bewerten → mechanisch bestanden (M3: 0 Fehler nach Nachfass; Feature-Sicht: 0 kaputte
      Referenzen). Nutzer-Urteil zur Lesbarkeit folgt im echten Viewer (Phase 2).
      Alle Befunde: `phase0/erkenntnisse.md` (13 Erkenntnisse, u. a. M3 statt M2.7-HS,
      Chunking-Pflicht, Stagger-Sperre, Infra-Fehlerklassen)

### Phase 1 — Scan-Pipeline ✅ (2026-07-09)
- [x] Kanban-Engine + Provider-Layer aus dem Creator übernehmen (Fallback entfernen!)
- [x] Rollen-Tabelle als Config, harter Stopp bei unkonfigurierter Rolle
- [x] Fake-Agenten von Anfang an (Creator-Muster) — Pipeline ohne LLM in Sekunden testbar
- [x] Scan-Board: schneiden → Fakten/Kanten → Sichten (Barriere) → mechanische Gates → Judge
- [x] Scan erfasst `.planer/pruefung.md` (Build/Test/Start-Kommandos je Projekt)
- [x] Scan-Ausschlussliste (`.env`, `node_modules`, Build-Artefakte …)
- [x] Re-Scan über git-Diff gegen Anker, Rename/Move-Matching
- [x] Events-Telemetrie von Anfang an
- [x] An eigenen Projekten laufen lassen (creator-Abnahme bestanden; weitere bei Bedarf)
- [x] Dogfooding: Planer scannt sich selbst — abgehakt auf Nutzer-Entscheid; Lauf folgt nach erstem Commit

### Phase 2 — Viewer
- [ ] Startseite: Projektliste mit Drift-Ampel, Scan/Re-Scan auslösbar
- [ ] Projektansicht: Kern, aufklappbare Feature-Hierarchie, Tabs Flows/Architektur/Entscheidungen
- [ ] Doku-Sicht (Leseordnung aus Kanten)
- [ ] Rechte Seitenleiste: laufende Scans live

### Phase 3 — Ändern (der Kern-Kreislauf)
- [ ] Chatbox: Beschreibung → Soll-Diff-Vorschau in den Artefakten → bestätigen
- [ ] Plan-Rolle: Zerlegung in Aufgaben entlang der Einheiten, Decision Records anhängen
- [ ] Team-Board v1: Umsetzer → mechanische Gates → 1 Verifizierer; sequenziell; 2-Runden-Deckel
- [ ] Eskalation v1: Karte pausiert, Antwort im Chat, wird Decision Record
- [ ] Integrations-Verifikation → Artefakt-Sync → Commit durch den Agenten
- [ ] Fake-E2E: kompletter Änderungs-Kreislauf (Soll-Diff → Board → Sync → Commit) ohne
      LLM in Sekunden, an einem Test-Repo
- [ ] Executor-Rolle delegiert (Claude Code headless), Schnittstelle: Auftrag + Kontext rein, Diff raus;
      arbeitet immer im Worktree/Branch (Selbst-Änderungs-Regel)
- [ ] Dogfooding: Änderungen am Planer laufen ab jetzt durch den Planer selbst

### Phase 4 — Orchestrieren
- [ ] Startseite zum Schreibtisch ausbauen: Entscheidungsliste, laufende Aufträge
- [ ] Entscheidungsreife Eskalationen (Optionen + Empfehlung, Klick-Entscheidung)
- [ ] Kosten-Dashboard (Tokens je Rolle/Projekt/Woche)
- [ ] Parallele Aufgaben über disjunkte Einheiten

### Phase 5 — Strategie & Jour Fixe
- [ ] Strategie-Modus der Chat-Komponente: benannte Entwürfe, Live-Feature-Baum, Roadmap-Abfluss
- [ ] Jour Fixe: datenbasierte Agenda aus Telemetrie, Protokoll, Ideen-Backlog
- [ ] LLM-Stil-Filter gezielt nachrüsten (nur was die Telemetrie als Lücke zeigt)

### Phase 6 — Politur
- [ ] Spiel-Skin (Personas, Budget, Benennungen; umschaltbar)
- [ ] Projektübergreifender Jour Fixe (Muster über alle Projekte)
- [ ] Lokale LLMs als Provider (wenn gebraucht)

---

## Offene Fragen (bei Phase 0/1 klären)

- Genaues Dateiformat der Einheiten/Sichten (Lesbarkeit vs. maschinelle Diff-Freundlichkeit)
- Rename/Move-Matching: wie viel Aufwand lohnt v1?
- Wie viel Kontext bekommt der Umsetzer (nur Aufgabe + Einheiten, oder mehr)?
