plan-canvas

Plan Canvas

Boucle de révision pour les plans et les artefacts visuels : vous écrivez l'artefact, l'humain le révise dans le navigateur — en annotant l'élément exact qu'il vise, en discutant, et en fournissant un verdict Approuver le plan / Demander des modifications — pendant que vous bloquez sur un seul appel CLI qui renvoie ses retours au format JSON.

Inspiré par lavish-axi ; reconstruit nativement pour ECC autour de la porte de confirmation /plan, avec zéro dépendance.

Quand l'utiliser

• Vous venez d'écrire un artefact de plan (.claude/plans/*.plan.md depuis /plan) et avez besoin de la décision CONFIRM/approuver — le verdict du canevas remplace un "oui/continuer" tapé.
• L'utilisateur doit pointer ce qui doit changer : révision de conceptions, comparaisons, rapports, ou tout artefact local .md/.html.
• L'utilisateur demande /plan-canvas, une révision visuelle, ou "ouvre-le dans le navigateur".

Ne PAS utiliser pour : la révision de code de diffs (/code-review), l'exécution d'applications web, ou les URL distantes. Le canevas sert uniquement les fichiers artefacts locaux.

Comment ça fonctionne

Invoquez le CLI comme ecc-plan-canvas — le binaire fourni par le paquet ecc-universal (sur le PATH après une installation globale/plugin ; node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js" fonctionne aussi pour les installations plugin). Exécutez-le depuis le projet que vous révisez ; il fonctionne depuis n'importe quel répertoire de travail. Il gère un serveur de boucle locale détaché (127.0.0.1:4517) partagé par toutes les sessions, indexé par le chemin de l'artefact — aucun identifiant de session à suivre.

Le flux de travail est une simple boucle CLI-plus-JSON, donc indépendant du modèle et du harnais : tout agent capable d'exécuter une commande shell et de lire la sortie standard le pilote de la même manière (Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot). Déclenchez-le comme votre harnais expose les compétences — par exemple /plan-canvas dans Claude Code, $plan-canvas dans Codex — ou exécutez directement les commandes ecc-plan-canvas.

# 1. Ouvrir l'artefact dans le navigateur de l'utilisateur (retourne immédiatement)
ecc-plan-canvas open .claude/plans/feature.plan.md

# 2. Bloquer jusqu'à ce que l'humain réponde. Laissez tourner ; réexécutez si interrompu :
#    les retours en file d'attente ne sont jamais perdus.
ecc-plan-canvas await .claude/plans/feature.plan.md

Restez à l'écoute, ou l'humain parle dans le vide

Les retours ne vous parviennent que lorsqu'un await est effectivement en attente sur la session. Si votre tour se termine sans rien écouter, le message reste dans la file et, du côté de l'humain, l'envoi semble ne rien faire du tout.

Exécutez donc await comme une tâche de fond lorsque votre harnais le permet (dans Claude Code, un appel Bash avec run_in_background: true). Il se termine dès que le retour arrive et le harnais vous remet le JSON, ce qui maintient la boucle active entre les tours au lieu de mourir avec l'appel de premier plan. Un await de premier plan fonctionne aussi, mais seulement jusqu'à ce que le harnais le limite dans le temps.

Deux filets de sécurité existent, et aucun n'est une excuse pour ignorer ce qui précède :

• ecc-plan-canvas pending liste les retours en file d'attente sans écouteur. Vérifiez-le à chaque fois que vous n'êtes pas sûr d'avoir manqué quelque chose.
• Le crochet stop:plan-canvas-pending bloque la fin de votre tour tant que des retours du canevas ne sont pas livrés, et vous remet les messages. Si vous lisez les retours depuis ce crochet, c'est que vous avez arrêté d'écouter trop tôt.

await imprime du JSON lorsque l'humain agit :

{
  "status": "feedback",
  "items": [
    { "kind": "annotation", "text": "Séparez ceci en deux phases",
      "anchor": { "selector": "h2:nth-of-type(3)", "tag": "h2", "snippet": "Phase 2 : Migration" } },
    { "kind": "verdict", "verdict": "request-changes" }
  ]
}

• kind: "chat" — message libre ; répondez dans le canevas, pas dans le terminal.
• kind: "annotation" — retour ancré à un élément (anchor.selector, anchor.snippet montrent ce qu'ils ont pointé ; anchor.textRange.text lorsqu'ils ont surligné un passage).
• kind: "verdict" — approve signifie que le plan est CONFIRMÉ : arrêtez de scruter, mettez fin à la session, et commencez l'implémentation. request-changes signifie révisez l'artefact (le canevas le recharge en direct) et continuez la boucle.

3. Répondez toujours dans le canevas, puis continuez à écouter. Une commande fait les deux :

ecc-plan-canvas await <fichier> --reply "Phase 2 séparée comme demandé. Regardez."

Chaque message humain reçoit une réponse dans le canevas, même une ligne comme "J'y travaille, je réécris le tableau des risques maintenant." Le silence dans le panneau de chat est impossible à distinguer d'un canevas cassé, ce qui est exactement l'échec que cette boucle existe pour éviter. Répondez-y, pas seulement dans le terminal.

Pendant que vous travaillez, maintenez le chat honnête avec l'indicateur d'activité :

# bulle animée "l'agent réfléchit..." ; rafraîchissez-la pendant un long travail
ecc-plan-canvas typing <fichier> --state thinking
# passez à "l'agent tape..." juste avant qu'une réponse n'arrive
ecc-plan-canvas typing <fichier> --state typing

await définit thinking pour vous dès qu'il vous remet un lot, et --reply l'efface. Les deux états s'auto-expirent, donc un agent planté se dégrade en un "en file d'attente" honnête au lieu de laisser l'humain regarder des points indéfiniment. Rafraîchissez thinking si une révision prend plus d'une minute.

4. Terminez lorsque la révision est conclue : ecc-plan-canvas end <fichier>.

Diagrammes (Mermaid)

Lorsqu'une partie du plan est un flux, une architecture, une séquence, une machine d'état, un modèle ER ou un graphique de dépendances, rédigez-le comme un bloc délimité ```mermaid au lieu d'art ASCII ou d'un mur de prose — le canevas le rend comme un diagramme thématique que l'humain peut pointer. Utilisez-le quand une image se lit plus vite qu'un paragraphe ; évitez-le pour les listes ou tableaux simples.

```mermaid
flowchart LR
  A[Marché résolu] --> B{Observateurs ?}
  B -->|oui| C[Files d'attente des tâches] --> D[Worker en éventail]
```

Les diagrammes s'affichent dans le thème sombre ECC avec la palette d'accentuation. Mermaid se charge dans le navigateur depuis un CDN épinglé ; s'il est indisponible (hors ligne), le bloc se dégrade en affichant son code source, donc la révision n'est jamais bloquée. Pointez un miroir local vers ECC_PLAN_CANVAS_MERMAID_URL pour une utilisation en environnement isolé.

Règles

• Les artefacts Markdown s'affichent dans le modèle de plan ECC (y compris les blocs Mermaid) ; les artefacts .html s'affichent tels quels avec la couche d'annotation injectée. Pour les conseils de création HTML, utilisez les compétences frontend-design-direction et artifact-design.
• Modifiez le fichier artefact pour réviser — le canevas se recharge en direct lors de l'enregistrement. Ne réexécutez jamais open pour rafraîchir.
• {"status": "ended", "endedBy": "user"} (ou sessionEnded: true sur un lot de retours) signifie que l'utilisateur a fermé la révision : arrêtez de scruter, livrez les mises à jour restantes dans le chat, et ne rouvrez pas. Un simple open sur cette session est refusé ; passez --reopen uniquement lorsque l'utilisateur demande de reprendre.
• Les ressources associées (images, CSS) doivent se trouver à côté de l'artefact et être référencées par chemin relatif.
• Le serveur est en boucle locale uniquement et se ferme après 30 minutes d'inactivité (ECC_PLAN_CANVAS_IDLE_MS) ; stop l'arrête explicitement. L'état se trouve dans ~/.claude/plan-canvas/ (ECC_PLAN_CANVAS_STATE_DIR).

Exemples

Flux d'approbation du plan — /plan écrit .claude/plans/notifications.plan.md et doit ATTENDRE la confirmation :

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
# le plan est confirmé — commencez l'implémentation

Boucle de révision — les retours arrivent, vous modifiez le fichier, répondez, continuez à écouter :

# await a renvoyé des annotations → modifiez le .plan.md (le canevas se recharge en direct)
ecc-plan-canvas await <fichier> --reply "Tableau des risques retravaillé."
# → bloque à nouveau jusqu'à la prochaine réponse

Anti-patrons

• Scruter avec --timeout-ms dans une boucle. Cela existe pour les tests. Laissez plutôt le simple await tourner.
• Terminer votre tour sans await à l'écoute alors que la révision est encore ouverte. C'est le seul échec que l'humain vit comme "j'ai envoyé un message et rien ne s'est passé".
• Lire les retours mais répondre uniquement dans le terminal. L'humain regarde le canevas.
• Rouvrir après une fin initiée par l'utilisateur "juste pour montrer" quelque chose.
• Coller tout le plan dans le chat et ouvrir un canevas — choisissez le canevas et limitez le résumé du terminal à une ligne.
• Analyser le chat du canevas à partir des fichiers d'état — tout ce dont vous avez besoin arrive via await.

Notes de conception et origine : docs/design/plan-canvas.md.