Files
planer/README.md
2026-07-22 16:12:23 +02:00

332 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 (610) → Features → Teilfeatures → Einheiten-Referenzen;
jedes Feature mit Flag `kern|rand`. Auf jeder Aufklapp-Ebene stehen 515 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 + 23 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)?