Files

Team3 f07ef9653d init

2026-07-22 16:12:23 +02:00

19 KiB

Raw Blame History

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

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.
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.
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.
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.
Messinvarianz. Telemetrie und QA messen nur; sie sind nie Teil einer Optimierung.
Die UI zeigt, was Handlung braucht — nicht alles, was passiert. Autonome Agenten bleiben Hintergrundrauschen; nur Entscheidungen, Drift und Ergebnisse drängen sich vor.
YAGNI. Zielbild vollständig planen (dieses Dokument), aber jede Phase baut nur, was sie braucht. Wachstum gesteuert durch Telemetrie und tatsächlichen Gebrauch.
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:

Umsetzer ändert Code für genau seine Aufgabe
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
LLM-Stil-Filter (je eigene Rolle, billige Modelle): kein Aufblähen, minimale Änderung, voller Umfang der Aufgabe — erst ab v2, wenn Telemetrie zeigt, welche
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)?

19 KiB Raw Blame History Unescape Escape