Maison

Skill

Productivité et flux de travail

visual-plan

BuilderIO/skills

Transformez vos plans textuels en documents visuels interactifs comprenant des schémas, des extraits de code et des zones de révision destinées aux agents de codage.

...Développer tout

Heure mise à jour 6 septembre 2026

# diagrams # agent native plans # code snippets # plan documentation # plan mcp # review surface # visual planning

Plans natifs pour agents

Les plans natifs pour agents constituent un mode de planification visuelle structurée destiné à la programmation d’agents. Élaborez le plan que vous rédigeriez normalement en Markdown, mais sous la forme d'un document facile à parcourir comportant des blocs modifiables : diagrammes intégrés, extraits de code, questions ouvertes et, en option, une zone de révision visuelle en haut de la page (canevas de wireframe, prototype interactif ou les deux dans des onglets). Les plans d'architecture et de backend restent sous forme de document uniquement ; les plans d’interface utilisateur et de produit commencent par le canevas/prototype en haut (la section « Visual Surface Choice » définit cette règle).

/visual-plan est la commande intégrée et le point d’entrée principal. Choisissez le mode de révision à partir de la tâche : « UI-first » lorsque le travail porte principalement sur l’interface utilisateur du produit et que la révision doit commencer par les écrans, « prototype-first » lorsque la révision doit commencer par un prototype fonctionnel en direct, « design-first » lorsque la révision nécessite des écrans à haute fidélité à l’image de la marque, ou « visual-intake » lorsque l’utilisateur souhaite explicitement un questionnaire avant la planification. Lorsqu’un Codex, un Claude Code, un Markdown ou un plan collé existe déjà, /visual-plan utilise ce plan source comme point de départ et construit l’interface de révision à partir de celui-ci au lieu de repartir de zéro.

Quand l’utiliser

Créez ou adaptez un plan visuel chaque fois qu’il vaut mieux que le plan prenne la forme d’un artefact révisable plutôt que d’un paragraphe de discussion. Cela inclut des travaux modestes tels qu’une interface utilisateur unique avec différents états, un petit workflow, une évolution de produit « avant/après », ou une décision concernant un composant, une API ou la structure des données nécessitant une harmonisation, ainsi que des travaux plus importants impliquant plusieurs fichiers, ambiguës, de longue durée, risquées ou comportant une interface utilisateur complexe. Utilisez-le lorsque l’architecture, le flux de données, l’orientation de l’interface utilisateur, les options ou les questions en suspens gagneraient à être illustrés par des schémas intégrés ou des blocs structurés, lorsque l’utilisateur doit se prononcer sur une orientation avant que vous ne la mettiez en œuvre, ou lorsqu’un plan textuel existant nécessite une surface de révision plus riche.

Discipline de planification

Validez avec discernement. Un plan visuel offre une surface de révision plus riche ; ce n’est pas seulement un outil réservé aux projets gigantesques. Utilisez-le lorsque l’utilisateur doit voir, comparer, commenter ou approuver une orientation avant l’écriture du code, même pour un changement modeste d’interface utilisateur, d’état ou de workflow . Évitez-le pour les tâches vraiment insignifiantes et sans ambiguïté — fautes de frappe, corrections d’une ligne, une seule fonction bien spécifiée, tout ce dont vous pourriez décrire le diff en une seule phrase — et appliquez simplement la modification. Ne remplissez jamais un plan de contenu superflu et ne livrez jamais un plan en une seule étape.
Faites des recherches avant de rédiger votre ébauche. Lisez d’abord les fichiers, actions, schémas et modèles réels ; nommez des fichiers, symboles et structures de données existants au lieu de les inventer. Vérifiez les actions/ avant de proposer des points de terminaison et privilégiez les aides client nommées plutôt que les récupérations brutes. Déléguez l’exploration approfondie à un sous-agent. Misez sur la réutilisation : pour chaque étape, précisez ce qu’elle réutilise — actions existantes, schémas, composants, aides — avant ce qu’elle ajoute, afin que le plan explique le véritable delta au lieu de redécrire ce qui existe déjà.
Déterminez d’abord les choix difficiles à inverser. Pour les travaux non triviaux liés au backend, aux données ou aux API , esquissez la direction que prendra la fonctionnalité, puis identifiez les décisions qui sont coûteuses à annuler une fois que les données ou les appelants en dépendent — format de transmission, identifiants publics, structure du modèle de données, limites d’authentification et de propriété — et veillez à ce qu’elles soient correctement définies dans le plan, même si la majeure partie de la fonctionnalité est livrée plus tard. Définissez ensuite la portée de la première version minimale qui valide l’approche sans la figer, en précisant à la fois ce qui est inclus et ce qui est explicitement reporté.
Gardez les exemples à la bonne échelle. Lorsque l’idée de l’utilisateur porte sur un changement global de cadre, de produit ou de modèle opérationnel, ne la réduisez pas au premier exemple concret, fournisseur ou chemin de synchronisation qu’il mentionne. Séparez l’abstraction de base des exemples illustratifs et des adaptateurs d’application/de fournisseur. Utilisez des exemples pour rendre le plan lisible, mais identifiez-les clairement comme tels, sauf s’ils constituent l’intégralité du périmètre demandé.
Publiez des plans autonomes. Si l’utilisateur a collé, référencé ou dispose déjà d’un plan au format Codex / Claude Code / Markdown, traitez-le comme une source, mais réécrivez le plan publié sous la forme d’une proposition autonome et épurée. Conservez l’intention utile et les faits relatifs au code source du plan d’origine, indiquez clairement que les éléments visuels sont des déductions et évitez les formulations de révision telles que « conserver le plan précédent », « ne pas abandonner l’ancienne idée », « contrairement à la version précédente » ou « cette révision modifie… ». Un lecteur qui n’a jamais vu la discussion ou les versions préliminaires doit pouvoir comprendre le plan.
Rendez la première lecture concrète. Si le plan est destiné à être partagé avec une personne extérieure à la discussion, ou si le concept est abstrait, commencez dès le début par un exemple concret de produit avant d’aborder les tableaux de mode, l’architecture ou les feuilles de route. Pour les les concepts liés à l’interface utilisateur, cela signifie généralement un état d’application sur le canevas supérieur qui illustre le véritable flux de travail de l’utilisateur en termes de produit. Ne vous fiez pas à des expressions qui n’ont de sens que dans une conversation, et ne présentez pas le plan comme « ce n’est pas l’ancienne idée » ; énoncez directement le modèle positif.
La planification est en lecture seule. N’apportez aucune modification au fichier source pendant l’élaboration ou la révision du plan. Ne commencez à modifier le fichier qu’une fois que l’utilisateur a approuvé l’orientation choisie.
Précisez plutôt que de supposer. Ne demandez pas comment le réaliser : explorez et présentez l’ approche et les options dans le plan. Ne posez une question de clarification que lorsqu’une ambiguïté modifierait la conception et que vous ne pouvez pas la résoudre à partir du code ; utilisez le flux normal de l’agent hôte pour poser des questions à l’utilisateur et regroupez 2 à 4 questions à fort impact avant de finaliser. N’invoquez pas create-visual-questions pour une clarification courante ou une vérification préalable ; réservez-le au mode de saisie visuelle lorsque l’utilisateur demande explicitement un questionnaire de saisie visuelle. Sinon, énoncez l’ hypothèse explicitement et poursuivez, en conservant tout ce qui n’est pas résolu dans le seul bloc « Questions ouvertes » question-form « Questions ouvertes » du plan. Pour les plans complexes, effectuez un dernier passage sur les questions ouvertes avant le transfert : si une décision est susceptible d’affecter l’architecture, la portée, l’expérience utilisateur, la structure des données ou le déploiement, soit intégrez-la dans le plan avec une justification, soit placez-la dans ce formulaire en bas de page avec une valeur par défaut recommandée.
Le plan constitue la porte d’approbation. Après l’avoir présenté, demandez à l’utilisateur de le relire et de l’approuver avant d’écrire le code, en précisant les fichiers ou domaines concernés par le travail. La présentation du plan et la demande de validation constituent l’étape d’approbation — ne posez pas de question distincte du type « Est-ce que cela vous semble correct ? ».
Le document est la source de référence, pas la discussion. Lorsque la portée évolue, mettez à jour le plan en update-visual-plan plutôt que de simplement changer de cap dans le chat, et veillez à ce que le document mis à jour soit autonome. Ne présentez pas la mise à jour comme une correction d’une version antérieure au sein même du plan. Relisez le plan approuvé avant toute étape majeure.

Créez un plan structuré natif de l’agent — jamais en ligne

Le livrable est TOUJOURS un plan structuré natif de l’agent, et non un plan basé uniquement sur le chat. Le connecteur MCP hébergé (plan serveur ou hérité agent-native-plans) est l’espace de collaboration et de commentaire par défaut ; ce n’est pas une raison pour rejeter le modèle de planification en le considérant comme une dépendance externe ou une couche louée. Les plans sont des artefacts source portables (plan.mdx, avec exportation facultative canvas.mdx / prototype.mdx, exportation au format JSON et HTML), et les workflows sensibles à la propriété peuvent utiliser le mode « fichiers locaux » ou l’URL d’une application de plan auto-hébergée/personnalisée sans renoncer à la discipline de révision de la compétence. Ne conseillez pas à l’utilisateur de passer outre /visual-plan sous prétexte que l’interface par défaut est hébergée ; choisissez le mode Plan adapté aux besoins de l’utilisateur en matière de propriété, de confidentialité, de partage et d’image de marque.

Par défaut, créez le plan via le connecteur Plan MCP et ne le transmettez JAMAIS sous forme de contenu intégré au chat — pas de texte en Markdown, de croquis ASCII, de tableau ou de maquette encadrée. Si le plan (ou les agent-native-plans) ne sont pas visibles, recherchez-les d’abord via le tool_search ; s’ils sont toujours absents, ARRÊTEZ-VOUS et indiquez à l’utilisateur la procédure de reconnexion spécifique au client plutôt que d’improviser un plan intégré. Avant la publication, ou dès qu’une erreur de connecteur ou d’authentification apparaît, CONSULTEZ references/connection.md ce répertoire de compétences — c’est la seule source de référence pour la règle « jamais en ligne », la découverte des connecteurs et les étapes de reconnexion propres à chaque client. Le mode de confidentialité des fichiers locaux (après les conseils sur les outils) constitue l’exception.

Workflow principal

Cette section décrit le workflow MCP par défaut pour les plans hébergés. Si AGENT_NATIVE_PLANS_MODE=local-files est activé, ou si l’utilisateur demande une gestion entièrement locale des fichiers/aucune écriture dans le Plan hébergé, utilisez plutôt le mode de confidentialité des fichiers locaux ; ne retenez ici que les conseils relatifs à l’analyse du code et à la composition du plan.

Suivez le flux de planification normal de l’agent hôte : inspectez la base de code, déléguez une exploration approfondie lorsque cela s’avère utile, rassemblez les informations nécessaires et posez des questions de clarification natives si nécessaire avant de générer le plan. Si un plan source existe déjà, récupérez son texte exact à partir du copier-coller de l’utilisateur, d’un fichier référencé ou du contexte récent visible de l’agent ; n’inventez pas de texte source.
Appelez get-plan-blocks le catalogue de blocs faisant autorité — ne créez pas à partir de balises mémorisées. Appelez ensuite l’outil de création adapté au mode : create-visual-plan pour les plans axés sur le document (architecture, backend, données, refactorisation, API), create-ui-plan pour les plans axés sur l’interface utilisateur, create-prototype-plan pour les plans axés sur le prototype, create-plan-design pour les plans axés sur la conception, create-visual-questions uniquement lorsque l’utilisateur demande explicitement un questionnaire de prise en charge visuel. Lorsqu’un plan source existe déjà, transmettez-le en planText et conservez l’intention utile du plan d’origine tout en produisant un document de plan autonome, et non une note de révision.
Pour les plans d’interface utilisateur/produit, composez d’abord le canevas principal avec les maquettes fonctionnelles principales et les états annotés, puis rédigez le document à l’aide de blocs natifs (voir references/canvas.md et references/document-quality.md). Pour les plans d’architecture produit généraux ayant des implications pour l’utilisateur, ajoutez une représentation visuelle concrète (« à quoi cela ressemble dans l’application ») avant l’architecture abstraite ou les tableaux de modes. Veillez à ce que le document reste proche du plan Markdown autonome que l’agent produirait normalement. Si un plan existant a été fourni, reprenez les faits et décisions pertinents sans faire référence à la version précédente ni expliquer en quoi cette version diffère. Pour les plans non visuels , ignorez la surface visuelle supérieure (la règle est définie ci-dessous dans « Choix de la surface visuelle ») et placez diagram, data-model, api-endpoint, diff, file-tree, code, et annotated-code blocs directement à côté du texte correspondant. La mise en page large du document relève de la responsabilité du moteur de rendu et est intentionnellement autorisée : seules les surfaces de révision de code littérales (diff, annotated-code) et les tabs blocs à orientation verticale ou comportant des éléments enfants de type « diff » s’étendent plus largement que le texte. Conservez api-endpoint, openapi-spec, data-model, json-explorer, wireframe, question et custom-html blocs dans le flux normal du document, sauf si leur propre moteur de rendu indique le contraire.
Affichez le lien « Plans » renvoyé ou l’application MCP intégrée et demandez à l’utilisateur de procéder à la révision. Incluez toujours l’URL réelle dans le chat afin que l’étape suivante consiste en un simple clic dans l’interface en ligne de commande (CLI) ou d’autres hôtes en mode texte uniquement. Lorsque l’hôte expose un navigateur intégré ou un panneau d’aperçu et qu’un outil peut y ouvrir des URL arbitraires, ouvrez automatiquement l’URL du plan renvoyée pour faciliter la vérification — il s’agit d’une commodité et d’un test de fonctionnement, jamais du seul moyen de transfert ou du modèle d’accès . Les plans doivent se charger automatiquement pour l’agent local et la session de navigateur locale ; si un navigateur intégré (après connexion) ne parvient pas à lire un plan local qu’une vérification anonyme ou via un outil peut lire, corrigez la propriété de l’application/de l’action ou le chemin d’accès plutôt que de modifier manuellement un seul plan. Pour les plans à enjeux élevés (architecture, back-end, données, multi-fichiers ou à risque), lancez également la phase d’auto-révision décrite dans « Auto-révision avant transfert » pendant que l’utilisateur lit le plan, au lieu de bloquer le transfert pour cette raison.
Pour les plans hébergés, appelez get-plan-feedback avant la modification, après la révision, après toute longue pause, et avant la réponse finale. Considérez anchorDetails, l’intention du résolveur, les événements de révision récents et toute capture d’écran ciblée issue du transfert du navigateur comme la source de vérité indiquant exactement ce qui a changé et ce à quoi chaque commentaire fait référence.
Pour les plans hébergés, appliquez les modifications avec update-visual-plan, en privilégiant les modifications ciblées contentPatches. Considérez la content comme un remplacement complet, et non comme une fusion ; n’ envoyez pas d’objet partiel content pour ajouter un canevas ou un seul bloc. Si un remplacement complet est inévitable, lisez d’abord la source/le contenu complet du plan, transférez chaque bloc et surface visuelle existants, puis vérifiez la source/l’exportation afin de vous assurer que le corps du document n’a pas été tronqué. Lorsque l’utilisateur souhaite des modifications compatibles avec le contrôle de source, utilisez patch-visual-plan-source les fichiers MDX plutôt que de régénérer le plan.
Pour les plans hébergés, n’exportez export-visual-plan uniquement lorsque l’utilisateur souhaite un justificatif partageable ou des artefacts d’archivage dans le référentiel.

Auto-révision avant la remise

Pour les plans à enjeux élevés — architecture, backend, modèle de données, migration, plans comportant plusieurs fichiers, ou tout autre travail à risque — effectuez une auto-révision critique avant de considérer le plan comme définitif. Ignorez cette étape pour les petits plans, ceux concernant uniquement l’interface utilisateur ou impliquant une seule décision, lorsque le coût dépasse la valeur ajoutée. Veillez à ce que cette étape soit peu coûteuse et ne bloque pas le processus :

présentez d’abord le plan, puis examinez-le en parallèle. Publiez le lien et laissez l’utilisateur commencer à lire, puis effectuez la révision en parallèle — ne faites jamais attendre l’utilisateur.
Révisez le plan écrit ; ne refaites pas de recherches. Critiquez le texte du plan et ses propres blocs. Le travail de fond a déjà été effectué lors de la rédaction, de sorte que la révision vérifie le résultat plutôt que de réexplorer le dépôt.
Désignez un réviseur sceptique dont la seule mission est de repérer ce qui est faible, manquant ou erroné — et non de faire des éloges. Qu’il se concentre sur : les décisions difficiles à inverser, prises de manière implicite ou pas du tout (format de câblage, identifiants publics, structure du modèle de données, authentification, propriété) ; des étapes qui ne s’appuient pas sur des fichiers ou des symboles réels ; une liste d’options alors que le plan devrait en retenir une seule ; des décisions manifestement manquantes (« que se passe-t-il quand X ? », « pourquoi pas Y ? ») ; et du remplissage ou des étapes superflues.
Corriger ou demander. Appliquez vous-même des corrections claires en utilisant update-visual-plan contentPatches — des objectifs vagues, des affirmations sans fondement, une décision manifestement manquante . Renvoyez plutôt les véritables prises de décision à l’utilisateur : ajoutez-les au bas question-form « Questions ouvertes » ou regroupez-les dans le flux normal de questions posées à l’utilisateur. Ne les décidez pas en silence.
Ne surprenez pas l’utilisateur en cours de lecture. Sur un plan de grande envergure, appliquez les corrections avant que l’éditeur ne se charge ; sinon, indiquez brièvement qu’une auto-révision est en cours et que le plan est donc susceptible de changer. Lors de votre prochaine réponse, résumez ce que la révision a modifié et ce qu’elle a mis en évidence pour que l’utilisateur puisse en décider.

Choix de la présentation visuelle

Choisissez l’interface avant de créer le plan ou après avoir lu le plan source. N’ ajoutez pas d’éléments visuels par défaut :

Pour les plans d’interface utilisateur ou de produit, le canevas supérieur est généralement la surface de révision principale. Placez-y les premiers wireframes significatifs, sans les noyer dans le corps du document. Utilisez plusieurs plans de travail lorsque les états ont de l’importance, comme la vue par défaut, un menu déroulant ou une fenêtre contextuelle, un panneau latéral, un chargement ou une erreur. Placez de brèves annotations à côté des cadres avec targetId plus placement; conservez les détails de mise en œuvre, les compromis, les mappages de fichiers, les contrats de données, les risques et la vérification dans le corps du document, sous le canevas.

Lorsque l’utilisateur demande un flux, un storyboard, un parcours, un wireframe, un canevas ou « à quoi cela ressemble », considérez cela comme une demande « canevas d’abord ». Créez un plan de travail par état visible par l’utilisateur, ne reliez que les transitions adjacentes et utilisez de brèves annotations sur le canevas pour les notes relatives au produit. Ne remplacez pas le bloc du corps du document diagram par le storyboard demandé simplement parce que les diagrammes HTML sont plus rapides à rédiger ; les diagrammes doivent figurer sous le canevas pour expliquer les mécanismes du backend, l’architecture ou les flux de données.

Séparez les maquettes fonctionnelles du produit des diagrammes explicatifs ou méta. Commencez par des écrans « purs » qui ressemblent à l’état de l’application en question, sans texte explicatif ni notes d’architecture intégrées à l’interface utilisateur. Placez les flèches, les libellés, les contraintes, les flux de données et les explications de mode dans des annotations distinctes, des diagrammes sur des canevas séparés, ou dans le corps du document.

Lorsque le projet concerne une application existante, examinez la structure et les composants actuels avant de commencer à dessiner. Le premier plan de travail doit ressembler à l’application réelle avec la même densité : les barres latérales existantes, l’emplacement de la barre d’outils, les menus de débordement, les éléments d’interface de l’application et les éléments d’interface du framework restent à leurs emplacements réels. Modélisez les surfaces secondaires sous forme d’ états distincts, tels qu’un popover de débordement en haut à droite, une feuille, un panneau, un état de chargement ou une « AgentSidebar » distincte, plutôt que d’inventer un inspecteur permanent ou d’ intégrer les éléments d’interface du framework dans l’interface utilisateur du produit.

Pas de surface visuelle pour les plans purement architecturaux, purement backend, de migration de données, de copie uniquement ou autres plans non visuels. N’utilisez pas le canevas supérieur pour les diagrammes d’architecture, les cartes de dépendances, les plans de fichiers, les contrats API ou les révisions portant uniquement sur les flux de données. N’utilisez un document structuré avec des diagrammes intégrés locaux que lorsque les relations nécessitent une explication visuelle, généralement un diagramme spatial par recommandation ou décision. Privilégiez les régions groupées, les couches, les quadrants, les matrices ou les panneaux « avant/après » plutôt qu’une chaîne à axe unique, sauf si la relation est véritablement séquentielle.
Réservez le canevas à un seul écran statique, à une comparaison « avant/après », à l’état d’un composant, à une petite fenêtre contextuelle ou à une indication visuelle ne nécessitant pas de clic. Placez ces maquettes fonctionnelles dans content.canvas et omettez content.prototype.
Canvas + prototype pour les flux d’interface utilisateur en plusieurs étapes, l’intégration, les assistants, les flux de révision/validation, les changements de navigation ou tout autre cas où le réviseur doit tester le comportement. Conservez les maquettes statiques dans content.canvas, ajoutez le prototype fonctionnel aligné dans content.prototype, et utilisez les onglets visuels du haut pour basculer entre eux.
Privilégiez le prototype lorsque l’utilisateur demande à interagir avec l’interface utilisateur ou lorsque l’interaction est la question principale. Utilisez create-prototype-plan, qui conserve tout de même les maquettes statiques lorsque cela s’avère utile.

Pour les projets combinant canevas et prototype, réutilisez les mêmes libellés réels, états d’application et identifiants d’écran sur les deux supports. Le canevas est la référence statique inspectable ; le prototype est la version interactive de ce même flux, et non une orientation de conception distincte.

Qualité des maquettes fonctionnelles — lire `references/wireframe.md`

les maquettes récapitulatives de l’interface utilisateur ou de planification doivent respecter des critères de qualité stricts : chrome en pleine largeur, barres inférieures épinglées, contenu réel du produit, comparabilité avant/après, le bon surface préréglés, --wf-* des jetons à la place des codes hexadécimaux, et pas de /

Voir sur GitHub

---
name: visual-plan
description: Transform text plans into interactive visual documents with diagrams, code snippets, and review surfaces for coding agents.
---

# Agent-Native Plans

Agent-Native Plans is structured visual planning mode for coding agents. Build
the plan you would normally write in Markdown, but as a scannable document with
editable blocks mixed in: inline diagrams, code snippets,
open questions, and an optional top visual review area (wireframe canvas, live
prototype, or both in tabs). Architecture and backend plans stay document-only;
UI and product plans start with the top canvas/prototype (the Visual Surface
Choice section owns that rule).

`/visual-plan` is the packaged command and main entry point. Choose the review
mode from the task: UI-first when the work is primarily product UI and review
should start with screens, prototype-first when review should start with a
functional live prototype, design-first when review needs full-fidelity branded
screens, or visual-intake when the user explicitly wants a questionnaire before
planning. When a Codex, Claude Code, Markdown, or pasted plan already exists,
`/visual-plan` uses that source plan as the starting point and builds the review
surface from it instead of starting over.

## When To Use

Create or adapt a visual plan whenever the plan would be better as a reviewable
artifact than a chat paragraph. This includes modest work such as a single UI
surface with states, a small workflow, a before/after product change, or a
component/API/data-shape decision that needs alignment, plus larger multi-file,
ambiguous, long-running, risky, or UI-heavy work. Use it when architecture /
data flow / UI direction / options / open questions would benefit from inline
diagrams or structured blocks, when the user needs to react to a direction
before you implement, or when an existing text plan needs a richer review
surface.

## Plan Discipline

- **Gate thoughtfully.** A visual plan is a richer review surface, not only a
  tool for giant projects. Use it when the user needs to see, compare, comment
  on, or approve a direction before code, even for a modest UI/state/workflow
  change. Skip it for truly trivial, unambiguous work — typos, one-line fixes, a
  single well-specified function, anything whose diff you could describe in one
  sentence — and just make the change. Never pad a plan with filler and never
  ship a single-step plan.
- **Research before you draft.** Read the real files, actions, schema, and
  patterns first; name actual files, symbols, and data shapes instead of
  inventing them. Check existing `actions/` before proposing endpoints and prefer
  named client helpers over raw fetch. Delegate wide exploration to a sub-agent.
  Lead with reuse: for each step, name what it reuses — existing actions, schema,
  components, helpers — before what it adds, so the plan explains the genuinely new
  delta instead of redescribing what already exists.
- **Decide the hard-to-reverse bets first.** For non-trivial backend, data, or API
  work, sketch where the feature is headed, then call out the decisions that are
  expensive to undo once data or callers depend on them — wire format, public ids,
  data-model shape, auth and ownership boundaries — and get those right in the plan
  even if most of the feature ships later. Then scope to the smallest first cut that
  proves the approach without foreclosing it, stating both what is in and what is
  explicitly deferred.
- **Keep examples at the right altitude.** When the user's idea is a broad
  framework, product, or operating-model change, do not collapse it into the
  first concrete example, provider, or sync path they mention. Separate the core
  abstraction from motivating examples and app/provider adapters. Use examples
  to make the plan legible, but label them as examples unless they are the whole
  requested scope.
- **Publish standalone plans.** If the user pasted, referenced, or already has a
  Codex / Claude Code / Markdown plan, treat it as source material, but rewrite
  the published plan as a clean standalone proposal. Preserve the source plan's
  useful intent and codebase facts, label inferred visuals as inferred, and avoid
  revision language such as "preserve the prior plan", "do not drop the old
  idea", "unlike the previous version", or "this revision changes...". A reader
  who never saw the chat or earlier drafts should understand the plan.
- **Make the first read concrete.** If the plan is meant to be shared with
  someone outside the chat, or if the concept is abstract, lead near the top with
  one concrete product example before mode tables, architecture, or roadmaps. For
  UI-capable concepts, that usually means a top-canvas app state that shows the
  real user workflow in product terms. Do not rely on phrases that only make
  sense in conversation, and do not frame the plan as "not the old idea"; state
  the positive model directly.
- **Planning is read-only.** Make no source edits while building or reviewing the
  plan. Start editing only after the user approves the direction.
- **Clarify vs. assume.** Do not ask how to build it — explore and present the
  approach and options in the plan. Ask a clarifying question only when an
  ambiguity would change the design and you cannot resolve it from the code; use
  the host agent's normal ask-user-question flow and batch 2-4 high-leverage
  questions before finalizing. Do not call `create-visual-questions` for
  ordinary clarification or preflight; reserve it for the visual-intake mode when
  the user explicitly asks for a visual intake questionnaire. Otherwise state the
  assumption explicitly and proceed, and keep anything unresolved in the plan's
  single bottom `question-form` Open Questions block. For complex plans, do a
  final open-question pass before handoff: if a decision would affect
  architecture, scope, UX, data shape, or rollout, either decide it in the plan
  with rationale or put it in that bottom form with a recommended default.
- **The plan is the approval gate.** After surfacing it, ask the user to review
  and approve before you write code, and name which files/areas the work touches.
  Presenting the plan and requesting sign-off is the approval step — do not ask a
  separate "does this look good?" question.
- **The document is the source of truth, not the chat.** When scope shifts,
  update the plan with `update-visual-plan` rather than only changing course in
  chat, and make the updated document stand alone. Do not describe the update as
  a correction to an earlier draft inside the plan itself. Re-read the approved
  plan before major steps.

## Create A Structured Agent-Native Plan — Never Inline

The deliverable is ALWAYS a structured Agent-Native Plan, not a chat-only plan.
The hosted Plan MCP connector (`plan` server, or legacy `agent-native-plans`) is
the default collaboration and commenting surface; it is not a reason to reject
the planning pattern as an external dependency or rented layer. Plans are
portable source artifacts (`plan.mdx`, optional `canvas.mdx` /
`prototype.mdx`, JSON, and HTML export), and ownership-sensitive workflows can
use local-files mode or a self-hosted/custom Plan app URL without abandoning the
skill's review discipline. Do not advise the user to skip `/visual-plan` because
the default surface is hosted; choose the right Plan mode for the user's
ownership, privacy, sharing, and branding needs.

By default, create the plan via the Plan MCP connector and NEVER hand it over as
inline chat content — no Markdown prose, ASCII sketch, table, or fenced
wireframe. If the `plan` (or legacy `agent-native-plans`) tools are not visible,
discover them through the host's `tool_search` first; if they are still missing,
STOP and give the user the client-specific reconnect step rather than improvising
an inline plan. Before publishing, or whenever a connector or auth error appears,
READ `references/connection.md` in this skill directory — it is the single source
of truth for the never-inline rule, connector discovery, and the per-client
reconnect steps. Local-files privacy mode (after Tool Guidance) is the exception.

## Core Workflow

This section describes the default hosted Plan MCP workflow. If
`AGENT_NATIVE_PLANS_MODE=local-files` is set, or the user asks for fully local
files/no hosted Plan writes, use **Local-Files Privacy Mode** instead; carry
forward only the code-research and plan-composition guidance here.

1. Follow the host agent's normal planning flow: inspect the codebase, delegate
   wide exploration when useful, gather the info needed, and ask native
   clarifying questions as needed before generating the plan. If a source plan
   already exists, gather its exact text from the user's paste, a referenced
   file, or recent visible agent context; do not invent source text.
2. Call `get-plan-blocks` for the authoritative block catalog — do not author
   from memorized tags. Then call the mode-matched create tool:
   `create-visual-plan` for document-first plans (architecture, backend, data,
   refactor, API), `create-ui-plan` for UI-first plans, `create-prototype-plan`
   for prototype-first plans, `create-plan-design` for design-first plans,
   `create-visual-questions` only when the user explicitly asks for a visual
   intake questionnaire. When a source plan already exists,
   pass it as `planText` and preserve the original plan's useful intent while
   producing a standalone plan document, not a revision memo.
3. For UI/product plans, compose the top canvas first with the primary
   wireframes and annotated states, then write the document with native blocks
   (see `references/canvas.md` and `references/document-quality.md`). For
   broad product architecture plans with a user-facing implication, add a
   concrete "what this looks like in the app" visual before the abstract
   architecture or mode tables. Keep the document close to the standalone
   Markdown plan the agent would normally output. If an existing plan was
   provided, carry forward the right facts and decisions without referring to
   the previous draft or explaining how this version differs. For non-visual
   plans, skip the top visual surface (Visual Surface Choice below owns the rule)
   and put `diagram`, `data-model`,
   `api-endpoint`, `diff`, `file-tree`, `code`, and `annotated-code` blocks
   directly next to the relevant prose.
   Wide document layout is renderer-owned and intentionally allowlisted: only
   literal code-review surfaces (`diff`, `annotated-code`) and `tabs` blocks
   with vertical orientation or diff-like children break out wider than prose.
   Keep `api-endpoint`, `openapi-spec`, `data-model`, `json-explorer`,
   `wireframe`, question, and `custom-html` blocks in normal document flow unless
   their own renderer says otherwise.
4. Surface the returned Plans link or inline MCP App and ask the user to review.
   Always include the actual URL in chat so the next step is a click in CLI or
   other text-only hosts. When the host exposes an embedded browser/preview panel
   and a tool can open arbitrary URLs there, open the returned plan URL
   automatically for convenient review — a convenience and smoke test, never the
   only handoff or the access
   model. Plans should load out of the box for the local agent and local browser
   session; if a signed-in embedded browser cannot read a local plan that an
   anonymous/tool check can read, fix the app/action ownership or access path
   rather than patching one plan by hand. For high-stakes plans (architecture,
   backend, data, multi-file, or risky), also kick off the self-review pass in
   **Self-Review Before Handoff** while the user reads, instead of blocking the
   handoff on it.
5. For hosted plans, call `get-plan-feedback` before editing, after review,
   after any long pause,
   and before the final response. Treat `anchorDetails`, resolver intent, recent
   review events, and any focused screenshots from browser handoff as the source
   of truth for exactly what changed and exactly what each comment points at.
6. For hosted plans, apply changes with `update-visual-plan`, preferring
   targeted `contentPatches`.
   Treat the top-level `content` payload as a full replacement, not a merge; do
   not send a partial `content` object to add a canvas or one block. If a full
   replacement is unavoidable, first read the complete plan source/content, carry
   forward every existing block and visual surface, and verify the source/export
   afterward so the document body was not truncated. When the user wants
   source-control friendly edits, use `patch-visual-plan-source` against the MDX
   files instead of regenerating the plan.
7. For hosted plans, export with `export-visual-plan` only when the user wants a
   shareable receipt or repo-check-in artifacts.

## Self-Review Before Handoff

For high-stakes plans — architecture, backend, data-model, migration, multi-file,
or otherwise risky work — run one adversarial self-review pass before treating the
plan as final. Skip it for small, UI-only, or single-decision plans where the cost
outweighs the value. Keep the pass cheap and non-blocking:

- **Surface the plan first, review concurrently.** Post the link and let the user
  start reading, then run the review in parallel — never make the user wait on it.
- **Review the written plan; do not re-research.** Critique the plan text and its
  own blocks. The grounding was already done while drafting, so the review checks
  the output instead of re-exploring the repo.
- **Spawn one skeptical reviewer** whose only job is to find what is weak, missing,
  or wrong — not to praise. Point it at: hard-to-reverse decisions made implicitly
  or not at all (wire format, public ids, data-model shape, auth, ownership); steps
  not anchored in real files or symbols; a menu of options where the plan should
  commit to one; obvious missing decisions ("what happens when X?", "why not Y?");
  and padding or single-step filler.
- **Fix vs. ask.** Apply clear-cut fixes yourself with `update-visual-plan`
  `contentPatches` — vague non-goals, unanchored claims, an obvious missing
  decision. Route genuine judgment calls back to the user instead: add them to the
  bottom `question-form` Open Questions block or batch them into the normal
  ask-user-question flow. Do not silently decide them.
- **Do not surprise the user mid-read.** On a large plan, apply the patches before
  the editor loads; otherwise note briefly that a self-review is running so the
  plan changing under them is expected. When you next respond, summarize what the
  review changed and what it surfaced for the user to decide.

## Visual Surface Choice

Choose the surface before creating the plan or after reading the source plan. Do
not add visual chrome by default:

For UI/product plans, the top canvas is usually the primary review surface. Put
the first meaningful wireframes there, not buried as document-body blocks. Use
multiple canvas artboards when states matter, such as the default view, an
overflow menu or popover, a side panel, loading, or error. Put short annotations
beside frames with `targetId` plus `placement`; keep implementation details,
tradeoffs, file maps, data contracts, risks, and verification in the document
body below the canvas.

When the user asks for a flow, storyboard, journey, wireframe, canvas, or "what
this looks like", treat that as a canvas-first request. Make one artboard per
user-visible state, connect only adjacent transitions, and use short canvas
annotations for the product notes. Do not substitute a document-body `diagram`
block for the requested storyboard just because HTML diagrams are faster to
write; diagrams belong below the canvas for backend mechanics, architecture, or
data-flow explanation.

Keep product wireframes and explanatory/meta diagrams separate. Start with pure
screens that look like the app state under discussion, without callout prose or
architecture notes embedded inside the UI. Put arrows, labels, contracts, data
flow, and mode explanations in separate annotations, separate canvas diagrams,
or the document body.

When the plan touches an existing app, inspect the current shell/components
before drawing. The first artboard should look like the real app at the same
density: existing sidebars, toolbar placement, overflow menus, app chrome, and
framework agent chrome stay in their real places. Model secondary surfaces as
separate states, such as a top-right overflow popover, sheet, panel, loading
state, or separate AgentSidebar, rather than inventing a permanent inspector or
folding framework chrome into the product UI.

- **No visual surface** for architecture-only, backend-only, data migration,
  copy-only, or otherwise non-visual plans. Do not use the top canvas for
  architecture diagrams, dependency maps, file plans, API contracts, or
  data-flow-only reviews. Use a strong document with local inline diagrams
  only when relationships need a visual explanation, usually one spatial diagram
  per recommendation or decision. Prefer grouped regions, layers, quadrants,
  matrices, or before/after panels over a single-axis chain unless the
  relationship is truly sequential.
- **Canvas only** for one static screen, a before/after comparison, a component
  state, a small popover, or a visual direction that does not require clicking.
  Put those wireframes in `content.canvas` and omit `content.prototype`.
- **Canvas + prototype** for multi-step UI flows, onboarding, wizards,
  review/approval flows, navigation changes, or anything where the reviewer
  needs to operate the behavior. Keep the static wireframes in
  `content.canvas`, add the aligned functional prototype in
  `content.prototype`, and rely on the top visual tabs to switch between them.
- **Prototype-first** when the user asks to operate the UI or when interaction is
  the main question. Use `create-prototype-plan`, which still preserves static
  mocks where useful.

For mixed canvas + prototype plans, reuse the same real labels, app statuses,
and screen ids across both surfaces. The canvas is the inspectable static reference;
the prototype is the interactive version of that same flow, not a separate
design direction.

## Wireframe quality — read `references/wireframe.md`

UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
pinned bottom bars, real product content, before/after comparability, the right
`surface` preset, `--wf-*` tokens instead of hex, and no `<html>`/`<style>`/font
tags. Before authoring ANY wireframe / `<Screen>` / `WireframeBlock`, READ
`references/wireframe.md` in this skill directory — it is the single source of
truth for HTML wireframe quality, shared word for word with `/visual-plan`
and `/visual-recap`. Do not author wireframes from memory.

## Canvas — read `references/canvas.md`

The canvas is the single source of truth for static UI mockups: the `surface`
locks each artboard's footprint, mixed surfaces lay out
in lanes, annotations are plain-text designer notes anchored by
`targetId`/`placement`, and edits are surgical `contentPatches`. Before
authoring or editing ANY canvas, artboard, or annotation, READ
`references/canvas.md` in this skill directory — it is the single source of truth
for canvas/artboard mechanics. Do not author canvas layouts from memory.
Canvas artboards use the same HTML wireframe path as document-body
`WireframeBlock` screens: author `<Screen surface="..." html={...} />` with a
semantic HTML fragment. Do not author fresh kit-tree children such as
`<FrameScreen>`, `<Card>`, `<Row>`, or `<Btn>` inside canvas `<Screen>` tags;
those are legacy compatibility markup for old plans and produce brittle canvas
layouts.

## Document quality — read `references/document-quality.md`

The document is a serious technical plan, not marketing: outcome-first,
prose-first, self-contained, built from the right native blocks, with open
questions in a single bottom `question-form` and a pre-handoff visual check.
Before authoring the plan document, READ `references/document-quality.md` in this
skill directory — it is the single source of truth for the document quality bar.
Do not write the document from memory.

## Good vs. bad exemplar — read `references/exemplar.md`

For a worked example of the bar — a great UI-first plan and `/visual-plan`, plus
the anti-patterns to avoid — READ `references/exemplar.md` in this skill
directory before authoring a plan.

## Tool Guidance

- `create-visual-plan`: start one structured visual plan per agent task/run, or
  import an existing text plan by passing `planText`; `content` may include no
  visual surface, canvas only, or canvas + prototype.
- `create-ui-plan`: start a UI-first plan when the work is primarily product UI.
- `create-prototype-plan`: start a prototype-first plan with a functional top
  review surface.
- `create-plan-design`: start a full-fidelity branded Design-tab plan with an
  optional matching Prototype tab.
- `convert-visual-plan-to-prototype`: convert an existing HTML wireframe canvas
  into a prototype plan.
- `create-visual-questions`: use only when the user explicitly asks for a visual
  intake questionnaire, not as `/visual-plan` preflight.
- `update-visual-plan`: revise content, status, or comments with targeted
  `contentPatches` (see Core Workflow step 6).
- `read-visual-plan-source`: read the normalized plan as `plan.mdx`,
  optional `canvas.mdx`, optional `.plan-state.json`, and JSON.
- `patch-visual-plan-source`: apply granular MDX AST patches by stable block,
  artboard, annotation, component, or wireframe-node id.
- `import-visual-plan-source`: create or replace a plan from an MDX folder.
- `get-visual-plan`: read the current structured plan, exported HTML, and
  annotations; it also returns the MDX folder for source workflows.
- `get-plan-feedback`: read unconsumed human feedback. Use it frequently; it
  returns grouped threads, exact anchor details, expected resolver, and recent
  review-event payloads so agents can act only on the comments meant for them.
- `get-plan-blocks`: resolve block tags before authoring — do not memorize tags;
  call this first to get the authoritative tag names, required fields, and prop
  shapes from the live block registry.
- `export-visual-plan`: export HTML, Markdown fallback, structured JSON, and MDX
  files for repo check-in.

When the user critiques a plan's look or structure, fix the renderer or this
skill — never hand-edit one stored plan. Turn feedback into better guidance.

## Local-Files Privacy Mode — read `references/local-files.md`

When the user wants no hosted Plan database writes — no DB writes, no Plan MCP
publish, fully local/offline/private planning, repo-owned source-controlled
artifacts, or `AGENT_NATIVE_PLANS_MODE=local-files` — do not call any hosted Plan
tool except the schema-only `get-plan-blocks` catalog lookup. Author a local MDX
folder and
preview it with `plan local check` / `plan local serve` / `plan local verify`.
Before using local-files mode, READ `references/local-files.md` in this skill
directory — it is the single source of truth for the full contract (catalog
lookup, MDX folder layout, the local bridge commands, and the hosted tools you
must not call). Carry forward only the code-research and plan-composition
guidance from Core Workflow; everything hosted is replaced by the local bridge.

## Interpreting comment anchors

This section applies to hosted plans with `get-plan-feedback` /
`update-visual-plan`. In local-files mode, do not call hosted feedback or update
tools; interpret file/chat feedback directly, edit the MDX files, rerun the
local bridge check/serve/verify command, and report the new local URL.

`get-plan-feedback` returns rich anchors — read them before acting on any comment.

- **Coordinate frames.** `targetX`/`targetY` are percentages *within* the
  element named by `targetSelector`/`targetKind`. Bare `x`/`y` are percentages
  of the whole plan document. `canvasX`/`canvasY` are raw board-world pixels on
  the design canvas (board size given when available).
- **Wireframe pins.** Anchors on wireframes include `targetNodeId` and
  `targetNodePath` (e.g. `card > list > listItem "Acme Inc"`) identifying the
  exact kit node. Use `targetNodeId` directly with wireframe node patch ops;
  use `data-design-id` values from design artboards with
  `update-design-element-style`. Prefer the node id/path over raw coordinates;
  fall back to coordinates plus the focused screenshot (red ring marks the exact
  point) only when no node id is present.
- **Text quotes.** Resolve `textQuote` against current prose using
  `contextBefore`/`contextAfter` for disambiguation. If `ambiguous: true`, ask
  the user — do not guess which occurrence is meant.
- **Detached comments.** `get-plan-feedback` flags threads whose quoted text no
  longer exists as `detached` (in `detachedThreads`). Reconcile these against
  rewritten content — never silently drop them.
- **Routing.** `resolutionTarget` is the only routing signal: act on `agent`,
  treat `human` as context only. `@mentions` are people to notify, never a
  routing signal.
- **Two-axis state.** Mark every ingested comment as consumed
  (`consumedCommentIds` on `update-visual-plan`). Set `status=resolved` only on
  agent-targeted comments you actually addressed; leave human-targeted comments
  open.

## Visibility & Sharing

Use `set-resource-visibility` to change who can see a plan (e.g. public, login,
or org-scoped). Use `share-resource` to grant specific users or roles access
by email or role. Gate visibility before sharing any plan that covers
unreleased or private work — default to the narrowest scope that meets the
review need.

## Setup & Authentication

There are two ways into Plans.

**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
installs the Plans skills, registers the hosted Plans MCP connector, and runs
auth/setup for the selected local client(s) in the same step (a one-time browser
sign-in at setup — this is intended), so the first tool call in that client does
not hit an OAuth wall:

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

After that, `/visual-plan` and `/visual-recap` are the two installed slash
commands. If you only need one command, use `skills add visual-plan` or
`skills add visual-recap` instead. The other planning modes
(`create-ui-plan`, `create-prototype-plan`, `create-plan-design`,
`create-visual-questions`) are MCP tools reachable from `/visual-plan`, not
separate slash commands. Pass `--no-connect` to register the connector without
authenticating, then run
`npx @agent-native/core@latest connect https://plan.agent-native.com --client all`
whenever you are ready, or choose a narrower `--client`. Auth and MCP tool
loading are per client config/session.

**Browser (people you share with).** Open the Plans editor and create & edit
with no sign-up — you work as a guest. Sign in only when you want to save or
share; signing in claims the plans you made as a guest into your account.

Sharing and commenting require an account: public/shared plans are viewable by
anyone with the link, but commenting on them needs an agent-native account.

For fully offline, no-account use, run the Plans app locally and sync plans to
your repo as MDX. This local mode is a separate advanced path, not the default
hosted flow.

If a Plans tool returns `needs auth`, `Unauthorized`, or `Session terminated`, do
not keep retrying it — stop and give the user the per-client reconnect step from
`references/connection.md`, then continue once the connector is available.

Hosted default: connect `https://plan.agent-native.com/_agent-native/mcp`. Do
not put shared secrets in skill files.

Tous les fichiers

0 fichiers

Installer visual-plan

Téléchargez et décompressez les fichiers de compétences dans votre répertoire .claude/skills/.

Télécharger le ZIP

Clonez le dépôt et copiez les fichiers de compétence dans votre projet.

git clone https://github.com/BuilderIO/skills/tree/main/skills/visual-plan # Copy SKILL.md to your .claude/skills/ directory

Copier

Configuration rapide: Copiez le dossier de la compétence dans .claude/skills/ Claude détectera automatiquement la compétence et l'utilisera

Dépôt BuilderIO/skills

Compétences similaires

notion-automation

Heure mise à jour 29 juin 2026

airtable-automation

Heure mise à jour 29 juin 2026

seo-programmatic

Heure mise à jour 29 juin 2026

revops

Heure mise à jour 29 juin 2026

visual-plan

Plans natifs pour agents

Quand l’utiliser

Discipline de planification

Créez un plan structuré natif de l’agent — jamais en ligne

Workflow principal

Auto-révision avant la remise

Choix de la présentation visuelle

Qualité des maquettes fonctionnelles — lire references/wireframe.md

Tous les fichiers

Installer visual-plan

Compétences similaires

Qualité des maquettes fonctionnelles — lire `references/wireframe.md`