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.

• .planer/-Dateiformat definieren (Einheiten, Sichten — Markdown/YAML) → docs/format.md
• Scan-Prompts von Hand am Creator-Repo ausprobieren (MiniMax) → phase0/ (Prompts, Beispiele)
• Mechanische Prüfskripte: Anker-Existenz, Zitat-Treue → phase0/pruefe.py
• 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)

• Kanban-Engine + Provider-Layer aus dem Creator übernehmen (Fallback entfernen!)
• Rollen-Tabelle als Config, harter Stopp bei unkonfigurierter Rolle
• Fake-Agenten von Anfang an (Creator-Muster) — Pipeline ohne LLM in Sekunden testbar
• Scan-Board: schneiden → Fakten/Kanten → Sichten (Barriere) → mechanische Gates → Judge
• Scan erfasst .planer/pruefung.md (Build/Test/Start-Kommandos je Projekt)
• Scan-Ausschlussliste (.env, node_modules, Build-Artefakte …)
• Re-Scan über git-Diff gegen Anker, Rename/Move-Matching
• Events-Telemetrie von Anfang an
• An eigenen Projekten laufen lassen (creator-Abnahme bestanden; weitere bei Bedarf)
• 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)?