| # megaHarness — Architektur-Plan |
|
|
| **Status:** Architektur-Lock für 5-Tage-MVP (2026-04-23 → 2026-04-28) |
| **Autor:** Samuel (Vision) + Claude/Opus 4.7 (Architektur-Synthese) |
| **Basis-Dokumente:** `idea` (Vision), `HarnessEcosystem/docs/gpt5-4-shift-report.md` (empirische Rechtfertigung) |
|
|
| --- |
|
|
| ## 0. North Star |
|
|
| megaHarness ist Samuels persönliches **Meta-Harness**: eine Schicht **über** existierenden Agent-Harnesses (Claude Code, OpenClaude, Codex, OpenHands, Cursor, …), die sie als austauschbare Execution-Engines orchestriert. Der Wert liegt nicht in einem neuen Agent, sondern in **Komposition**: gleiche Task läuft auf anderem Harness + anderem Modell, ohne Re-Konfiguration. |
|
|
| Die acht Prinzipien aus `idea` sind nicht verhandelbar. Alles andere ist Implementierungsdetail. |
|
|
| --- |
|
|
| ## 1. Architektur in Schichten |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ L4 — UI-Layer │ |
| │ Dashboard · Track-Viewer · MD-DB-Browser · Eval-Viewer │ |
| ├─────────────────────────────────────────────────────────────┤ |
| │ L3 — Kernel (megaHarness-Core) │ |
| │ Task-Router · Parallel-Orchestrator · Sidecar-Engine │ |
| │ Eval-Engine · MD-Resolver · Harness-Swap │ |
| ├─────────────────────────────────────────────────────────────┤ |
| │ L2 — MD-Datenbank (Source of Truth) │ |
| │ projects/ · instructions/ · skills/ · tracks/ · evals/ │ |
| ├─────────────────────────────────────────────────────────────┤ |
| │ L1 — Harness-Adapter-Layer │ |
| │ Claude-Code · OpenClaude · Codex · OpenHands · Hermes │ |
| ├─────────────────────────────────────────────────────────────┤ |
| │ L0 — Provider-Layer (extern, nicht megaHarness) │ |
| │ Anthropic · OpenAI · Google · MiniMax · lokale Modelle │ |
| └─────────────────────────────────────────────────────────────┘ |
| ``` |
|
|
| **Kern-Invariante:** L3 kennt L1 nur durch Adapter-Interface, L2 nur durch Resolver-Interface, L0 nie direkt. So wird Modell-Swap und Harness-Swap zur Config-Änderung, nicht zum Refactor. |
|
|
| --- |
|
|
| ## 2. Kern-Komponenten |
|
|
| ### 2.1 MD-Datenbank (L2) |
|
|
| **Rolle:** Einzige Quelle der Wahrheit für alle adaptiven Verträge. |
|
|
| **Entitäten:** |
| - `projects/*.md` — Projekt-Briefs, Done-Kriterien, Scope-Locks |
| - `instructions/*.md` — CLAUDE.md-Äquivalente, per Harness + Modell versioniert |
| - `skills/*.md` — wiederverwendbare Skill-Definitionen |
| - `sidecar/*.md` — Regelwerke (ADHS-Hooks, Scope-Guards, Commit-Gates) |
| - `tracks/*.md` — Live-Track-Definitionen (Task, Harness, Modell, Budget, Done) |
| - `evals/*.jsonl` — Eval-Läufe, append-only |
|
|
| **Adaptivität:** jedes MD-File hat Frontmatter mit `applies_when:`-Clauses (Harness-ID, Modell-ID, Projekt-ID, Session-Phase). Der **MD-Resolver** (L3) wählt zur Laufzeit das relevante Subset. Nicht-adaptive .md-Files sind Legacy-Schicht. |
|
|
| **Warum Markdown + Frontmatter, nicht SQLite/Postgres:** |
| - Menschenlesbar, Git-diffbar |
| - LLM-nativ (kein Query-Layer nötig für Konsumption) |
| - Versionierbar mit dem Repo |
| - Zero Infrastruktur, keine Migrations-Drama |
|
|
| **Trade-off:** keine komplexen Joins, keine Transaktionen. Für diesen Use-Case egal. |
|
|
| ### 2.2 Harness-Adapter-Protokoll (L1↔L3-Vertrag) |
|
|
| Jeder Harness-Adapter implementiert ein minimales Interface: |
|
|
| | Method | Zweck | |
| |---|---| |
| | `spawn(track_md)` | Starte Session aus Track-MD | |
| | `status(session_id)` | Lebens-Check, Tokens, Turn-Count | |
| | `interrupt(session_id)` | Hartes Stop | |
| | `collect(session_id)` | Transcript + Metriken holen | |
| | `capabilities()` | Was kann der Harness (Tools, Background, Worktrees) | |
|
|
| **Completion-Contract:** jeder Spawn bekommt aus der MD-DB eine explizite `done_when:`-Clause injiziert. Harnesses ohne native Contract-Unterstützung (GPT-5.4 im Claude-Code-Harness: siehe Shift-Report) kriegen einen Wrapper-Prompt, der die Clause als System-Message voranstellt. |
|
|
| **Der Harness-Swap-Moment:** Swap = Track-MD unverändert lassen, nur `harness_id:` im Frontmatter ändern. Re-Spawn. Der Kernel liefert dieselben Inputs. |
|
|
| ### 2.3 Task-Router (L3) |
|
|
| **Input:** Task-Request (aus UI, CLI, Cron oder Eval-Trigger) |
| **Output:** Track-MD + Harness-Auswahl |
|
|
| **Routing-Logik:** |
| 1. Matching: welche Harnesses + Modelle sind kompatibel mit Task-Typ |
| 2. Policy: Default-Modell pro Task-Typ aus `instructions/router-policy.md` |
| 3. Override: explizite User-Wahl schlägt Policy |
| 4. Fallback: wenn Primär-Harness unavailable, Sekundär aus Policy |
|
|
| **Empirisch kalibriert:** Shift-Report zeigt, dass GPT-5.4 im Claude-Code-Harness 2–8M Input-Tokens pro Session verbrennt. Router-Policy verhindert diese Kombination by default, es sei denn explizit als Experiment deklariert. |
|
|
| ### 2.4 Parallel-Orchestrator (L3) |
|
|
| **Rolle:** N Tracks gleichzeitig, keine Race Conditions im Dateisystem, Checkpoint-fähig. |
|
|
| **Mechanismen:** |
| - Git-Worktree pro Track (Isolation auf Repo-Ebene) |
| - tmux/supervisord für Prozess-Leben (keine eigene Prozess-Verwaltung bauen) |
| - MD-Queue für Track-Slots (`tracks/active/`, `tracks/queued/`, `tracks/done/`, `tracks/failed/`) |
| - Heartbeat-File pro Track für Status-Polling |
|
|
| **Kapazität:** 3–5 Tracks parallel. Mehr ist Token-Verbrennung ohne Kognitions-Nutzen (Samuel kann nicht 8 parallel reviewen). |
|
|
| ### 2.5 Sidecar-Engine (L3) |
|
|
| **Rolle:** Samuel-spezifische Kalibrierung — ADHS-Guards, Scope-Warnungen, Commit-Gates. |
|
|
| **Baut auf:** existierendem `Sidecar-ng`-Projekt (bereits produktiv, liefert die Hook-Payloads die dieser Dialog durchgehend zeigt). |
|
|
| **Integration:** Sidecar-Engine ist **kein neuer Code**, sondern ein Adapter der existierende Sidecar-NG-Events an die MD-DB und den Orchestrator sendet. Regeln kommen aus `sidecar/*.md`. |
|
|
| **Kernfunktion für megaHarness:** Cross-Track-Scope-Guard. Wenn Track A in `home/` arbeitet und Track B plötzlich auch: Flag. |
|
|
| ### 2.6 Eval-Engine (L3) |
|
|
| **Rolle:** jeder Track misst sich selbst. |
|
|
| **Baut auf:** existierendem `HarnessEcosystem/sidebyside` (liefert bereits snapshot-basierte Vergleiche, siehe Shift-Report). |
|
|
| **Metriken pro Track:** |
| - Token-Effizienz (in/out, pro Turn) |
| - Tool-Burst-Dichte (Tool-Calls pro Turn) |
| - Contract-Adhärenz (Done-Clause erreicht?) |
| - Termination-Typ (clean / limit / interrupt / crash) |
| - Outcome-Label (manuell oder durch Review-Track) |
|
|
| **Feedback-Loop:** Eval-Ergebnisse schreiben zurück nach `evals/*.jsonl`. Router-Policy konsumiert aggregierte Evals → empirische Modell-Auswahl. |
|
|
| ### 2.7 UI-Layer (L4) |
|
|
| **Kern-Views:** |
| 1. Track-Dashboard (welche Tracks laufen, Status, ETA, Tokens) |
| 2. MD-DB-Browser (Navigation + Diff) |
| 3. Eval-Viewer (Baut auf `frontier-llm-harness`-Ästhetik auf) |
| 4. Spawn-Composer (Track-MD erstellen → Router → Adapter) |
|
|
| **Technologie-Entscheidung:** statische SPA + lokaler HTTP-Server, liest direkt aus `tracks/` + `evals/`. Kein Backend. Grund: `sidebyside` + `frontier-llm-harness` haben das Pattern bereits bewiesen, keine neue Infrastruktur. |
|
|
| **Live-Updates:** Polling (nicht WebSocket). KISS. |
|
|
| --- |
|
|
| ## 3. Bausteine-Map (Was existiert, was fehlt) |
|
|
| | Schicht / Komponente | Existierend (✓) / Fehlt (✗) | Quelle | |
| |---|---|---| |
| | L2 MD-DB Schema | ✗ | — | |
| | L2 MD-Resolver | ✗ | — | |
| | L2 Adaptive Regeln existierend | (✓) teilweise | PromptGarage, Skills | |
| | L1 Claude Code Adapter | (✓) implizit (JSONL-Logs) | `~/.claude/projects/` | |
| | L1 Codex/GPT-5.4 Adapter | (✓) implizit | `extract_codex.py` | |
| | L1 OpenClaude Adapter | ✗ | Fork existiert, kein Adapter | |
| | L1 Hermes Adapter | (✓) teilweise | `extract_hermes.py` | |
| | L1 OpenHands Adapter | ✗ | — | |
| | L3 Harness-Swap Mechanik | (in Arbeit) | `derWolfimSchafspelz/openclaude` | |
| | L3 Task-Router | ✗ | — | |
| | L3 Parallel-Orchestrator | ✗ | — | |
| | L3 Sidecar-Engine | ✓ | `Sidecar-ng` | |
| | L3 Eval-Engine | ✓ | `HarnessEcosystem/sidebyside` | |
| | L4 Dashboard | (✓) Aesthetik + Pattern | `SidecarDashboard`, `KomandoZentral`, `frontier-llm-harness` | |
|
|
| **Schlüssel-Erkenntnis:** L2 (MD-DB) ist der kritische neue Baustein. L3-Kernel ist dünne Integration existierender Teile. L1-Adapter sind jeweils 1–2 Tage Arbeit, wir brauchen in 5 Tagen nur 2–3. |
|
|
| --- |
|
|
| ## 4. Harness-Swap — der aktuelle Build |
|
|
| **Definition:** Harness-Swap ist der Mechanismus, der denselben Task auf einem anderen Harness re-exekutiert, ohne Task-Definition zu ändern. |
|
|
| **Architekturrolle:** Harness-Swap ist **nicht** ein L1-Adapter. Es ist ein L3-Kernel-Feature, das L1-Adapter koordiniert. |
|
|
| **Interface:** |
| ``` |
| swap(track_id, from_harness, to_harness) → |
| 1. collect(from_harness.session) → transcript + state |
| 2. translate(state, to_harness.capabilities) → new_state |
| 3. track_md.harness_id = to_harness |
| 4. spawn(to_harness, track_md, continuation=new_state) |
| ``` |
|
|
| **State-Translation-Regeln** sind in `instructions/harness-translation-*.md` abgelegt (eine Datei pro Harness-Paar). Diese Regeln sind **adaptiv** — sie werden basierend auf Eval-Daten (was hat funktioniert beim letzten Swap?) fortgeschrieben. |
|
|
| **MVP-Umfang:** Claude Code ↔ OpenClaude Swap. Alles andere Post-MVP. |
|
|
| --- |
|
|
| ## 5. Datenfluss — der eine zentrale Loop |
|
|
| ``` |
| User-Intent |
| ↓ |
| MD-Resolver liest projects/ + instructions/ |
| ↓ |
| Task-Router wählt Harness + Modell (Policy + Eval-History) |
| ↓ |
| Track-MD geschrieben in tracks/active/ |
| ↓ |
| Parallel-Orchestrator spawnt via L1-Adapter |
| ↓ |
| Harness läuft (mit Completion-Contract injiziert) |
| ↓ |
| Sidecar-Engine beobachtet, flagt bei Regel-Verletzung |
| ↓ |
| Abschluss: Eval-Engine schreibt nach evals/*.jsonl |
| ↓ |
| Track-MD nach tracks/done/ verschoben |
| ↓ |
| UI reflektiert neuen Zustand |
| ↓ |
| Router-Policy lernt aus evals/ für nächsten Spawn |
| ``` |
|
|
| Dieser Loop ist das System. Alles andere ist Verzierung. |
|
|
| --- |
|
|
| ## 6. 5-Tage-Meilensteine (architektonisch) |
|
|
| Jeder Meilenstein hat **eine binäre Done-Frage**, nicht eine Feature-Liste. |
|
|
| ### Tag 1 — Fundament (2026-04-23) |
| **Done-Frage:** Existiert `md-db/` mit Schema-definierten Frontmatter-Keys, und kann der MD-Resolver aus einer `tracks/example.md` eine zusammengesetzte Instruction produzieren? |
| - MD-DB-Schema finalisiert (Frontmatter-Felder, Ordner-Layout) |
| - MD-Resolver als dünner Layer |
| - Ein Beispiel-Track in der DB abgelegt |
| - **Non-Goal Tag 1:** kein Spawn, keine UI, kein Router |
|
|
| ### Tag 2 — Execution (2026-04-24) |
| **Done-Frage:** Kann ein Track-MD via Adapter einen Claude-Code-Subprozess spawnen, laufen lassen, und das Transcript ingesten? |
| - L1-Adapter: Claude Code (via CLI-Spawn) |
| - L1-Adapter: OpenClaude (via Fork-CLI) |
| - L3 Spawn-Funktion im Kernel |
| - **Non-Goal:** kein Parallelismus, kein Swap, kein Router |
|
|
| ### Tag 3 — Parallelität + Router (2026-04-25) |
| **Done-Frage:** Laufen 3 Tracks gleichzeitig in Worktrees, ohne dass sie sich im Dateisystem zerstören, und wählt der Router automatisch Harness+Modell aus der Policy? |
| - Parallel-Orchestrator mit Worktree-Isolation |
| - Task-Router mit statischer Policy (Eval-Feedback Post-MVP) |
| - Heartbeat + Status-Polling |
| - **Non-Goal:** UI, Swap |
|
|
| ### Tag 4 — Swap + Eval-Integration (2026-04-26) |
| **Done-Frage:** Kann ein laufender Track von Claude Code nach OpenClaude geswapt werden, und schreibt der Eval-Hook nach Abschluss saubere Metriken in `evals/`? |
| - Harness-Swap (MVP: Claude Code ↔ OpenClaude) |
| - Eval-Engine-Hook an Adapter-Collection angebunden |
| - `sidebyside`-Scripts als Eval-Konsumenten integriert |
| - **Non-Goal:** UI, Router-Lernen aus Evals |
|
|
| ### Tag 5 — UI + E2E (2026-04-27, Puffer 2026-04-28) |
| **Done-Frage:** Sieht Samuel im Browser ein Track-Dashboard, kann er einen neuen Track spawnen und das Ergebnis inklusive Evals einsehen? |
| - Statische SPA mit Track-Dashboard + MD-DB-Browser + Eval-Viewer |
| - Spawn-Composer (einfache Form, kein Advanced) |
| - Ein echter E2E-Run: Spawn → Parallel → Swap → Eval → UI |
| - Puffer-Tag (28.04) für Polish und unerwartete Blocker |
|
|
| --- |
|
|
| ## 7. Risiken & Mitigationen |
|
|
| | Risiko | Wahrscheinlichkeit | Impact | Mitigation | |
| |---|---|---|---| |
| | Scope-Creep über MVP hinaus | Hoch | Hoch | Jeder Tag hat eine binäre Done-Frage, nicht Feature-Liste. Post-MVP-Liste explizit in §9. | |
| | GPT-5.4 im Claude-Code-Harness verbrennt Token-Budget | Hoch | Mittel | Router-Policy verhindert Kombination by default. Nur als explizites Experiment. Empirisch belegt durch Shift-Report. | |
| | UI-Tag-5 wird zum Zeitfresser | Hoch | Hoch | Statische SPA, keine neue Infrastruktur. `frontier-llm-harness` als Muster. Kein Framework-Neuwahl. | |
| | MD-DB-Schema wird zu komplex | Mittel | Hoch | Schema ≤ 10 Frontmatter-Keys im MVP. Erweiterung nur mit belegtem Use-Case. | |
| | Parallelismus zerstört Dateisystem | Mittel | Hoch | Git-Worktree pro Track. Kein Shared-State außerhalb `md-db/`. | |
| | Bestehende Projekte nicht sauber integrierbar | Mittel | Mittel | MVP nutzt nur `Sidecar-ng` und `sidebyside` als Integration. Rest Post-MVP. | |
| | 5-Tage-Schätzung zu optimistisch | Hoch | Hoch | Tag 5 hat Puffer 28.04. MVP-Scope bewusst klein. Wenn Tag 3 nicht done: Swap+Eval gehen Post-MVP. | |
| | ADHS-Fokus-Kollaps | Mittel | Hoch | Sidecar-NG aktiv, tägliche Done-Frage als Anker, keine Parallelarbeit an mehr als EINEM Kernel-Teil gleichzeitig. | |
|
|
| --- |
|
|
| ## 8. Done-Kriterien (Tag 5) |
|
|
| Der MVP ist fertig, wenn **alle** folgenden Bedingungen wahr sind: |
| 1. `md-db/` existiert mit den definierten Ordnern |
| 2. Mindestens 2 Harness-Adapter funktionieren (Claude Code, OpenClaude) |
| 3. 3 Tracks sind parallel gelaufen ohne gegenseitige Blockade |
| 4. Ein Harness-Swap wurde erfolgreich durchgeführt (Claude Code → OpenClaude) |
| 5. Mindestens ein Eval-Lauf ist in `evals/` persistent |
| 6. UI zeigt aktuelle Tracks + Evals korrekt |
| 7. Ein Ende-zu-Ende-Flow (Spawn → Parallel → Swap → Eval → UI) lief ohne manuelle Eingriffe durch |
|
|
| Wenn 5 von 7 erreicht: **MVP accepted**. Wenn weniger: MVP-Scope reevaluieren, nicht verlängern. |
|
|
| --- |
|
|
| ## 9. Non-Goals (Post-MVP, bewusst ausgeschlossen) |
|
|
| - Cursor-Adapter |
| - OpenHands-Adapter |
| - Hermes-Adapter (Collect-Script reicht) |
| - Router-Policy-Lernen aus Eval-History |
| - Advanced Spawn-Composer in UI (Form-only reicht) |
| - Fremde Repos als Tracks (nur eigene im MVP) |
| - Cloud-Deployment |
| - Multi-User |
| - Auth |
| - Mobile-UI |
| - Persistente DB (MD-Files reichen) |
| - Config-Hot-Reload |
| - Skill-Marketplace |
| - Eval-Auto-Labeling durch Review-Track |
|
|
| Jeder dieser Punkte ist ein legitimes Feature — aber nicht in 5 Tagen. |
|
|
| --- |
|
|
| ## 10. Glossar |
|
|
| - **Harness**: Ausführungsumgebung für einen Agent (Claude Code, Codex, OpenHands …) |
| - **Modell**: LLM-Endpoint (Opus, GPT-5.4, …) |
| - **Track**: Eine konkrete Task-Instanz mit Harness + Modell + Projekt-Kontext |
| - **Spawn**: Track in einem Harness starten |
| - **Swap**: Track mitten im Leben auf anderen Harness übertragen |
| - **MD-DB**: Markdown-basierte Datenbank (L2) |
| - **Completion-Contract**: Explizites `done_when:` in Track-MD |
| - **Adaptiv**: .md-File gilt nur wenn Frontmatter-`applies_when:` zur Laufzeit matcht |
|
|
| --- |
|
|
| ## 11. Offene Architektur-Fragen (vor Tag 1 zu entscheiden) |
|
|
| 1. **Kernel-Sprache:** Python (ökosystemnah zu Claude Code + Codex) vs TypeScript (näher an UI). **Empfehlung: Python**, Grund: alle existierenden Scripts (`extract_*.py`, `build_snapshot.py`) sind Python. Kein Sprach-Bruch. |
| 2. **Prozess-Modell:** tmux vs supervisord vs systemd-user. **Empfehlung: tmux**, Grund: Samuel nutzt es bereits, minimal neues Setup. |
| 3. **UI-Framework:** vanilla JS (wie `sidebyside`) vs Preact vs Svelte. **Empfehlung: vanilla**, Grund: `sidebyside` + `frontier-llm-harness` sind vanilla und lesbar. |
| 4. **MD-DB-Location:** `~/.megaharness/md-db/` vs im Repo. **Empfehlung: im Repo** (`megaHarness/md-db/`), Grund: Git-versioniert, portabel, diffbar. |
|
|
| --- |
|
|
| **Dieser Plan ist ein Vertrag zwischen Samuel und dem 5-Tage-Ich. Jede Abweichung muss als ADR (Architecture Decision Record) in `docs/adr/` dokumentiert werden — oder explizit abgelehnt und hier gestrichen. Keine stille Scope-Drift.** |
|
|
