{ "meta": { "stand": "2026-03-22", "version": "1.0.0" }, "hero": { "title": "Samuels AI-Werkstatt", "subtitle": "4 Harnesses. 1 Workflow. Datengetrieben.", "stats": [ { "label": "Harnesses", "value": "4" }, { "label": "Sessions", "value": "100+" }, { "label": "Stunden", "value": "50+" }, { "label": "Stand", "value": "2026-03-22" } ] }, "style_fit": { "kicker": "Welches Tool passt?", "heading": "Style-Fit Matrix", "description": "Welches Harness trifft deinen Arbeitsstil am besten — fuer jeden Task-Typ bewertet.", "task_types": [ "Greenfield Architektur", "Feature iterieren", "Bugfix isoliert", "Refactor gross", "Docs schreiben", "Codebase erkunden", "Parallele Agenten", "Interaktiv chatten", "Terminal-nah" ], "harnesses": ["Claude Code", "Hermes", "OpenCode", "Codex CLI"], "matrix": [ ["PERFEKT", "GUT", "OKAY", "MITTEL"], ["PERFEKT", "GUT", "GUT", "OKAY"], ["GUT", "GUT", "PERFEKT", "OKAY"], ["PERFEKT", "GUT", "GUT", "MITTEL"], ["GUT", "PERFEKT", "OKAY", "SCHLECHT"], ["PERFEKT", "GUT", "GUT", "MITTEL"], ["PERFEKT", "MITTEL", "GUT", "SCHLECHT"], ["PERFEKT", "GUT", "OKAY", "MITTEL"], ["GUT", "MITTEL", "MITTEL", "PERFEKT"] ], "recommendations": [ { "harness": "Claude Code", "for": "Architektur, grosse Refactors, Agenten-Workflows", "color": "teal" }, { "harness": "Hermes", "for": "Dokumentation, Research, Analyse", "color": "gold" }, { "harness": "OpenCode", "for": "Isolierte Bugs, saubere Feature-Implementierungen", "color": "green" }, { "harness": "Codex CLI", "for": "Terminal-Scripts, Batch-Ops, Shell-Automation", "color": "amber" } ] }, "harnesses": [ { "id": "claude-code", "name": "Claude Code", "tagline": "Vollstaendiges Agentic Coding Environment", "status": "aktiv", "color": "teal", "data_complete": true, "stats": [ { "label": "Sessions", "value": "100+" }, { "label": "Avg. Session", "value": "~45 min" }, { "label": "Modell", "value": "claude-opus-4-6" } ], "strengths": [ "Tiefste Codebase-Integration via LSP und Git", "Subagent-Orchestrierung fuer parallele Arbeit", "Sidecar-NG Kontext-Injektion", "MCP-Server Support", "Direkter Bash/File-Zugriff" ], "weaknesses": [ "Hoechste Kosten pro Session", "Opinionated Workflow (Claude-first)", "Kein nativer Web-Browser" ], "architecture_link": "diagrams/architecture-claude-code.html", "router_keywords": ["architektur", "system", "design", "plan", "komplex", "verstehen", "codebase", "neue idee", "greenfield", "orchestr", "analyse"], "router_reason": "Dein Architekt-Modus — Plan Mode erzwingt Denken vor Code. Teuer aber richtig wenn du verstehen willst WAS passiert.", "router_wave": "Wave 1 — Scout", "tutorial": { "quickStart": [ "Starte mit: `claude` oder `claude --plan` für Architektur-Modus", "Erste Commands: `/status`, `git status`, `Lies BACKLOG.md`", "Plan Mode aktivieren für grosse Entscheidungen", "Subagents für parallele Recherche: `run_in_background: true`", "Ergebnis als Tasksheet exportieren für nächstes Harness" ], "adhsPatterns": { "bodyDoubling": "Du bist mein virtueller Co-Worker. Ich rede mit dir während ich hacke — nicht weil ich Hilfe brauche, sondern weil Präsenz mich fokussiert. Sprich, auch wenn ich nicht direkt frage.", "dopaminTrigger": "Schnelle Wins: Cliffhanger setzen, Teilergebnisse zeigen, Checkpoint-Messages ('Session bisher: 3 Features, 2 Tests grün').", "antiParalysis": "Wenn ich feststecke: Nicht philosophieren, sondern 'Was ist die kleinste nächste Action?' stellen. Mikro-Schritte, nicht Grossvision.", "sessionRhythm": "Max 45min pro Session. Dann /compact oder neue Session. Hyperfocus ≠ Produktivität — nach 1h ohne Test → Quality Drop." }, "wellenmodus": { "role": "Scout & Orchestrator", "entry": "Wenn Task Architektur, Planung, oder grosses Refactor braucht", "exit": "Tasksheet für Hermes/Codex wenn Code gebaut werden soll" }, "handoff": { "toHermes": "Konkretes Feature mit Scope-Statement, nicht Plan", "toOpenCode": "Isolierter Bugfix mit Fehlermeldung + Expected vs Actual", "toCodex": "Refactor-Task mit Before/After-Beschreibung" }, "architektur": { "annotations": [ { "component": "CLAUDE.md", "description": "Globale + per-project Verhaltensregeln. Priorität: project > global." }, { "component": "settings.json", "description": "Modell, Permissions, Env-Variablen. settings.local.json überschreibt." }, { "component": "Hooks (5 Points)", "description": "SessionStart, UserPromptSubmit, PreToolUse (blockiert!), PostToolUse, Stop" }, { "component": "Subagents", "description": "Parallele Tasks via Task-Tool. Cost: ~$0.25/M (Haiku). vs $15/M (Opus)." }, { "component": "MCP-Server", "description": "Externe Tools: Filesystem, GitHub, Memory. Nicht für Long-Running." } ] }, "config": { "settingsKeys": [ { "key": "model", "type": "string", "default": "claude-opus-4-6", "description": "Default-Modell für Sessions" }, { "key": "permissions.allow", "type": "array", "default": "['Edit', 'Write', 'Glob', 'Grep', 'Agent', 'Bash(git*)']", "description": "Erlaubte Tools" }, { "key": "permissions.deny", "type": "array", "default": "['Bash(rm*)', 'Bash(apt*)', 'Bash(dd*)']", "description": "Verbotene Tools ( safety_gates.py)" }, { "key": "env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS", "type": "boolean", "default": "1", "description": "Aktiviert Subagent-Orchestrierung" }, { "key": "hooks.PreToolUse", "type": "array", "description": "Blocking-Hooks vor Tool-Ausführung" }, { "key": "hooks.UserPromptSubmit", "type": "array", "description": "Context-Injection vor LLM-Call (Sidecar-NG nutzt dies)" } ], "hooks": [ { "name": "SessionStart", "description": "Session-Init. Nicht blockierend. Gut für Auto-Context.", "canBlock": false }, { "name": "UserPromptSubmit", "description": "Vor LLM-Call. Kann additionalContext injizieren (Sidecar-NG).", "canBlock": false }, { "name": "PreToolUse", "description": "Vor Tool-Ausführung. BLOCKIERT Tool wenn Handler blockiert. Nutzung: safety_gates.py.", "canBlock": true }, { "name": "PostToolUse", "description": "Nach Tool-Ausführung. Für Logging, Async-Review.", "canBlock": false }, { "name": "Stop", "description": "Session-Ende. Cleanup, Final-Report.", "canBlock": false } ] }, "faq": [ { "q": "Session friert ein", "a": "ctrl+c → neu starten. Prüfe ~/claude/.claude/logs/ für Fehler." }, { "q": "Subagent antwortet nicht", "a": "60s timeout in CLAUDE.md. Prüfe seinen Output oder spawnne neuen." }, { "q": "Sidecar-Injection funktioniert nicht", "a": "Prüfe hook_inject.py läuft, additionalContext wird in PreToolUse nicht unterdrückt." }, { "q": "Context zu voll", "a": "/compact eingeben oder neue Session starten. Long-Context = Quality-Drop." }, { "q": "Hook führt nichts aus", "a": "Prüfe: 1) Hook-Pfad existiert, 2) Datei ausführbar, 3) Interpreter-Pfad in Shebang." } ] }, "powerUser": { "level2": { "title": "Config Mastery", "configHierarchy": [ { "file": "~/.claude/settings.json", "role": "Basis-Config: Modell, Permissions, Hooks. Wird versioniert." }, { "file": "~/.claude/settings.local.json", "role": "Lokale Overrides — NICHT ins Git. Für Bash(*) und sensitive Permissions." }, { "file": "~/.claude/CLAUDE.md", "role": "Globale Verhaltensregeln. Akkumulieren mit Projekt-CLAUDE.md — nicht überschreiben." }, { "file": "/CLAUDE.md", "role": "Projektspezifische Regeln. Höchste Priorität. Definiert Scope, Test-Strategie, Verbote." } ], "bashPermissions": [ { "pattern": "Bash(git*)", "meaning": "Alle git-Befehle erlaubt" }, { "pattern": "Bash(python3 /home/*)", "meaning": "python3 nur mit absolutem Pfad" }, { "pattern": "Bash(*)", "meaning": "ALLES erlaubt — nur in settings.local.json, nie in settings.json" }, { "pattern": "Bash(gh api*)", "meaning": "GitHub CLI API-Calls" }, { "pattern": "Bash(npm*)", "meaning": "Alle npm-Befehle" } ], "attentionBudget": [ { "rule": ">50 Regeln = Compliance-Drop", "detail": "Ab ~50 CLAUDE.md-Regeln sinkt die Regel-Einhaltung messbar. Weniger, schärfer ist besser." }, { "rule": "Weniger > Mehr", "detail": "Weniger Regeln, scharf formuliert > viele Regeln, weich formuliert. Jede Regel konkurriert um Kontext." }, { "rule": "CLAUDE.md ≠ Config-File", "detail": "Kein JSON, kein YAML — Aufmerksamkeitsbudget. Was nicht gelesen wird, wirkt nicht." }, { "rule": "Projekt > Global", "detail": "project/CLAUDE.md überschreibt ~/.claude/CLAUDE.md bei Konflikten. Nutze das gezielt." } ] }, "level3": { "title": "Subagent & Cost Mastery", "costTable": [ { "action": "Kurze Analyse", "cost": "<$0.05", "tip": "Unter 2min — kein Subagent nötig" }, { "action": "Codebase-Analyse (vollständig)", "cost": "~$0.20-0.50", "tip": "Sonnet-Subagent statt Opus direkt" }, { "action": "Subagent-Wave (3 Agents)", "cost": "~$0.10-0.30", "tip": "Haiku für Background-Tasks: ~$0.25/1M" }, { "action": "Session ohne Fokus (>1h)", "cost": "$1-3+", "tip": "ABBRECHEN — /compact oder neue Session" }, { "action": "Opus direkt", "cost": "~$15/1M Tokens", "tip": "Nur für Architektur — nie für Recherche" }, { "action": "Sonnet-Subagent", "cost": "~$3/1M Tokens", "tip": "5x günstiger als Opus — für Recherche + Code" } ], "subagentPatterns": [ { "pattern": "run_in_background: true — IMMER", "description": "Hauptsession muss responsive bleiben. Kein Blocking. Pflicht bei run_in_background: true." }, { "pattern": "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1", "description": "Aktiviert typisierte Subagents mit Frontmatter-Model-Override. 21 aktive Agent-Typen parallel ausführbar." }, { "pattern": "Max 2-3 parallele Sessions", "description": "Mehr als 3 parallele Claude Code Sessions = Context-Chaos + doppelte Kosten. Hard Limit." }, { "pattern": "Sonnet für Recherche, Opus für Architektur", "description": "Nie Opus für Websuche oder File-Lesen. Sonnet-Subagent reicht, spart 80% der Kosten." }, { "pattern": "Lesen vor Spawn", "description": "Erst relevante Dateien selbst lesen. Subagent soll nicht Dinge herausfinden die schon bekannt sind." }, { "pattern": "1 fehlgeschlagener Ansatz → STOPP", "description": "Nicht automatisch Ansatz 2 probieren. Samuel fragen. Zweiter autonomer Versuch löst Problem selten." } ] }, "level4": { "title": "Extension System", "extensionTypes": [ { "type": "Agent", "path": "~/.claude/agents/my-agent.md", "description": "Frontmatter mit name/model/tools/subagent_type + System-Prompt. Erbt alle aktiven Hooks." }, { "type": "Skill", "path": "~/.claude/skills/my-skill/SKILL.md", "description": "Via /my-skill getriggert. Kontext-Injektion, kein Tool. Sidecar-NG nutzt Skills über Knowledge-Base-Paths." }, { "type": "Command", "path": "~/.claude/commands/my-cmd.md", "description": "Via /my-cmd aufgerufen. Setzt Datei-Inhalt als System-Prompt. Verhält sich wie Slash-Command." }, { "type": "Hook", "path": "~/.claude/hooks/my-hook.py", "description": "Bekommt JSON via stdin (tool, input, session_id). Exit 0 = erlaubt, non-zero = geblockt (nur PreToolUse)." }, { "type": "Statusline", "path": "~/.claude/statusline.sh", "description": "Liest JSON von stdin (Context%, Token-Usage, Git-Branch, Hooks). ANSI-formatierte Ausgabe. Editierbar ohne Neustart." } ], "hookDeepDive": [ { "name": "PreToolUse", "blocking": true, "knownBug": false, "detail": "Einzigartig: blockt Tool-Ausführung physisch. Kein anderer Harness hat das. Hook entscheidet ob Tool läuft.", "workaround": null }, { "name": "UserPromptSubmit", "blocking": false, "knownBug": false, "detail": "additionalContext-Injection vor LLM-Call. Sidecar-NG nutzt diesen Hook für Prompt-Klassifikation.", "workaround": null }, { "name": "SessionStart", "blocking": false, "knownBug": true, "detail": "Bug #13650: additionalContext wird verworfen. Hook läuft, aber Injection landet nicht beim LLM.", "workaround": "Injection über UserPromptSubmit statt SessionStart" }, { "name": "Hook-Inheritance", "blocking": false, "knownBug": false, "detail": "Subagents erben ALLE Hooks — kein differenziertes Gate pro Agent möglich. Known Limitation.", "workaround": "Matcher in PreToolUse einschränken, z.B. nur auf Agent-Tool" }, { "name": "Hook-Restart Required", "blocking": false, "knownBug": false, "detail": "Hook-Änderungen in settings.json erfordern Session-Neustart. Kein Hot-Reload.", "workaround": "Hook-Script selbst kann ohne Neustart editiert werden — nur settings.json-Änderungen erfordern Neustart" } ], "activeHooks": [ { "name": "enforce-background-agents.py", "hook": "PreToolUse → Agent", "function": "Blockt Agent-Calls ohne run_in_background: true. Hält Hauptsession responsive." }, { "name": "coach-before.sh", "hook": "SessionStart", "function": "Rotiert Playbook-Regeln, Streak-Counter, tägliche Fokus-Injection." }, { "name": "event_logger.py", "hook": "alle Events", "function": "JSON-Telemetrie aller Tool-Calls. Datei: ~/.claude/events/YYYY-MM-DD.jsonl" }, { "name": "gsd-context-monitor.js", "hook": "PostToolUse", "function": "Context-Window-Überwachung. Warnt bei >80% Auslastung." }, { "name": "hook_inject.py (Sidecar-NG)", "hook": "UserPromptSubmit", "function": "Keyword-First → LLM-Fallback Klassifikation. Injiziert additionalContext für aktiven Mode/Skill." } ] } } }, { "id": "hermes", "name": "Hermes", "tagline": "Billig & Anpassungsfähig — das Arbeitspferd", "status": "aktiv", "color": "gold", "data_complete": true, "stats": [ { "label": "Sessions", "value": "40+" }, { "label": "Avg. Session", "value": "~20 min" }, { "label": "Modell", "value": "MiniMax-M2.5" } ], "strengths": [ "MiniMax ~150x billiger als Opus — fuer Routineaufgaben", "10 Provider, 200+ Modelle via OpenRouter", "Beste Feedback-Annahme — Korrekturen werden direkt akzeptiert", "48 eingebaute Tools (Web, Browser, Vision, SmartHome)", "Git Worktrees fuer parallele, isolierte Tasks" ], "weaknesses": [ "Scope-Drift: Baut standardmaessig in ~/.hermes/ wenn cwd nicht gesetzt", "Langsamer Start: 10-15s Stille vor erster Response — normal, nicht abbrechen", "Output-Qualitaet mittel: funktional aber nicht elegant", "Kein CLAUDE.md-Aequivalent: SOUL.md aktuell leer", "Kein PreToolUse-Blocking: keine programmatische Verhaltenssteuerung" ], "architecture_link": "diagrams/architecture-hermes.html", "router_keywords": ["build", "implement", "feature", "frontend", "backend", "api", "günstig", "iterati", "docs", "dokumentation", "research", "schreib"], "router_reason": "50x günstiger als Opus. Self-Improvement ersetzt deine Meta-Arbeit. Wenn du weißt WAS du willst — bau es hier.", "router_wave": "Wave 2 — Build", "tutorial": { "quickStart": [ "IMMER zuerst: `cd ~/Projekte/Projekt` — Hermes baut sonst in ~/.hermes/", "Starte: `hermes chat` (15s Stille am Anfang = normal, nicht abbrechen)", "Modell waehlen: `hermes chat -m minimax/minimax-text-01` fuer guenstige Runs", "Verzeichnis-Check: 'Bestätige in welchem Verzeichnis du arbeitest'", "Tasksheet einfuegen — Scope, Output-Pfad, Constraints klar", "Feedback geben — konkret und praezise. Hermes akzeptiert Korrekturen direkt.", "Feature by Feature iterieren, Summary fuer Handoff an Codex" ], "adhsPatterns": { "bodyDoubling": "Pair-Programming-Feeling. CLI oder Telegram — offen lassen, nicht killen. Ich rede waehrend du zuloeschst.", "dopaminTrigger": "Iteratives Feedback gibt immediate gratification. Kleine Korrektur, sofort sichtbarer Erfolg. Nicht alles auf einmal.", "antiParalysis": "Feature by Feature. Kleine Schritte die ich abschliessen kann. Scope-Drift ist teurer als tiny Tasks.", "sessionRhythm": "15s Stille am Anfang ist normal. Geduld. Iterationen sind billig — nich neu starten wenn etwas falsch ist." }, "wellenmodus": { "role": "Output-Bauer (Wave 2)", "entry": "Wenn Claude Code einen Plan hat und Tasksheet existiert", "exit": "Summary an Codex fuer Polishing oder fertig wenn keine Qualitaetsanspruch" }, "handoff": { "toOpenCode": "Reality-Check mit frischem Blick — was hat Hermes gebaut das suboptimal ist?", "toCodex": "Summary: Geaenderte Dateien, implementierte Features, offene TODOs. Codex Polishing machen lassen." }, "architektur": { "annotations": [ { "component": "config.yaml", "description": "Haupt-Config (YAML). 284 Zeilen — alle Einstellungen." }, { "component": "SOUL.md", "description": "Agent-Personality, freier Text. Aktuell leer — Potenzial ungenutzt." }, { "component": "10 Provider", "description": "MiniMax, OpenRouter (200+ Modelle), Anthropic, OpenAI, Gemini, Custom Endpoints." }, { "component": "48 Tools", "description": "Web, Terminal, Vision, Browser, SmartHome — ohne MCP-Server." }, { "component": "Git Worktrees", "description": "Parallele isolierte Agents auf demselben Repo. Merge danach manuell." } ] }, "config": { "settingsKeys": [ { "key": "default_model", "type": "string", "default": "MiniMax-M2.5", "description": "Default-Modell" }, { "key": "default_provider", "type": "string", "default": "minimax", "description": "Default-Provider" }, { "key": "agent.reasoning_effort", "type": "string", "default": "medium", "description": "low | medium | high — mehr Tokens bei high" }, { "key": "terminal.backend", "type": "string", "default": "local", "description": "local | docker | ssh | modal — wo Code ausgefuehrt wird" }, { "key": "terminal.cwd", "type": "string", "default": ".", "description": "Working Directory — ~/.hermes wenn nicht gesetzt" }, { "key": "memory.enabled", "type": "boolean", "default": "true", "description": "Cross-Session Memory via Honcho AI" }, { "key": "compression.enabled", "type": "boolean", "default": "true", "description": "Context-Kompression fuer lange Sessions" } ], "hooks": [ { "name": "gateway:startup", "description": "Beim Gateway-Start. Logging, Init.", "canBlock": false }, { "name": "session:start", "description": "Bei neuer Session. Worktree-Setup.", "canBlock": false }, { "name": "agent:start", "description": "Vor erstem Agent-Turn.", "canBlock": false }, { "name": "session:reset", "description": "Bei Session-Reset. Cleanup.", "canBlock": false } ] }, "faq": [ { "q": "Session startet nicht", "a": "15s warten. Dann Enter druecken. Das ist normal — nicht abbrechen und neu starten." }, { "q": "Baut am falschen Ort", "a": "IMMER zuerst cd in Projektordner. Tasksheet muss Output-Pfad enthalten." }, { "q": "Output-Qualitaet mittel", "a": "Normal. Hermes ist funktional, nicht elegant. Polishing by Codex." }, { "q": "Keine Verhaltensregeln", "a": "SOUL.md ist leer. Fuer strukturierte Regeln: SOUL.md befuellen (kommt noch)." }, { "q": "Workflow mit Claude Code", "a": "Plan Mode in CC → Tasksheet schreiben → hermes chat → Summary → Codex Polishing." } ] } }, { "id": "opencode", "name": "OpenCode", "tagline": "Schlankes Agentic Coding Tool", "status": "aktiv", "color": "green", "data_complete": true, "stats": [ { "label": "Sessions", "value": "50+" }, { "label": "Avg. Session", "value": "~15 min" }, { "label": "Modell", "value": "MiniMax / Claude Sonnet" } ], "strengths": [ "Multi-Provider: Anthropic, OpenAI, MiniMax ohne Lock-in", "One-Shot Mode für schnelle Pipelines", "Parallele Instanzen ohne Konflikte", "MCP native Support ohne JSON-Editierung", "Headless Server für API-Integration" ], "weaknesses": [ "Fragt NICHT nach — unvollständiges Briefing führt zu falschem Output", "Scope-Drift ohne explizites Scope-Statement", "Kein Session-Gedächtnis zwischen opencode run-Aufrufen", "Feedback-Reparatur schwach — Korrekturen werden bestätigt aber nicht integriert", "Keine Subagent-Orchestrierung" ], "architecture_link": "diagrams/architecture-opencode.html", "router_keywords": ["bugfix", "bug", "fix", "fehler", "debug", "isoliert", "schnell", "provider", "lsp"], "router_reason": "LSP Pre-fetch liefert Kontext bevor du fragst. Für isolierte Bugs ohne den Overhead von Claude Code.", "router_wave": "Wave 2 — Build (Alternative)", "tutorial": { "quickStart": [ "Starte mit: `opencode` (TUI) oder `opencode run \"prompt\"` (one-shot)", "Im Projektordner starten: `cd ~/Projekte/MeinProjekt`", "Erstes: `Lies ARCHITECTURE.md` — Was hat Claude Code geplant?", "Scope explizit machen: Output-Pfad + Umfang in einem Satz", "Bauen oder Reality-Check — one-shot für Drafts, TUI für komplexe Tasks", "Ergebnis dokumentieren — was wurde gebaut, was weggelassen, warum" ], "adhsPatterns": { "bodyDoubling": "TUI-Session fühlt sich wie Pair-Programming an. Offen lassen, nicht wegdiskutieren. Ich rede während du baust.", "dopaminTrigger": "Schneller Output in <30s. One-shot für immediate gratification — Draft wegwerfen ist billig, nicht frustrierend.", "antiParalysis": "Kurzes Briefing, schneller Re-Run. Billig = Experimentieren erlaubt. Lieber 2min laenger briefen als zweiten Run.", "sessionRhythm": "One-shots statt Marathon. Max 3 Runs pro Task, dann reflektieren. Nicht in Loop verlieren." }, "wellenmodus": { "role": "Reality-Check & Schnell-Builder", "entry": "Wenn Claude Code einen Plan hat und du schnelle Validierung brauchst", "exit": "Ergebnis an Hermes für Implementierung oder Bestätigung dass Plan stimmt" }, "handoff": { "toHermes": "Dateistruktur + validierten Plan. Kontext immer mitgeben.", "toCodex": "Refactor-Task mit Before/After-Beschreibung. Sandbox macht sicheres Bulk-Edit." }, "architektur": { "annotations": [ { "component": "opencode run", "description": "One-shot Execution ohne TUI. Für Pipelines und schnelle Drafts." }, { "component": "opencode serve", "description": "Headless HTTP-Server für API-Integration." }, { "component": "Multi-Provider", "description": "anthropic, openai, minimax. MiniMax ~150x billiger als Opus." }, { "component": "Plugins (TS)", "description": "TypeScript Hooks für Context-Injection. experimental.chat.system.transform." }, { "component": "MCP-Server", "description": "Native CLI-Verwaltung: opencode mcp add/remove/list." } ] }, "config": { "settingsKeys": [ { "key": "provider", "type": "object", "description": "API-Keys für Provider (anthropic, openai, minimax)" }, { "key": "model.default", "type": "string", "default": "anthropic/claude-sonnet-4-5", "description": "Default-Modell" }, { "key": "model.fast", "type": "string", "default": "anthropic/claude-haiku-4-5", "description": "Schnelles Modell für einfache Tasks" }, { "key": "permission", "type": "string", "default": "ask", "description": "ask | auto-edit | allow — für headless: allow" }, { "key": "mcp", "type": "object", "description": "MCP-Server Config (filesystem, github, etc.)" }, { "key": "experimental.chat.system.transform", "type": "string", "description": "Plugin-Path für Context-Injection" } ], "hooks": [ { "name": "system.transform", "description": "TypeScript-Hook für System-Prompt Modifikation. Injiziert CLAUDE.md-ähnliche Regeln.", "canBlock": false }, { "name": "postResponse", "description": "Nach Response — für Syntax-Check, Narration-Dispatch.", "canBlock": false }, { "name": "onError", "description": "Bei Error — Error-Pattern-Analyse und Kontext-Return.", "canBlock": false } ] }, "faq": [ { "q": "Session blockiert", "a": "ctrl+c zum Beenden. Bei headless: permission: allow in opencode.json setzen." }, { "q": "Baut das Falsche", "a": "Re-Run mit explizitem Scope. Nicht 'nochmal' sagen — genau beschreiben was ANDERS." }, { "q": "Kein Gedächtnis", "a": "Kontext immer mitgeben. Nichts voraussetzen. Jeder run startet blank." }, { "q": "Plugin funktioniert nicht", "a": "experimental.chat.system.transform in opencode.json prüfen. Pfad muss stimmen." }, { "q": "Dashboard statt Website", "a": "Immer explizit: 'Admin-Dashboard, nicht Landing Page. Keine Hero-Section.'" } ] } }, { "id": "codex-cli", "name": "Codex CLI", "tagline": "Verify-, Review- und Polishing-Harness fuer den letzten Meter", "status": "aktiv", "color": "amber", "data_complete": true, "stats": [ { "label": "Sessions", "value": "40+" }, { "label": "Avg. Session", "value": "~20 min" }, { "label": "Modell", "value": "gpt-5.4" } ], "strengths": [ "Saubere Scope-Begrenzung durch Sandbox + Approval-Policy", "Starker Review-Workflow mit `codex review`", "Rigorose Rueckfragen vor riskanten Implementierungen", "Terminal-nahe Edits, Refactors und Batch-Operationen", "Runbooks fuer Planning, Build, Inspect und Review" ], "weaknesses": [ "Langsamer Start wenn das Repo erst gelesen werden muss", "Kein Hook-System wie bei Claude Code", "Wenig Selbstkritik — Review und Tests weiter selbst einfordern", "Nicht der beste ROI fuer offene Exploration oder Research", "OpenAI-locked, kein Multi-Provider-Setup" ], "architecture_link": "diagrams/architecture-codex-cli.html", "router_keywords": ["test", "tests", "verif", "review", "polish", "polieren", "refactor", "rename", "bulk", "migrat", "sandbox", "batch", "aufräum", "cleanup", "quality", "stabil", "ship"], "router_reason": "Codex ist dein Finish-Harness: Sandbox und Approval halten den Scope eng, Rueckfragen reduzieren Fehlannahmen und `codex review` macht den letzten Qualitaetscheck.", "router_wave": "Wave 3 — Verify" , "tutorial": { "quickStart": [ "Starte interaktiv mit `codex` direkt im Projektordner wenn der Task noch Rueckfragen braucht", "Nutze `codex exec \"PROMPT\"` fuer klare Einzelaufgaben wie Type Hints, Refactors oder Tests", "Setze fuer sichere Alltagsarbeit `-s workspace-write -a on-request` oder den Shortcut `--full-auto`", "Verwende `codex review` vor jedem Ship-Kandidaten als Pflichtschritt, nicht als Bonus", "Wenn ein guter Zwischenstand existiert: `codex resume --last` fortsetzen oder `codex fork --last` fuer riskante Varianten" ], "adhsPatterns": { "bodyDoubling": "Codex ist weniger conversational als Claude Code, aber stark wenn der Auftrag klar gerahmt ist. Nutze ihn als ruhigen Co-Worker fuer den Finish-Pass: ein Ziel, ein Scope, ein sauberer Abschluss.", "dopaminTrigger": "Sichtbare Mini-Wins funktionieren gut: erst `codex review`, dann ein enger Fix, dann direkt Tests oder Smoke-Checks. Kurze, abgeschlossene Schleifen halten Momentum ohne Scope-Explosion.", "antiParalysis": "Wenn du festhaengst, nicht 'mach es besser' sagen. Gib Codex ein enges Paket: Datei, Ziel, Definition of Done und was explizit out of scope ist.", "sessionRhythm": "Codex nicht als Marathon-Session benutzen. Erst Planung oder Build woanders, dann 15 bis 25 Minuten Finish-Phase: Review, Polishing, Verifikation, Handoff." }, "wellenmodus": { "role": "Verifier & Finisher", "entry": "Wenn ein Feature bereits gebaut ist und jetzt Review, Polishing, Tests oder Scope-sichere Refactors anstehen", "exit": "Ship-Entscheidung mit Findings, offenen Punkten und konkreter Empfehlung an Samuel" }, "handoff": { "toHermes": "Wenn waehrend des Polishings klar wird dass neue Funktionalitaet fehlt oder ein groesserer Umbau noetig ist.", "toOpenCode": "Wenn ein isolierter Build-Task schneller als one-shot oder in parallelen kleinen Runs gebaut werden kann.", "toSamuel": "Review-Ergebnis, behobene Punkte, verbleibende Risiken und eine klare Ship-Empfehlung: JA oder NEIN." }, "architektur": { "annotations": [ { "component": "config.toml", "description": "Zentrale Steuerung fuer Modell, Reasoning, Trust-Level und Modell-Migrationen." }, { "component": "Runbooks", "description": "Vier Session-Typen strukturieren die Arbeit: build, planning, review und inspect." }, { "component": "Sandbox Mode", "description": "Bestimmt die Umgebung: read-only, workspace-write oder danger-full-access." }, { "component": "Approval Policy", "description": "Legt fest wann Rueckfragen kommen: untrusted, on-request, on-failure oder never." }, { "component": "codex review", "description": "Eingebauter Review-Modus fuer uncommitted Changes, Branch-Diffs oder einzelne Commits." } ] }, "config": { "settingsHeading": "Config / CLI Keys", "hooksHeading": "Runbooks", "settingsKeys": [ { "key": "model", "type": "string", "default": "gpt-5.4", "description": "Standardmodell fuer interaktive Sessions und exec-Runs" }, { "key": "model_reasoning_effort", "type": "string", "default": "medium", "description": "Reasoning-Tiefe: low, medium, high oder xhigh" }, { "key": "projects..trust_level", "type": "string", "default": "trusted", "description": "Projektbezogene Vertrauenseinstufung fuer Rechte und Verhalten" }, { "key": "notice.model_migrations", "type": "table", "description": "Leitet veraltete Modellnamen auf aktuelle Modelle um" }, { "key": "sandbox_mode", "type": "flag", "default": "workspace-write", "description": "Praktisch via CLI-Flag gesetzt: read-only, workspace-write oder danger-full-access" }, { "key": "approval_policy", "type": "flag", "default": "on-request", "description": "Praktisch via CLI-Flag gesetzt: untrusted, on-request, on-failure oder never" } ], "hooks": [ { "name": "planning.md", "description": "Runbook fuer unscharfe Ziele und Architekturarbeit. Erst artefaktfaehig machen, dann bauen.", "canBlock": false }, { "name": "build.md", "description": "Runbook fuer klar umrissene Implementierung mit stabilem Outcome.", "canBlock": false }, { "name": "inspect.md", "description": "Read-only Exploration zum Verstehen einer Codebase ohne Edits.", "canBlock": false }, { "name": "review.md", "description": "Qualitaets- und Regressionsfokus fuer Review-Paesse vor dem Ship.", "canBlock": false } ] }, "faq": [ { "q": "Warum stellt Codex so viele Rueckfragen?", "a": "Weil es Fehlannahmen vor dem Edit reduziert. Gerade bei Review-, Refactor- und Finish-Aufgaben spart das Re-Work." }, { "q": "Wann nutze ich `codex review`?", "a": "Immer vor einem Ship-Kandidaten und immer dann, wenn Codex selbst etwas veraendert hat. Review ist Pflichtschritt, nicht optional." }, { "q": "Welcher Sandbox-Modus ist alltagstauglich?", "a": "Meist `workspace-write` mit `on-request`. Fuer Analyse `read-only`, fuer riskante Vollautonomie nur in bekannten, stabilen Situationen mehr." }, { "q": "Wofuer ist Codex die falsche Wahl?", "a": "Offene Exploration, Research und grobe Produktentscheidungen. Dafuer erst Claude Code oder Hermes nutzen und Codex spaeter fuer Finish und Verify einsetzen." }, { "q": "Was wenn waehrend des Polishings neuer Scope auftaucht?", "a": "Nicht heimlich mitbauen. Findings dokumentieren und den Task zur passenden Build- oder Plan-Phase zurueckgeben." } ] } } ], "architecture_diagrams": [ { "name": "Claude Code", "link": "diagrams/architecture-claude-code.html", "description": "Hub-and-Spoke Architektur mit Sidecar-NG Integration" }, { "name": "Hermes", "link": "diagrams/architecture-hermes.html", "description": "Multi-Provider Gateway mit SOUL.md und Personality-System" }, { "name": "Codex CLI", "link": "diagrams/architecture-codex-cli.html", "description": "Terminal-native Pipeline mit Sandbox-Execution" }, { "name": "OpenCode", "link": "diagrams/architecture-opencode.html", "description": "Modulares Open-Source Coding Agent Framework" } ], "laws": [ { "number": 1, "title": "Kontext ist alles", "text": "Ohne sauberen Kontext liefert jedes Modell Mittelwert-Output. CLAUDE.md, Sidecar und Skill-Injektion sind keine Extras — sie sind der Job.", "beweis": "Sessions ohne Sidecar produzieren messbar mehr Korrekturen", "color": "teal" }, { "number": 2, "title": "Verifikation vor Commit", "text": "Code Review allein zaehlt nicht. Tests laufen oder es ist nicht fertig.", "beweis": "Jeder 'fast fertig'-Commit ohne Tests hat Folge-Fixes erzeugt", "color": "green" }, { "number": 3, "title": "Atomare Commits", "text": "Eine logische Aenderung pro Commit. Was nicht in einen Satz passt, gehoert in zwei Commits.", "beweis": "Grosse Commits blockieren Rollbacks und verwischen Kausalitaet", "color": "gold" }, { "number": 4, "title": "Fragen ist schneller als Irren", "text": "Wenn der Agent unsicher ist, fragt er. Eine Rueckfrage kostet 10 Sekunden. Falsches Abbiegen kostet 10 Minuten.", "beweis": "Sidecar Intent-First-Regel reduziert Out-of-Scope-Aenderungen", "color": "teal" }, { "number": 5, "title": "Parallelitaet beats Sequenz", "text": "Unabhaengige Tasks werden gleichzeitig ausgefuehrt. Subagents sind die Einheit, nicht Prompts.", "beweis": "Parallele Subagent-Runs reduzieren Gesamtzeit um ~60%", "color": "amber" }, { "number": 6, "title": "Scope-Disziplin", "text": "Was nicht explizit beauftragt ist, wird nicht gemacht. Keine spontanen Refactors, keine Erweiterungen.", "beweis": "Scope-Creep ist die haeufigste Ursache fuer lange Review-Zyklen", "color": "red" }, { "number": 7, "title": "Exploration Budget", "text": "Ein fehlgeschlagener Ansatz, dann Stop und fragen. Nicht automatisch Ansatz 2 probieren.", "beweis": "Zweiter autonomer Ansatz loest das Problem selten, kostet aber immer Context", "color": "amber" }, { "number": 8, "title": "Stabilisierung vor Neubau", "text": "Bugs werden als Patches geloest, nicht als Rewrites. Backlog schlaegt Goldplating.", "beweis": "Rewrites ohne Testbaseline reproducieren 40% der alten Bugs", "color": "gold" }, { "number": 9, "title": "Deutsche Kommunikation, englische Commits", "text": "Conventional Commits auf Englisch. Alles andere in der Sprache des Kontexts.", "beweis": "Konsistenz in Commit-History erleichtert Changelog-Generierung", "color": "muted" }, { "number": 10, "title": "Evidence vor Bauchgefuehl", "text": "Kein Feature, keine Entscheidung ohne Datenbasis. Evals, Logs, Tests — nicht Intuition.", "beweis": "Sidecar-NG Accuracy-Messungen zeigten kontra-intuitive Ergebnisse mehrfach", "color": "teal" } ], "anti_patterns": [ { "name": "Ambiguous Target", "description": "Task starten ohne zu klaeren welches Projekt, welche Komponente, welches Konzept gemeint ist.", "folge": "30 Minuten Arbeit in die falsche Richtung", "severity": "hoch" }, { "name": "Blind Agent Trust", "description": "Subagent-Output nicht verifizieren und direkt als erledigt markieren.", "folge": "Stille Regressionen, die erst Tage spaeter auffallen", "severity": "kritisch" }, { "name": "Big Bang Commit", "description": "Alles in einem Commit, weil 'gehoert zusammen'.", "folge": "Unkontrollierbarer Rollback, verlorene Kausalitaet", "severity": "hoch" }, { "name": "Config-Halluzination", "description": "Keys in Konfigurationsdateien schreiben die dort nicht existieren.", "folge": "Stille Fehler oder Runtime-Crashes", "severity": "hoch" }, { "name": "Scope Creep", "description": "Waehrend X implementieren auch Y und Z refactoren weil man gerade dabei ist.", "folge": "Review-Aufwand verdoppelt, Rollback unmoeglich", "severity": "mittel" }, { "name": "Guessing without Asking", "description": "Bei Unklarheit raten statt eine Rueckfrage zu stellen.", "folge": "Meistens falsche Richtung, immer Zeitverlust", "severity": "hoch" }, { "name": "Retry Loop ohne Diagnose", "description": "Nach fehlgeschlagenem Test denselben Ansatz nochmal versuchen.", "folge": "Exponentiell steigende Context-Kosten, gleiche Fehler", "severity": "mittel" }, { "name": "Commit ohne Tests", "description": "Commit-Vorschlag ohne eigene Verifikation dass Tests gruen sind.", "folge": "Samuel gibt Freigabe auf der Basis falscher Annahmen", "severity": "kritisch" } ], "wave_mode": { "kicker": "So arbeite ich", "heading": "Wellenmodus", "description": "Jede produktive Session folgt dem gleichen Muster: Scout, Build, Verify — mit klaren Convergence-Checkpoints.", "phases": [ { "id": "scout", "name": "Scout", "description": "Kontext aufbauen. Ziel klaeren. Ambiguitaeten eliminieren bevor Code geschrieben wird.", "steps": ["git status pruefen", "Relevante Dateien lesen", "Ziel mit Samuel abgleichen", "Teilaufgaben identifizieren"], "color": "teal" }, { "id": "build", "name": "Build", "description": "Parallele Subagents fuer unabhaengige Tasks. Atomare Aenderungen. Scope-Disziplin.", "steps": ["Subagents spawnen fuer parallele Arbeit", "Jede Aenderung atomar halten", "Scope nicht erweitern", "Fehler sofort eskalieren"], "color": "gold" }, { "id": "verify", "name": "Verify", "description": "Tests ausfuehren. Output verifizieren. Commit erst nach gruenem Signal.", "steps": ["pytest / smoke-tests laufen", "Agent-Output selbst pruefen", "Commit-Gate: Samuel entscheidet", "Ergebnis dokumentieren"], "color": "green" } ], "checkpoints": [ "Nach Scout: Ziel ist schriftlich klar", "Nach Build: Tests existieren fuer jede Aenderung", "Nach Verify: Samuels Commit-Freigabe" ] }, "costs": { "kicker": "Was kostet was", "heading": "Kostenvergleich", "harnesses": [ { "name": "Claude Code", "model": "claude-opus-4-6", "cost_per_session": "~$0.80-3.00", "cost_relative": 100, "billing": "Token-basiert", "notes": "Hoechste Qualitaet, hoechste Kosten. Subagents multiplizieren." }, { "name": "Hermes", "model": "TBD", "cost_per_session": "TBD", "cost_relative": 0, "billing": "TBD", "notes": "Daten nach Bootcamp verfuegbar" }, { "name": "OpenCode", "model": "Konfigurierbar", "cost_per_session": "Modell-abhaengig", "cost_relative": 60, "billing": "Token-basiert via Provider", "notes": "Open-Source, Kosten haengen vom konfigurierten Modell ab" }, { "name": "Codex CLI", "model": "gpt-5.4", "cost_per_session": "~$0.20-0.60", "cost_relative": 25, "billing": "Token-basiert (OpenAI)", "notes": "Mittelpreisig, aber stark fuer Review, Polishing und verifizierte Terminal-Tasks" } ] } }