# 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 `/.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/.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)?