Plan Canvas

Loop de revisão para planos e artefatos visuais: você escreve o artefato, o humano o revisa no navegador — anotando o elemento exato que ele quer dizer, conversando e entregando um veredito de Aprovar plano / Solicitar alterações — enquanto você bloqueia em uma única chamada CLI que retorna o feedback dele como JSON.

Inspirado por lavish-axi; reconstruído nativamente em ECC em torno do portão de confirmação /plan, com zero dependências.

Quando Usar

• Você acabou de escrever um artefato de plano (.claude/plans/*.plan.md de /plan) e precisa da decisão CONFIRMAR/aprovar — o veredito do canvas substitui um "sim/prosseguir" digitado.
• O usuário deve apontar para o que mudar: revisando designs, comparações, relatórios ou qualquer artefato local .md / .html.
• O usuário pede por /plan-canvas, uma revisão visual ou "abrir no navegador".

NÃO use para: revisão de código de diffs (/code-review), execução de aplicativos web ou URLs remotos. O canvas serve apenas para arquivos de artefatos locais.

Como Funciona

Invoque a CLI como ecc-plan-canvas — o binário enviado pelo pacote ecc-universal (no PATH após uma instalação global/plugin; node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js" também funciona para instalações de plugin). Execute-o a partir do projeto que você está revisando; ele funciona de qualquer diretório de trabalho. Ele gerencia um servidor de loopback desanexado (127.0.0.1:4517) compartilhado por todas as sessões, com chave pelo caminho do artefato — sem IDs de sessão para rastrear.

O fluxo de trabalho é um loop simples de CLI mais JSON, então é agnóstico ao modelo e ao harness: qualquer agente que possa executar um comando shell e ler stdout o conduz da mesma forma (Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot). Acione-o como seu harness expõe as habilidades — por exemplo, /plan-canvas no Claude Code, $plan-canvas no Codex — ou apenas execute os comandos ecc-plan-canvas diretamente.

# 1. Open the artifact in the user's browser (returns immediately)
ecc-plan-canvas open .claude/plans/feature.plan.md

# 2. Block until the human responds. Leave running; re-run if interrupted:
#    queued feedback is never lost.
ecc-plan-canvas await .claude/plans/feature.plan.md

Fique escutando, ou o humano fala para uma cadeira vazia

O feedback só chega até você enquanto um await está realmente estacionado na sessão. Se a sua vez terminar sem nada escutando, a mensagem fica na fila e, do lado do humano do vidro, o envio parece não fazer nada.

Portanto, execute await como uma tarefa em segundo plano quando seu harness suportar uma (no Claude Code, uma chamada Bash com run_in_background: true). Ele sai no momento em que o feedback chega e o harness entrega o JSON, o que mantém o loop vivo entre as voltas em vez de morrer com a chamada em primeiro plano. Um await em primeiro plano também funciona, mas apenas até que o harness o limite por tempo.

Existem dois mecanismos de segurança, e nenhum deles é desculpa para pular o acima:

• ecc-plan-canvas pending lista o feedback enfileirado sem um ouvinte. Verifique-o sempre que tiver dúvidas se perdeu algo.
• O hook stop:plan-canvas-pending impede que sua vez termine enquanto o feedback do canvas não for entregue, e entrega as mensagens para você. Se você estiver lendo feedback desse hook, você parou de escutar cedo demais.

await imprime JSON quando o humano age:

{
  "status": "feedback",
  "items": [
    { "kind": "annotation", "text": "Split this into two phases",
      "anchor": { "selector": "h2:nth-of-type(3)", "tag": "h2", "snippet": "Phase 2: Migration" } },
    { "kind": "verdict", "verdict": "request-changes" }
  ]
}

• kind: "chat" — mensagem livre; responda no canvas, não no terminal.
• kind: "annotation" — feedback ancorado a um elemento (anchor.selector, anchor.snippet mostram o que eles apontaram; anchor.textRange.text quando eles destacaram uma passagem).
• kind: "verdict" — approve significa que o plano está CONFIRMADO: pare de sondar, encerre a sessão e comece a implementar. request-changes significa revisar o artefato (o canvas o recarrega ao vivo) e manter o loop em andamento.

3. Sempre responda no canvas, depois continue escutando. Um comando faz ambos:

ecc-plan-canvas await <file> --reply "Split Phase 2 as requested. Take a look."

Cada mensagem humana recebe uma resposta no canvas, mesmo um texto curto como "Entendido, reescrevendo a tabela de riscos agora." O silêncio no painel de chat é indistinguível de um canvas quebrado, que é exatamente a falha que este loop existe para evitar. Responda lá, não apenas no terminal.

Enquanto você trabalha, mantenha o chat honesto com o indicador de atividade:

…