Plan Canvas

Was macht Plan Canvas?

Überprüfungsschleife für Pläne und visuelle Artefakte: Du schreibst das Artefakt, der Mensch überprüft es im Browser – annotiert das exakte Element, meint, chattet und gibt eine Plan genehmigen / Änderungen anfordern-Entscheidung – während du auf einem einzigen CLI-Aufruf blockierst, der ihr Feedback als JSON zurückgibt.

Inspiriert von lavish-axi; ECC-nativ neu entwickelt um das /plan-Bestätigungsgate, ohne Abhängigkeiten.

Wann verwenden

• Du hast gerade ein Plan-Artefakt geschrieben (.claude/plans/*.plan.md aus /plan) und benötigst die CONFIRM/Genehmigungsentscheidung – die Canvas-Entscheidung ersetzt ein getipptes „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 entfernte URLs. Die Canvas bedient nur lokale Artefaktdateien.

Wie es funktioniert

Rufe das CLI als ecc-plan-canvas auf – das Binärskript, das mit dem ecc-universal-Paket ausgeliefert 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 Projektverzeichnis aus, das du überprüfst; es funktioniert von jedem Arbeitsverzeichnis aus. Es verwaltet einen entkoppelten Loopback-Server (127.0.0.1:4517), der von allen Sitzungen gemeinsam genutzt wird, der nach Artefaktpfad geschlüsselt ist – keine Sitzungs-IDs müssen verfolgt werden.

Der Workflow ist eine einfache CLI-plus-JSON-Schleife, daher ist er 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, wie auch immer 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 (kehrt sofort zurück)
ecc-plan-canvas open .claude/plans/feature.plan.md

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

Bleibe zuhören, sonst spricht der Mensch mit einem leeren Stuhl

Feedback erreicht dich nur, während ein await tatsächlich auf der Sitzung wartet. Wenn dein Zug endet, ohne dass etwas zuhört, bleibt die Nachricht in der Warteschlange und erscheint aus der Sicht des Menschen, als ob das Senden überhaupt nichts bewirkt.

Führe also await als Hintergrundtask 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 Auffangmechanismen, und keiner ist eine Ausrede, 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 stop:plan-canvas-pending-Hook verhindert, dass dein Zug endet, 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" – frei formattierte Nachricht; antworte in der 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 fragen, beende die Sitzung und beginne mit der Implementierung. request-changes bedeutet, überarbeite das Artefakt (die Canvas lädt es live neu) und setze die Schleife fort.

3. Antworte immer in der Canvas, höre dann weiter zu. Ein Befehl macht beides:

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

Jede menschliche Nachricht erhält eine Antwort in der Canvas, selbst ein Einzeiler wie „Bin dran, schreibe die Risikotabelle um." Schweigen im Chatfenster ist nicht von einer defekten Canvas zu unterscheiden, genau das Versagen, das diese Schleife verhindern soll. Antworte dort, nicht nur im Terminal.

Während du arbeitest, halte den Chat mit dem Aktivitätsindikator ehrlich:

# animierte „Agent denkt nach..."-Blase; aktualisiere sie bei langer 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 einen Batch übergibt, und --reply löscht es. Beide Zustände laufen von selbst ab, sodass ein abgestürzter Agent zu einem ehrlichen „in der Warteschlange" verfällt, anstatt den Menschen in eine Endlosschleife von Punkten 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, eine Architektur, eine Sequenz, ein Zustandsautomat, ein ER-Modell oder ein Abhängigkeitsgraph ist, schreibe ihn als abgegrenzten ```mermaid-Block anstatt als ASCII-Art oder Prosa-Wand – die Canvas rendert ihn als thematisiertes Diagramm, auf das der Mensch zeigen kann. Greife darauf zurück, wenn ein Bild schneller gelesen wird als ein Absatz; überspringe es für einfache Listen oder Tabellen.

```mermaid
flowchart LR
  A[Markt löst aus] --> B{Beobachter?}
  B -->|ja| C[Aufgaben in Warteschlange] --> D[Fan-Out-Arbeiter]
```

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), wird der Block auf die Anzeige seines Quellcodes zurückgesetzt, sodass die Überprüfung nie blockiert wird. Verweise für den luftdichten Betrieb auf einen lokalen Mirror unter ECC_PLAN_CANVAS_MERMAID_URL.

Regeln

• Markdown-Artefakte werden in ECCs Planvorlage gerendert (einschließlich Mermaid-Blöcke); .html-Artefakte werden unverändert mit der eingefügten Annotationsschicht gerendert. Verwende für HTML-Autorichtlinien die Skills frontend-design-direction und artifact-design.
• Bearbeite die Artefaktdatei zur Überarbeitung – die Canvas lädt beim Speichern live neu. Führe niemals erneut open zum Aktualisieren aus.
• {"status": "ended", "endedBy": "user"} (oder sessionEnded: true bei einem Feedback-Batch) bedeutet, der Benutzer hat die Überprüfung geschlossen: höre auf zu fragen, liefere verbleibende Updates im Chat und öffne nicht erneut. Ein einfaches open für diese Sitzung wird abgelehnt; verwende --reopen nur, wenn der Benutzer darum bittet, fortzufahren.
• Geschwister-Assets (Bilder, CSS) müssen neben dem Artefakt liegen und über relative Pfade referenziert werden.
• Der Server ist Loopback-only und beendet sich nach 30 Minuten Inaktivität (ECC_PLAN_CANVAS_IDLE_MS); stop fährt ihn explizit herunter. Der Zustand wird in ~/.claude/plan-canvas/ (ECC_PLAN_CANVAS_STATE_DIR) gespeichert.

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, 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

• Abfragen mit --timeout-ms in einer Schleife. Es existiert nur für Tests. Lasse stattdessen das einfache await laufen.
• Deinen Zug beenden, ohne dass ein await zuhört, während die Überprüfung noch offen ist. Das ist der eine Fehler, den 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 die Canvas.
• Nach einer vom Benutzer initiierten Beendigung erneut öffnen „nur um etwas zu zeigen".
• Den gesamten Plan im Chat einfügen und eine Canvas öffnen – wähle die Canvas und halte die Terminal-Zusammenfassung auf eine Zeile.
• Den Canvas-Chat aus Zustandsdateien parsen – alles, was du brauchst, kommt über await.

Designnotizen und Ursprung: docs/design/plan-canvas.md.