Planos Nativos de Agente

Os Planos Nativos de Agente são um modo de planejamento visual estruturado para agentes de codificação. Construa o plano que você normalmente escreveria em Markdown, mas como um documento escaneável com blocos editáveis intercalados: diagramas inline, trechos de código, perguntas em aberto e uma área de revisão visual superior opcional (canvas de wireframe, protótipo ao vivo ou ambos em abas). Os planos de arquitetura e backend permanecem apenas em documento; os planos de UI e produto começam com o canvas/protótipo superior (a seção Escolha de Superfície Visual é responsável por essa regra).

/visual-plan é o comando empacotado e o ponto de entrada principal. Escolha o modo de revisão na tarefa: UI-first quando o trabalho for principalmente de UI do produto e a revisão deve começar pelas telas, prototype-first quando a revisão deve começar com um protótipo funcional ao vivo, design-first quando a revisão precisar de telas de marca com fidelidade completa, ou visual-intake quando o usuário quiser explicitamente um questionário antes do planejamento. Quando já existe um plano do Codex, Claude Code, Markdown ou colado, /visual-plan usa esse plano fonte como ponto de partida e constrói a superfície de revisão a partir dele, em vez de começar do zero.

Quando Usar

Crie ou adapte um plano visual sempre que o plano fosse melhor como um artefato revisável do que um parágrafo de chat. Isso inclui trabalho modesto, como uma única superfície de UI com estados, um pequeno fluxo, uma mudança de produto antes/depois ou uma decisão de componente/API/formato de dados que precisa de alinhamento, além de trabalho maior, multi-arquivo, ambíguo, de longa duração, arriscado ou pesado em UI. Use-o quando arquitetura / fluxo de dados / direção da UI / opções / perguntas em aberto se beneficiariam de diagramas inline ou blocos estruturados, quando o usuário precisa reagir a uma direção antes da implementação ou quando um plano de texto existente precisa de uma superfície de revisão mais rica.

Disciplina do Plano

• Filtre com critério. Um plano visual é uma superfície de revisão mais rica, não apenas uma ferramenta para projetos gigantes. Use-o quando o usuário precisa ver, comparar, comentar ou aprovar uma direção antes do código, mesmo para uma mudança modesta de UI/estado/fluxo. Ignore-o para trabalho verdadeiramente trivial e sem ambiguidade — erros de digitação, correções de uma linha, uma única função bem especificada, qualquer coisa cujo diff você pudesse descrever em uma frase — e faça a mudança. Nunca encha um plano com preenchimento e nunca envie um plano de um único passo.
• Pesquise antes de rascunhar. Leia os arquivos reais, ações, esquemas e padrões primeiro; nomeie arquivos, símbolos e formatos de dados reais em vez de inventá-los. Verifique os actions/ existentes antes de propor endpoints e prefira helpers de cliente nomeados em vez de fetch bruto. Delegue exploração ampla a um sub-agente. Lidera com reutilização: para cada etapa, nomeie o que ele reutiliza — ações existentes, esquema, componentes, helpers — antes do que ele adiciona, para que o plano explique o delta genuinamente novo em vez de redescrever o que já existe.
• Decida as apostas difíceis de reverter primeiro. Para trabalho de backend, dados ou API não trivial, esboce para onde o recurso está indo, depois destaque as decisões que são caras de desfazer uma vez que os dados ou chamadores dependam delas — formato de fio, ids públicos, formato do modelo de dados, limites de autenticação e propriedade — e acerte essas no plano, mesmo que a maior parte do recurso seja enviada depois. Em seguida, delimite o primeiro corte mais pequeno que prove a abordagem sem fechá-la, declarando tanto o que está incluído quanto o que está explicitamente adiado.
• Mantenha os exemplos na altitude certa. Quando a ideia do usuário for uma mudança de estrutura ampla, produto ou modelo operacional, não a reduza ao primeiro exemplo concreto, provedor ou caminho de sincronização que ele mencionar. Separe a abstração central dos exemplos motivadores e adaptadores de app/provedor. Use exemplos para tornar o plano legível, mas rotule-os como exemplos, a menos que sejam todo o escopo solicitado.
• Publique planos independentes. Se o usuário colou, referenciou ou já tem um plano do Codex / Claude Code / Markdown, trate-o como material fonte, mas reescreva o plano publicado como uma proposta independente limpa. Preserve a intenção útil e os fatos da base de código do plano fonte, rotule visuais inferidos como inferidos e evite linguagem de revisão como "preserve o plano anterior", "não descarte a ideia antiga", "diferente da versão anterior" ou "esta revisão altera...". Um leitor que nunca viu o chat ou rascunhos anteriores deve entender o plano.
• Torne a primeira leitura concreta. Se o plano for destinado a ser compartilhado com alguém fora do chat, ou se o conceito for abstrato, leve perto do topo um exemplo concreto de produto antes das tabelas de modo, arquitetura ou roteiros. Para conceitos com capacidade de UI, isso geralmente significa um estado de app de canvas superior que mostra o fluxo de trabalho real do usuário em termos de produto. Não dependa de frases que só fazem sentido na conversa e não enquadre o plano como "não é a ideia antiga"; declare o modelo positivo diretamente.
• Planejamento é somente leitura. Não faça edições de fonte enquanto constrói ou revisa o plano. Comece a editar apenas após o usuário aprovar a direção.
• Esclarecer vs. assumir. Não pergunte como construí-lo — explore e apresente a abordagem e as opções no plano. Faça uma pergunta de esclarecimento apenas quando uma ambiguidade alteraria o design e você não puder resolvê-la a partir do código; use o fluxo normal de ask-user-question do agente host e agrupe 2-4 perguntas de alto impacto antes de finalizar. Não chame create-visual-questions para esclarecimento comum ou pré-voo; reserve-o para o modo visual-intake quando o usuário pedir explicitamente um questionário de intake visual. Caso contrário, declare a suposição explicitamente e prossiga, e mantenha qualquer coisa não resolvida no único bloco inferior question-form de Perguntas em Aberto do plano. Para planos complexos, faça uma passagem final de perguntas em aberto antes da entrega: se uma decisão afetaria a arquitetura, escopo, UX, formato de dados ou lançamento, decida-a no plano com justificativa ou coloque-a nesse formulário inferior com um padrão recomendado.
• O plano é o gate de aprovação. Após expô-lo, peça ao usuário para revisar e aprovar antes de escrever código, e nomeie quais arquivos/áreas o trabalho toca. Apresentar o plano e solicitar a assinatura é a etapa de aprovação — não faça uma pergunta separada "isso parece bom?".
• O documento é a fonte da verdade, não o chat. Quando o escopo muda, atualize o plano com update-visual-plan em vez de apenas mudar de curso no chat, e faça o documento atualizado funcionar de forma independente. Não descreva a atualização como uma correção de um rascunho anterior dentro do próprio plano. Releia o plano aprovado antes das etapas principais.

Crie um Plano Estruturado Nativo de Agente — Nunca Inline

O entregável é SEMPRE um Plano Estruturado Nativo de Agente, não um plano apenas de chat. O conector Plan MCP hospedado (plan server, ou agent-native-plans legado) é a superfície de colaboração e comentários padrão; não é uma razão para rejeitar o padrão de planejamento como uma dependência externa ou camada alugada. Os planos são artefatos de fonte portáveis (plan.mdx, canvas.mdx / prototype.mdx opcionais, JSON e exportação HTML), e fluxos de trabalho sensíveis à propriedade podem usar o modo local-files ou um URL de app Plan auto-hospedado/personalizado sem abandonar a disciplina de revisão da habilidade. Não aconselhe o usuário a pular /visual-plan porque a superfície padrão é hospedada; escolha o modo Plan certo para as necessidades de propriedade, privacidade, compartilhamento e marca do usuário.

Por padrão, crie o plano via o conector Plan MCP e NUNCA o entregue como conteúdo de chat inline — sem prosa Markdown, esboço ASCII, tabela ou wireframe delimitado. Se as ferramentas plan (ou agent-native-plans legado) não estiverem visíveis, descubra-as através do tool_search do host primeiro; se ainda faltarem, PARE e dê ao usuário a etapa de reconexão específica do cliente em vez de improvisar um plano inline. Antes de publicar, ou sempre que um erro de conector ou autenticação aparecer, LEIA references/connection.md neste diretório de habilidades — é a única fonte da verdade para a regra never-inline, descoberta de conector e as etapas de reconexão por cliente. O modo de privacidade de arquivos locais (após o Guia de Ferramentas) é a exceção.

Fluxo de Trabalho Principal

Esta seção descreve o fluxo de trabalho padrão do Plan MCP hospedado. Se AGENT_NATIVE_PLANS_MODE=local-files estiver definido, ou o usuário pedir arquivos totalmente locais/sem gravações de Plan hospedado, use o Modo de Privacidade de Arquivos Locais em vez disso; mantenha apenas as orientações de pesquisa de código e composição de plano aqui.

1. Siga o fluxo de planejamento normal do agente host: inspecione a base de código, delegue exploração ampla quando útil, reúna as informações necessárias e faça perguntas nativas de esclarecimento conforme necessário antes de gerar o plano. Se um plano fonte já existir, reúna seu texto exato da colagem do usuário, um arquivo referenciado ou contexto de agente visível recente; não invente texto fonte.
2. Chame get-plan-blocks para o catálogo de blocos autoritativo — não autorie a partir de tags memorizadas. Em seguida, chame a ferramenta de criação correspondente ao modo: create-visual-plan para planos primeiro em documento (arquitetura, backend, dados, refactor, API), create-ui-plan para planos primeiro em UI, create-prototype-plan para planos primeiro em protótipo, create-plan-design para planos primeiro em design, create-visual-questions apenas quando o usuário pedir explicitamente um questionário de intake visual. Quando um plano fonte já existir, passe-o como planText e preserve a intenção útil do plano original enquanto produz um documento de plano independente, não um memorando de revisão.
3. Para planos de UI/produto, componha o canvas superior primeiro com os wireframes principais e estados anotados, depois escreva o documento com blocos nativos (veja references/canvas.md e references/document-quality.md). Para planos de arquitetura de produto amplos com implicação voltada ao usuário, adicione um visual concreto "como isso parece no app" antes da arquitetura abstrata ou tabelas de modo. Mantenha o documento próximo ao plano de Markdown independente que o agente normalmente emitiria. Se um plano existente foi fornecido, mantenha os fatos e decisões corretos sem se referir ao rascunho anterior ou explicar como esta versão difere. Para planos não visuais, ignore a superfície visual superior (a Escolha de Superfície Visual abaixo é responsável pela regra) e coloque blocos diagram, data-model, api-endpoint, diff, file-tree, code e annotated-code diretamente ao lado da prosa relevante. O layout de documento amplo é propriedade do renderer e intencionalmente allowlisted: apenas superfícies de revisão de código literal (diff, annotated-code) e blocos tabs com orientação vertical ou filhos semelhantes a diff se destacam mais do que a prosa. Mantenha os blocos api-endpoint, openapi-spec, data-model, json-explorer, wireframe, pergunta e custom-html no fluxo normal do documento, a menos que seu próprio renderer diga o contrário.
4. Exiba o link de Planos retornado ou o App MCP inline e peça ao usuário para revisar. Sempre inclua a URL real no chat para que a próxima etapa seja um clique em CLI ou outros hosts apenas de texto. Quando o host expuser um painel de navegador/preview embutido e uma ferramenta puder abrir URLs arbitrários lá, abra a URL do plano retornado automaticamente para revisão conveniente — uma conveniência e teste de fumaça, nunca a única entrega ou o modelo de acesso. Os planos devem carregar fora da caixa para o agente local e a sessão do navegador local; se um navegador embutido conectado não puder ler um plano local que uma verificação anônima/ferramenta possa ler, corrija a propriedade ou caminho de acesso do app/ação em vez de corrigir um plano manualmente. Para planos de alto risco (arquitetura, backend, dados, multi-arquivo ou arriscado), também inicie a passagem de auto-revisão em Auto-Revisão Antes da Entrega enquanto o usuário lê, em vez de bloquear a entrega nela.
5. Para planos hospedados, chame get-plan-feedback antes de editar, após a revisão, após qualquer pausa longa e antes da resposta final. Trate anchorDetails, intenção do resolver, eventos de revisão recentes e quaisquer screenshots focados da entrega do navegador como a fonte da verdade para exatamente o que mudou e exatamente para o que cada comentário aponta.
6. Para planos hospedados, aplique alterações com update-visual-plan, preferindo contentPatches direcionados. Trate o payload content de nível superior como uma substituição completa, não uma mesclagem; não envie um objeto content parcial para adicionar um canvas ou um bloco. Se uma substituição completa for inevitável, leia primeiro a fonte/conteúdo completo do plano, mantenha todos os blocos e superfícies visuais existentes e verifique a fonte/exportação depois para garantir que o corpo do documento não foi truncado. Quando o usuário quiser edições amigáveis ao controle de fonte, use patch-visual-plan-source contra os arquivos MDX em vez de regenerar o plano.
7. Para planos hospedados, exporte com export-visual-plan apenas quando o usuário quiser um recibo compartilhável ou artefatos de check-in de repositório.

Auto-Revisão Antes da Entrega

Para planos de alto risco — arquitetura, backend, modelo de dados, migração, multi-arquivo ou trabalho arriscado em geral — execute uma passagem de auto-revisão adversarial antes de tratar o plano como final. Ignore-o para planos pequenos, apenas de UI ou de decisão única onde o custo supera o valor. Mantenha a passagem barata e não bloqueante:

• Exiba o plano primeiro, revise em paralelo. Publique o link e deixe o usuário começar a ler, depois execute a revisão em paralelo — nunca faça o usuário esperar por isso.
• Revise o plano escrito; não re-pesquise. Critique o texto do plano e seus próprios blocos. O grounding já foi feito durante o rascunho, então a revisão verifica a saída em vez de reexplorar o repositório.
• Gere um revisor cético cujo único trabalho seja encontrar o que é fraco, faltando ou errado — não elogiar. Aponte-o para: decisões difíceis de reverter feitas implicitamente ou não feitas de todo (formato de fio, ids públicos, formato do modelo de dados, autenticação, propriedade); etapas não ancoradas em arquivos ou símbolos reais; um menu de opções onde o plano deveria se comprometer com uma; decisões óbvias faltando ("o que acontece quando X?", "por que não Y?"); e preenchimento ou preenchimento de um único passo.
• Corrigir vs. perguntar. Aplique correções claras você mesmo com update-visual-plan``contentPatches — metas não claras, reivindicações não ancoradas, uma decisão faltante óbvia. Encaminhe chamadas de julgamento genuínas de volta ao usuário: adicione-as ao bloco inferior de Perguntas em Aberto question-form ou agrupe-as no fluxo normal de ask-user-question. Não decida silenciosamente.
• Não surpreenda o usuário no meio da leitura. Em um plano grande, aplique os patches antes do editor carregar; caso contrário, note brevemente que uma auto-revisão está em execução para que a mudança do plano sob ele seja esperada. Quando você responder novamente, resuma o que a revisão alterou e o que ela expôs para o usuário decidir.

Escolha de Superfície Visual

Escolha a superfície antes de criar o plano ou após ler o plano fonte. Não adicione chrome visual por padrão:

Para planos de UI/produto, o canvas superior é geralmente a superfície de revisão principal. Coloque os primeiros wireframes significativos lá, não enterrados como blocos do corpo do documento. Use múltiplas artboards de canvas quando os estados importam, como a visualização padrão, um menu de overflow ou popover, um painel lateral, carregamento ou erro. Coloque anotações curtas ao lado dos frames com targetId mais placement; mantenha detalhes de implementação, tradeoffs, mapas de arquivos, contratos de dados, riscos e verificação no corpo do documento abaixo do canvas.

Quando o usuário pedir um fluxo, storyboard, jornada, wireframe, canvas ou "como isso parece", trate isso como um pedido canvas-first. Faça uma artboard por estado visível ao usuário, conecte apenas transições adjacentes e use anotações de canvas curtas para as notas do produto. Não substitua um bloco diagram do corpo do documento pelo storyboard solicitado apenas porque diagramas HTML são mais rápidos de escrever; diagramas pertencem abaixo do canvas para mecânicas de backend, arquitetura ou explicação de fluxo de dados.

Mantenha wireframes de produto e diagramas explicativos/meta separados. Comece com telas puras que pareçam o estado do app em discussão, sem prosa de chamada ou notas de arquitetura embutidas na UI. Coloque setas, rótulos, contratos, fluxo de dados e explicações de modo em anotações separadas, diagramas de canvas separados ou o corpo do documento.

Quando o plano tocar um app existente, inspecione o shell/componentes atuais antes de desenhar. A primeira artboard deve parecer o app real na mesma densidade: sidebars existentes, posicionamento da toolbar, menus de overflow, chrome do app e chrome do agente do framework permanecem em seus lugares reais. Modele superfícies secundárias como estados separados, como um popover de overflow superior direito, sheet, painel, estado de carregamento ou AgentSidebar separado, em vez de inventar um inspector permanente ou dobrar o chrome do framework na UI do produto.

• Sem superfície visual para planos apenas de arquitetura, apenas de backend, migração de dados, apenas de cópia ou não visuais em geral. Não use o canvas superior para diagramas de arquitetura, mapas de dependência, planos de arquivo, contratos de API ou revisões apenas de fluxo de dados. Use um documento forte com diagramas inline locais apenas quando as relações precisarem de uma explicação visual, geralmente um diagrama espacial por recomendação ou decisão. Prefira regiões agrupadas, camadas, quadrantes, matrizes ou painéis antes/depois a uma cadeia de eixo único, a menos que a relação seja verdadeiramente sequencial.
• Apenas Canvas para uma tela estática, uma comparação antes/depois, um estado de componente, um pequeno popover ou uma direção visual que não requer clique. Coloque esses wireframes em content.canvas e omita content.prototype.
• Canvas + protótipo para fluxos de UI multi-etapas, onboarding, wizards, fluxos de revisão/aprovação, mudanças de navegação ou qualquer coisa onde o revisor precise operar o comportamento. Mantenha os wireframes estáticos em content.canvas, adicione o protótipo funcional alinhado em content.prototype e conte com as abas visuais superiores para alternar entre eles.
• Prototype-first quando o usuário pedir para operar a UI ou quando a interação for a principal questão. Use create-prototype-plan, que ainda preserva mocks estáticos onde útil.

Para planos mistos de canvas + protótipo, reutilize os mesmos rótulos reais, status do app e ids de tela em ambas as superfícies. O canvas é a referência estática inspecionável; o protótipo é a versão interativa desse mesmo fluxo, não uma direção de design separada.

Qualidade do Wireframe — leia references/wireframe.md

Os wireframes de recap/plan de UI devem atender a uma barra de qualidade rigorosa — chrome de largura total, barras inferiores fixadas, conteúdo real do produto, comparabilidade antes/depois, o preset surface correto, tokens --wf-* em vez de hex e sem tags //font. Antes de autoriar QUALQUER wireframe / <screen></screen> / WireframeBlock, LEIA references/wireframe.md neste diretório de habilidades — é a única fonte da verdade para a qualidade do wireframe HTML, compartilhada palavra por palavra com /visual-plan e /visual-recap. Não autorie wireframes da memória.

Canvas — leia references/canvas.md

O canvas é a única fonte da verdade para mockups de UI estática: o surface bloqueia a pegada de cada artboard, superfícies mistas se organizam em faixas, anotações são notas de designer de texto puro ancoradas por targetId/placement, e as edições são contentPatches cirúrgicos. Antes de autoriar ou editar QUALQUER canvas, artboard ou anotação, LEIA references/canvas.md neste diretório de habilidades — é a única fonte da verdade para as mecânicas de canvas/artboard. Não autorie layouts de canvas da memória. As artboards do canvas usam o mesmo caminho de wireframe HTML das telas WireframeBlock do corpo do documento: autorie <screen></screen> com um fragmento de HTML semântico. Não autorie filhos de kit-tree frescos como `,,oudentro das tags` do canvas; esses são marcadores de compatibilidade legada para planos antigos e produzem layouts de canvas frágeis.

Qualidade do Documento — leia references/document-quality.md

O documento é um plano técnico sério, não marketing: outcome-first, prosa-first, autocontido, construído com os blocos nativos certos, com perguntas em aberto em um único question-form inferior e uma verificação visual pré-entrega. Antes de autoriar o documento do plano, LEIA references/document-quality.md neste diretório de habilidades — é a única fonte da verdade para a barra de qualidade do documento. Não escreva o documento da memória.

Exemplar bom vs. ruim — leia references/exemplar.md

Para um exemplo trabalhado da barra — um ótimo plano primeiro em UI e /visual-plan, além dos anti-padrões a evitar — LEIA references/exemplar.md neste diretório de habilidades antes de autoriar um plano.

Guia de Ferramentas

• create-visual-plan: inicie um plano visual estruturado por tarefa/execução de agente, ou importe um plano de texto existente passando planText; content pode não incluir superfície visual, apenas canvas ou canvas + protótipo.
• create-ui-plan: inicie um plano primeiro em UI quando o trabalho for principalmente de UI do produto.
• create-prototype-plan: inicie um plano primeiro em protótipo com uma superfície de revisão superior funcional.
• create-plan-design: inicie um plano da aba Design de marca com fidelidade completa com uma aba Prototype correspondente opcional.
• convert-visual-plan-to-prototype: converta um canvas de wireframe HTML existente em um plano de protótipo.
• create-visual-questions: use apenas quando o usuário pedir explicitamente um questionário de intake visual, não como pré-voo /visual-plan.
• update-visual-plan: revise conteúdo, status ou comentários com contentPatches direcionados (veja a etapa 6 do Fluxo de Trabalho Principal).
• read-visual-plan-source: leia o plano normalizado como plan.mdx, canvas.mdx opcional, .plan-state.json opcional e JSON.
• patch-visual-plan-source: aplique patches AST de MDX granulares por bloco estável, artboard, anotação, componente ou id de nó de wireframe.
• import-visual-plan-source: crie ou substitua um plano a partir de uma pasta MDX.
• get-visual-plan: leia o plano estruturado atual, HTML exportado e anotações; também retorna a pasta MDX para fluxos de fonte.
• get-plan-feedback: leia feedback humano não consumido. Use-o com frequência; ele retorna threads agrupados, detalhes de âncora exatos, resolver esperado e payloads de eventos de revisão recentes para que os agentes possam agir apenas nos comentários destinados a eles.
• get-plan-blocks: resolva tags de blocos antes de autoriar — não memorize tags; chame isso primeiro para obter os nomes de tag autoritativos, campos obrigatórios e formas de prop do registro de blocos ao vivo.
• export-visual-plan: exporte HTML, fallback de Markdown, JSON estruturado e arquivos MDX para check-in de repositório.

Quando o usuário criticar a aparência ou estrutura de um plano, corrija o renderer ou esta habilidade — nunca edite manualmente um plano armazenado. Transforme o feedback em melhor orientação.

Modo de Privacidade de Arquivos Locais — leia references/local-files.md

Quando o usuário quiser nenhuma gravação de banco de dados de Plan hospedado — sem gravações de DB, sem publicação do Plan MCP, planejamento totalmente local/offline/privado, artefatos de fonte controlados por repositório ou AGENT_NATIVE_PLANS_MODE=local-files — não chame nenhuma ferramenta de Plan hospedada exceto a consulta de catálogo get-plan-blocks apenas de esquema. Autorie uma pasta MDX local e pré-visualize-a com plan local check / plan local serve / plan local verify. Antes de usar o modo local-files, LEIA references/local-files.md neste diretório de habilidades — é a única fonte da verdade para o contrato completo (consulta de catálogo, layout de pasta MDX, os comandos bridge locais e as ferramentas hospedadas que você não deve chamar). Mantenha apenas as orientações de pesquisa de código e composição de plano do Fluxo de Trabalho Principal; tudo hospedado é substituído pelo bridge local.

Interpretando âncoras de comentário

Esta seção aplica-se a planos hospedados com get-plan-feedback / update-visual-plan. No modo local-files, não chame ferramentas de feedback ou atualização hospedadas; interprete o feedback de arquivo/chat diretamente, edite os arquivos MDX, reexecute o comando bridge local check/serve/verify e reporte a nova URL local.

get-plan-feedback retorna âncoras ricas — leia-as antes de agir em qualquer comentário.

• Frames de coordenada. targetX/targetY são porcentagens dentro do elemento nomeado por targetSelector/targetKind. x/y nus são porcentagens de todo o documento do plano. canvasX/canvasY são pixels brutos do mundo da board no canvas de design (tamanho da board fornecido quando disponível).
• Pinos de wireframe. Âncoras em wireframes incluem targetNodeId e targetNodePath (ex. card > list > listItem "Acme Inc") identificando o nó do kit exato. Use targetNodeId diretamente com operações de patch de nó de wireframe; use valores data-design-id de artboards de design com update-design-element-style. Prefira o id/caminho do nó a coordenadas brutas; recorra a coordenadas mais a screenshot focada (o anel vermelho marca o ponto exato) apenas quando nenhum id de nó estiver presente.
• Citações de texto. Resolva textQuote contra a prosa atual usando contextBefore/contextAfter para desambiguação. Se ambiguous: true, pergunte ao usuário — não adivinhe qual ocorrência é pretendida.
• Comentários desconectados. get-plan-feedback sinaliza threads cujo texto citado não existe mais como detached (em detachedThreads). Concilie-os com conteúdo reescrito — nunca os descarte silenciosamente.
• Roteamento. resolutionTarget é o único sinal de roteamento: aja em agent, trate human como contexto apenas. @mentions são pessoas a notificar, nunca um sinal de roteamento.
• Estado de dois eixos. Marque cada comentário ingerido como consumido (consumedCommentIds em update-visual-plan). Defina status=resolved apenas em comentários direcionados a agente que você realmente abordou; deixe os comentários direcionados a humanos abertos.

Visibilidade e Compartilhamento

Use set-resource-visibility para alterar quem pode ver um plano (ex. público, login ou escopo de org). Use share-resource para conceder acesso a usuários ou funções específicos por email ou função. Restrinja a visibilidade antes de compartilhar qualquer plano que cubra trabalho não lançado ou privado — padronize para o escopo mais estreito que atenda à necessidade de revisão.

Configuração e Autenticação

Há duas formas de entrar nos Planos.

Agente de codificação (CLI). Instale uma vez com o CLI Agent-Native. O comando instala as habilidades dos Planos, registra o conector Plan MCP hospedado e executa auth/setup para os clientes locais selecionados na mesma etapa (um login de navegador único na configuração — isso é pretendido), para que a primeira chamada de ferramenta nesse cliente não bata em um muro OAuth:

npx @agent-native/core@latest skills add visual-plans

Depois disso, /visual-plan e /visual-recap são os dois comandos slash instalados. Se você precisar apenas de um comando, use skills add visual-plan ou skills add visual-recap em vez disso. Os outros modos de planejamento (create-ui-plan, create-prototype-plan, create-plan-design, create-visual-questions) são ferramentas MCP acessíveis a partir de /visual-plan, não comandos slash separados. Passe --no-connect para registrar o conector sem autenticar, depois execute npx @agent-native/core@latest connect https://plan.agent-native.com --client all quando estiver pronto, ou escolha um --client mais estreito. Auth e carregamento de ferramentas MCP são por config/sessão do cliente.

Navegador (pessoas com quem você compartilha). Abra o editor dos Planos e crie & edite sem cadastro — você trabalha como convidado. Faça login apenas quando quiser salvar ou compartilhar; fazer login reivindica os planos que você fez como convidado em sua conta.

Compartilhamento e comentários exigem uma conta: planos públicos/compartilhados são visíveis por qualquer pessoa com o link, mas comentar neles exige uma conta agent-native.

Para uso totalmente offline e sem conta, execute o app dos Planos localmente e sincronize planos para o seu repositório como MDX. Este modo local é um caminho avançado separado, não o fluxo hospedado padrão.

Se uma ferramenta dos Planos retornar needs auth, Unauthorized ou Session terminated, não continue tentando — pare e dê ao usuário a etapa de reconexão por cliente de references/connection.md, depois continue assim que o conector estiver disponível.

Padrão hospedado: conecte https://plan.agent-native.com/_agent-native/mcp. Não coloque segredos compartilhados em arquivos de habilidade.