Plan-Canvas

Was macht Plan-Canvas?

Review-Loop für Pläne und visuelle Artefakte: Du schreibst das Artefakt, der Mensch prüft es im Browser – annotiert das exakte Element, das er meint, chatet und gibt ein Votum „Plan genehmigen / Änderungen anfordern“ ab – während du auf einem einzelnen CLI-Aufruf blockierst, der das Feedback als JSON zurückgibt.

Inspiriert von lavish-axi; neu aufgebaut als ECC-native Lösung rund um das /plan-Bestätigungsgate, mit null Abhängigkeiten.

Wann verwenden

• Du hast gerade ein Plan-Artefakt geschrieben (.claude/plans/*.plan.md von /plan) und benötigst die BESTÄTIGUNG/Genehmigung – das Canvas-Votum ersetzt eine getippte „Ja/weiter“.
• Der Benutzer soll darauf zeigen, was geändert werden soll: Überprüfung von Designs, Vergleichen, Berichten oder beliebigen lokalen .md-/.html-Artefakten.
• Der Benutzer fragt nach /plan-canvas, einer visuellen Überprüfung oder „öffne es im Browser“.

NICHT verwenden für: Code-Review von Diffs (/code-review), Ausführen von Web-Apps oder entfernten URLs. Das Canvas dient nur lokalen Artefakt-Dateien.

Funktionsweise

Rufe das CLI als ecc-plan-canvas auf – das Binary, das vom Paket ecc-universal bereitgestellt wird (nach einer globalen/Plugin-Installation im PATH; node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js" funktioniert auch für Plugin-Installationen). Führe es aus dem Projekt aus, das du gerade überprüfst; es funktioniert von jedem Arbeitsverzeichnis aus. Es verwaltet einen getrennten Loopback-Server (127.0.0.1:4517), der von allen Sitzungen gemeinsam genutzt wird, abgeglichen über den Artefakt-Pfad – keine Sitzungs-IDs zum Nachverfolgen.

Der Workflow ist eine einfache CLI-plus-JSON-Schleife, daher Modell- und Framework-unabhängig: Jeder Agent, der einen Shell-Befehl ausführen und stdout lesen kann, steuert ihn auf die gleiche Weise (Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot). Starte ihn so, wie dein Framework Skills bereitstellt – z. B. /plan-canvas in Claude Code, $plan-canvas in Codex – oder führe die ecc-plan-canvas-Befehle direkt aus.

# 1. Öffne das Artefakt im Browser des Benutzers (sofortige Rückmeldung)
ecc-plan-canvas open .claude/plans/feature.plan.md

# 2. Blockiere, bis der Mensch antwortet. Lass es laufen; führe es bei Unterbrechung erneut aus:
#    in der Warteschlange befindliches Feedback geht nie verloren.
ecc-plan-canvas await .claude/plans/feature.plan.md

Hör zu, sonst spricht der Mensch mit einem leeren Stuhl

Feedback erreicht dich nur, solange ein await tatsächlich auf der Sitzung wartet. Wenn dein Zug endet und niemand zuhört, bleibt die Nachricht in der Warteschlange und vom Menschen aus gesehen scheint das Senden nichts zu bewirken.

Führe daher await als Hintergrundaufgabe aus, wenn dein Framework dies unterstützt (in Claude Code: ein Bash-Aufruf mit run_in_background: true). Es beendet sich, sobald Feedback eintrifft, und das Framework übergibt dir das JSON, was die Schleife über mehrere Züge hinweg am Leben hält, anstatt mit dem Vordergrundaufruf zu sterben. Ein Vordergrund-await funktioniert auch, aber nur bis das Framework es zeitlich begrenzt.

Es gibt zwei Rückfallebenen, die jedoch keine Ausrede sind, um das Obige zu überspringen:

• ecc-plan-canvas pending listet Feedback auf, das ohne Zuhörer in der Warteschlange steht. Überprüfe es immer, wenn du unsicher bist, ob du etwas verpasst hast.
• Der Hook stop:plan-canvas-pending blockiert das Ende deines Zuges, solange Canvas-Feedback noch nicht zugestellt wurde, und übergibt dir die Nachrichten. Wenn du Feedback aus diesem Hook liest, hast du zu früh aufgehört zuzuhören.

await gibt JSON aus, wenn der Mensch handelt:

{
  "status": "feedback",
  "items": [
    { "kind": "annotation", "text": "Teile dies in zwei Phasen auf",
      "anchor": { "selector": "h2:nth-of-type(3)", "tag": "h2", "snippet": "Phase 2: Migration" } },
    { "kind": "verdict", "verdict": "request-changes" }
  ]
}

• kind: "chat" – Freitext-Nachricht; antworte im Canvas, nicht im Terminal.
• kind: "annotation" – Feedback, das an einem Element verankert ist (anchor.selector, anchor.snippet zeigen, worauf sie gezeigt haben; anchor.textRange.text, wenn sie eine Passage hervorgehoben haben).
• kind: "verdict" – approve bedeutet, der Plan ist BESTÄTIGT: höre auf zu polln, beende die Sitzung und beginne mit der Implementierung. request-changes bedeutet, überarbeite das Artefakt (das Canvas lädt es live neu) und setze die Schleife fort.

3. Antworte immer im Canvas, höre dann weiter zu. Ein Befehl erledigt beides:

ecc-plan-canvas await <datei> --reply "Phase 2 wie gewünscht aufgeteilt. Schau mal."

Jede menschliche Nachricht erhält eine Antwort im Canvas, auch ein Einzeiler wie „Bin dabei, schreibe die Risikotabelle gerade um.“ Stille im Chat-Panel ist nicht von einem defekten Canvas zu unterscheiden – genau das Versagen, das diese Schleife verhindern soll. Antworte dort, nicht nur im Terminal.

Halte den Chat während der Arbeit mit dem Aktivitätsindikator ehrlich:

# animierte „Agent denkt nach…“-Blase; aktualisiere sie bei längerer Arbeit
ecc-plan-canvas typing <datei> --state thinking
# wechsle zu „Agent tippt…“ kurz bevor eine Antwort eintrifft
ecc-plan-canvas typing <datei> --state typing

await setzt thinking für dich, sobald es dir einen Batch übergibt, und --reply löscht es. Beide Zustände laufen selbsttätig ab, sodass ein abgestürzter Agent zu einem ehrlichen „in der Warteschlange“ verfällt, anstatt den Menschen ewig auf Punkte starren zu lassen. Aktualisiere thinking, wenn eine Überarbeitung länger als eine Minute dauert.

4. Beende die Überprüfung: ecc-plan-canvas end <datei>.

Diagramme (Mermaid)

Wenn ein Teil des Plans ein Ablauf-, Architektur-, Sequenz-, Zustands-, ER-Modell oder Abhängigkeitsgraph ist, schreibe es als umschlossenen ```mermaid-Block statt als ASCII-Kunst oder Prosa-Wand – das Canvas rendert es als thematisiertes Diagramm, auf das der Mensch zeigen kann. Greife darauf zurück, wenn ein Bild schneller zu lesen ist als ein Absatz; überspringe es bei einfachen Listen oder Tabellen.

```mermaid
flowchart LR
  A[Markt entscheidet] --> B{Beobachter?}
  B -->|ja| C[Aufgaben einreihen] --> D[Fan-Out-Worker]
```

Diagramme werden im ECC-Dunkelthema mit der Akzentpalette gerendert. Mermaid wird im Browser von einem gepinnten CDN geladen; falls dieses nicht verfügbar ist (offline), degradiert der Block zur Anzeige des Quelltextes, sodass die Überprüfung nie blockiert wird. Richte für den Luftspaltbetrieb einen lokalen Spiegel unter ECC_PLAN_CANVAS_MERMAID_URL ein.

Regeln

• Markdown-Artefakte werden in ECCs Plan-Vorlage gerendert (einschließlich Mermaid-Blöcke); .html-Artefakte werden unverändert mit eingefügter Annotationsschicht gerendert. Für HTML-Autorichtlinien verwende die Skills frontend-design-direction und artifact-design.
• Bearbeite die Artefakt-Datei zur Überarbeitung – das Canvas lädt bei Speicherung live neu. Führe niemals open erneut aus, um zu aktualisieren.
• {"status": "ended", "endedBy": "user"} (oder sessionEnded: true bei einem Feedback-Batch) bedeutet, der Benutzer hat die Überprüfung beendet: höre auf zu polln, liefere verbleibende Updates im Chat und öffne nicht erneut. Ein einfaches open für diese Sitzung wird abgelehnt; übergib --reopen nur, wenn der Benutzer die Wiederaufnahme anfordert.
• Geschwister-Assets (Bilder, CSS) müssen neben dem Artefakt liegen und mit relativem Pfad referenziert werden.
• Der Server ist nur auf Loopback beschränkt und beendet sich nach 30 Minuten Inaktivität (ECC_PLAN_CANVAS_IDLE_MS); stop beendet ihn explizit. Der Zustand liegt in ~/.claude/plan-canvas/ (ECC_PLAN_CANVAS_STATE_DIR).

Beispiele

Plan-Genehmigungsablauf – /plan schreibt .claude/plans/notifications.plan.md und muss auf Bestätigung WARTEN:

ecc-plan-canvas open .claude/plans/notifications.plan.md
ecc-plan-canvas await .claude/plans/notifications.plan.md
# → {"status":"feedback","items":[{"kind":"verdict","verdict":"approve"}]}
ecc-plan-canvas end .claude/plans/notifications.plan.md
# Plan ist bestätigt – beginne mit der Implementierung

Überarbeitungsschleife – Feedback trifft ein, du bearbeitest die Datei, antwortest und hörst weiter zu:

# await gab Annotationen zurück → bearbeite die .plan.md (Canvas lädt live neu)
ecc-plan-canvas await <datei> --reply "Risikotabelle überarbeitet."
# → blockiert erneut bis zur nächsten Antwort

Anti-Patterns

• Pollen mit --timeout-ms in einer Schleife. Es existiert für Tests. Lass stattdessen das einfache await laufen.
• Deinen Zug beenden, während kein await zuhört und die Überprüfung noch offen ist. Das ist das eine Versagen, das der Mensch als „Ich habe eine Nachricht gesendet und nichts ist passiert“ erlebt.
• Das Feedback lesen, aber nur im Terminal antworten. Der Mensch schaut auf das Canvas.
• Nach einer benutzerinitiierten Beendigung erneut öffnen, „nur um etwas zu zeigen“.
• Den gesamten Plan in den Chat einfügen und ein Canvas öffnen – wähle das Canvas und halte die Terminal-Zusammenfassung auf eine Zeile.
• Den Canvas-Chat aus Zustandsdateien parsen – alles, was du brauchst, kommt über await.

Design-Notizen und Ursprung: docs/design/plan-canvas.md.