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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 or replace-blocks is unavoidable, call get-visual-plan
immediately before the write, pass its plan.updatedAt as
expectedUpdatedAt, and carry forward every existing block and visual
surface. Never reuse a revision from an earlier read or feedback payload.
For source-control friendly edits, use granular patch-visual-plan-source
operations against the MDX files instead of regenerating the plan;
replace-file is also destructive and requires the same fresh
expectedUpdatedAt fence.
- After every hosted-plan write, call
get-visual-plan again and compare the
persisted text, block IDs/counts, canvas frames, and prototype with the
intended result. A successful mutation response is not proof that unrelated
content survived. If the edit addressed agent-targeted feedback, only after
this verification call resolve-plan-comment for the thread and
consume-plan-feedback for its comments; do both so addressed feedback is
neither visibly open nor returned as pending work.
- 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
This adversarial self-review pass is opt-in, not default: run it only for
high-stakes plans — irreversible migrations, security-sensitive work, or when
the user explicitly asks for extra rigor — and skip it otherwise. It roughly
doubles the cost of plan generation, so the default for small, UI-only,
single-decision, or ordinary plans is to skip it, not to run it. Keep the pass
cheap and non-blocking when it does run:
- 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.
When both surfaces are present, open the Wireframes tab by default; the
prototype remains available as the interactive follow-up view.
- Default to wireframes. A clean, minimal UI, a high UX bar, or references
to Linear/Vercel describe the content and density bar; they do not request
full-fidelity design mode. Use renderer-owned wireframes unless the user
explicitly asks for branded, pixel-accurate, production-like, or full visual
design. This keeps every canvas screen inspectable and its full content visible.
- 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 labels and IDs; patch surfaces
together unless explicitly single-surface. For output audits, read the
observability skill: support single-app and workspace tables, preserve app
previews, and keep audit, synthesis, diffs, and applying changes admin-gated.
Treat “higher fidelity,” “pixel-accurate,” “polished mockup,” “production-like,”
“real design,” and “not a sketch/wireframe” as design-first language even when
the request also says “mockup.” For a new plan, use create-plan-design. For
an existing plan, keep the same plan id and call update-visual-plan with a
set-visual-render-mode patch using renderMode: "design" plus the upgraded
screen HTML/CSS in the same update. Ground the result in the real app shell,
tokens, typography, spacing, and states, and add stable data-design-id
targets. Put scoped styles in each screen's css field, never in a <style>
tag. The viewer-local Clean toggle only changes one browser's wireframe
preference; it is not a fidelity upgrade. Do not create a duplicate plan to
handle a fidelity follow-up.
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.
Authoring invariants
Treat these as data-integrity checks, not optional polish:
content is a complete replacement. Pass either content or the mode's
convenience arrays (screens/transitions or states/components),
never both. The create actions reject mixed sources so a second payload cannot
silently discard CSS, frames, or document blocks.
- A design screen's scoped
css is part of the artifact. Keep it on both the
prototype screen and its matching canvas frame, and use renderer-owned
--wf-* tokens for portable color and typography.
- Rich-text
data.markdown must contain actual runtime line breaks. Do not
hand a plan a one-line Markdown value containing literal \n escape text,
which renders the whole section as one heading. Escaped newlines are fine in
code examples when the surrounding Markdown still has real line breaks.
- Canvas artboards do not scroll. Keep wireframe HTML in natural flow and set a
larger frame
height when a screen exceeds the surface preset; preserve the
surface width and inspect the bottom edge at default zoom before handoff.
- After every hosted write, re-read the structured content and inspect the live
Plan surface. A valid JSON payload is not proof that CSS loaded or Markdown
rendered into the intended heading, paragraph, and list structure.
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. If the interaction itself must also be high fidelity, set each
screen's renderMode to design and pass scoped styles through css;
otherwise use create-plan-design for design-first review.
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 steps 6-7). Use
set-visual-render-mode with renderMode: "design" when promoting an
existing plan to high fidelity, together with deliberate screen HTML/CSS;
render mode alone only removes sketch treatment. replace-blocks and full
content replacement require expectedUpdatedAt from a fresh
get-visual-plan call.
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. Prefer those targeted
operations; replace-file requires expectedUpdatedAt from a fresh
get-visual-plan call.
import-visual-plan-source: create or replace a plan from an MDX folder.
get-visual-plan: read the current structured plan, exported HTML,
annotations, and plan.updatedAt; it also returns the MDX folder for source
workflows. Re-read immediately before a destructive write for its concurrency
fence and again after every write to verify persisted state.
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. When an edit addresses feedback, first re-read the persisted plan and
verify the requested change. Only then call resolve-plan-comment for the
addressed thread and consume-plan-feedback for its comments; never mark
addressed feedback along only one axis.
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:
npx @agent-native/core@latest skills add visual-plans
After that, /visual-plan, /visual-recap, and /visualize-repo are the
installed slash commands. If you only need one command, use
skills add visual-plan, skills add visual-recap, or
skills add visualize-repo 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.
For repo-wide visual docs, run
npx @agent-native/core@latest visualize-repo --open to create/update
agent-native.json, seed .agent-native/visual-docs/repo-overview, and open
the local bridge.
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/mcp. Do
not put shared secrets in skill files.
1---2name: visual-plan-33description: >-4 Turn ordinary text plans into rich interactive visual plans with diagrams,5 file maps, annotated code, open questions, and UI/prototype review when6 useful.7metadata:8 source: https://skillmd.com/skills/builderio/visual-plan-39 visibility: exported10---1112# Agent-Native Plans1314Agent-Native Plans is structured visual planning mode for coding agents. Build15the plan you would normally write in Markdown, but as a scannable document with16editable blocks mixed in: inline diagrams, code snippets,17open questions, and an optional top visual review area (wireframe canvas, live18prototype, or both in tabs). Architecture and backend plans stay document-only;19UI and product plans start with the top canvas/prototype (the Visual Surface20Choice section owns that rule).2122`/visual-plan` is the packaged command and main entry point. Choose the review23mode from the task: UI-first when the work is primarily product UI and review24should start with screens, prototype-first when review should start with a25functional live prototype, design-first when review needs full-fidelity branded26screens, or visual-intake when the user explicitly wants a questionnaire before27planning. When a Codex, Claude Code, Markdown, or pasted plan already exists,28`/visual-plan` uses that source plan as the starting point and builds the review29surface from it instead of starting over.3031## When To Use3233Create or adapt a visual plan whenever the plan would be better as a reviewable34artifact than a chat paragraph. This includes modest work such as a single UI35surface with states, a small workflow, a before/after product change, or a36component/API/data-shape decision that needs alignment, plus larger multi-file,37ambiguous, long-running, risky, or UI-heavy work. Use it when architecture /38data flow / UI direction / options / open questions would benefit from inline39diagrams or structured blocks, when the user needs to react to a direction40before you implement, or when an existing text plan needs a richer review41surface.4243## Plan Discipline4445- **Gate thoughtfully.** A visual plan is a richer review surface, not only a46 tool for giant projects. Use it when the user needs to see, compare, comment47 on, or approve a direction before code, even for a modest UI/state/workflow48 change. Skip it for truly trivial, unambiguous work — typos, one-line fixes, a49 single well-specified function, anything whose diff you could describe in one50 sentence — and just make the change. Never pad a plan with filler and never51 ship a single-step plan.52- **Research before you draft.** Read the real files, actions, schema, and53 patterns first; name actual files, symbols, and data shapes instead of54 inventing them. Check existing `actions/` before proposing endpoints and prefer55 named client helpers over raw fetch. Delegate wide exploration to a sub-agent.56 Lead with reuse: for each step, name what it reuses — existing actions, schema,57 components, helpers — before what it adds, so the plan explains the genuinely new58 delta instead of redescribing what already exists.59- **Decide the hard-to-reverse bets first.** For non-trivial backend, data, or API60 work, sketch where the feature is headed, then call out the decisions that are61 expensive to undo once data or callers depend on them — wire format, public ids,62 data-model shape, auth and ownership boundaries — and get those right in the plan63 even if most of the feature ships later. Then scope to the smallest first cut that64 proves the approach without foreclosing it, stating both what is in and what is65 explicitly deferred.66- **Keep examples at the right altitude.** When the user's idea is a broad67 framework, product, or operating-model change, do not collapse it into the68 first concrete example, provider, or sync path they mention. Separate the core69 abstraction from motivating examples and app/provider adapters. Use examples70 to make the plan legible, but label them as examples unless they are the whole71 requested scope.72- **Publish standalone plans.** If the user pasted, referenced, or already has a73 Codex / Claude Code / Markdown plan, treat it as source material, but rewrite74 the published plan as a clean standalone proposal. Preserve the source plan's75 useful intent and codebase facts, label inferred visuals as inferred, and avoid76 revision language such as "preserve the prior plan", "do not drop the old77 idea", "unlike the previous version", or "this revision changes...". A reader78 who never saw the chat or earlier drafts should understand the plan.79- **Make the first read concrete.** If the plan is meant to be shared with80 someone outside the chat, or if the concept is abstract, lead near the top with81 one concrete product example before mode tables, architecture, or roadmaps. For82 UI-capable concepts, that usually means a top-canvas app state that shows the83 real user workflow in product terms. Do not rely on phrases that only make84 sense in conversation, and do not frame the plan as "not the old idea"; state85 the positive model directly.86- **Planning is read-only.** Make no source edits while building or reviewing the87 plan. Start editing only after the user approves the direction.88- **Clarify vs. assume.** Do not ask how to build it — explore and present the89 approach and options in the plan. Ask a clarifying question only when an90 ambiguity would change the design and you cannot resolve it from the code; use91 the host agent's normal ask-user-question flow and batch 2-4 high-leverage92 questions before finalizing. Do not call `create-visual-questions` for93 ordinary clarification or preflight; reserve it for the visual-intake mode when94 the user explicitly asks for a visual intake questionnaire. Otherwise state the95 assumption explicitly and proceed, and keep anything unresolved in the plan's96 single bottom `question-form` Open Questions block. For complex plans, do a97 final open-question pass before handoff: if a decision would affect98 architecture, scope, UX, data shape, or rollout, either decide it in the plan99 with rationale or put it in that bottom form with a recommended default.100- **The plan is the approval gate.** After surfacing it, ask the user to review101 and approve before you write code, and name which files/areas the work touches.102 Presenting the plan and requesting sign-off is the approval step — do not ask a103 separate "does this look good?" question.104- **The document is the source of truth, not the chat.** When scope shifts,105 update the plan with `update-visual-plan` rather than only changing course in106 chat, and make the updated document stand alone. Do not describe the update as107 a correction to an earlier draft inside the plan itself. Re-read the approved108 plan before major steps.109110## Create A Structured Agent-Native Plan — Never Inline111112The deliverable is ALWAYS a structured Agent-Native Plan, not a chat-only plan.113The hosted Plan MCP connector (`plan` server, or legacy `agent-native-plans`) is114the default collaboration and commenting surface; it is not a reason to reject115the planning pattern as an external dependency or rented layer. Plans are116portable source artifacts (`plan.mdx`, optional `canvas.mdx` /117`prototype.mdx`, JSON, and HTML export), and ownership-sensitive workflows can118use local-files mode or a self-hosted/custom Plan app URL without abandoning the119skill's review discipline. Do not advise the user to skip `/visual-plan` because120the default surface is hosted; choose the right Plan mode for the user's121ownership, privacy, sharing, and branding needs.122123By default, create the plan via the Plan MCP connector and NEVER hand it over as124inline chat content — no Markdown prose, ASCII sketch, table, or fenced125wireframe. If the `plan` (or legacy `agent-native-plans`) tools are not visible,126discover them through the host's `tool_search` first; if they are still missing,127STOP and give the user the client-specific reconnect step rather than improvising128an inline plan. Before publishing, or whenever a connector or auth error appears,129READ `references/connection.md` in this skill directory — it is the single source130of truth for the never-inline rule, connector discovery, and the per-client131reconnect steps. Local-files privacy mode (after Tool Guidance) is the exception.132133## Core Workflow134135This section describes the default hosted Plan MCP workflow. If136`AGENT_NATIVE_PLANS_MODE=local-files` is set, or the user asks for fully local137files/no hosted Plan writes, use **Local-Files Privacy Mode** instead; carry138forward only the code-research and plan-composition guidance here.1391401. Follow the host agent's normal planning flow: inspect the codebase, delegate141 wide exploration when useful, gather the info needed, and ask native142 clarifying questions as needed before generating the plan. If a source plan143 already exists, gather its exact text from the user's paste, a referenced144 file, or recent visible agent context; do not invent source text.1452. Call `get-plan-blocks` for the authoritative block catalog — do not author146 from memorized tags. Then call the mode-matched create tool:147 `create-visual-plan` for document-first plans (architecture, backend, data,148 refactor, API), `create-ui-plan` for UI-first plans, `create-prototype-plan`149 for prototype-first plans, `create-plan-design` for design-first plans,150 `create-visual-questions` only when the user explicitly asks for a visual151 intake questionnaire. When a source plan already exists,152 pass it as `planText` and preserve the original plan's useful intent while153 producing a standalone plan document, not a revision memo.1543. For UI/product plans, compose the top canvas first with the primary155 wireframes and annotated states, then write the document with native blocks156 (see `references/canvas.md` and `references/document-quality.md`). For157 broad product architecture plans with a user-facing implication, add a158 concrete "what this looks like in the app" visual before the abstract159 architecture or mode tables. Keep the document close to the standalone160 Markdown plan the agent would normally output. If an existing plan was161 provided, carry forward the right facts and decisions without referring to162 the previous draft or explaining how this version differs. For non-visual163 plans, skip the top visual surface (Visual Surface Choice below owns the rule)164 and put `diagram`, `data-model`,165 `api-endpoint`, `diff`, `file-tree`, `code`, and `annotated-code` blocks166 directly next to the relevant prose.167 Wide document layout is renderer-owned and intentionally allowlisted: only168 literal code-review surfaces (`diff`, `annotated-code`) and `tabs` blocks169 with vertical orientation or diff-like children break out wider than prose.170 Keep `api-endpoint`, `openapi-spec`, `data-model`, `json-explorer`,171 `wireframe`, question, and `custom-html` blocks in normal document flow unless172 their own renderer says otherwise.1734. Surface the returned Plans link or inline MCP App and ask the user to review.174 Always include the actual URL in chat so the next step is a click in CLI or175 other text-only hosts. When the host exposes an embedded browser/preview panel176 and a tool can open arbitrary URLs there, open the returned plan URL177 automatically for convenient review — a convenience and smoke test, never the178 only handoff or the access179 model. Plans should load out of the box for the local agent and local browser180 session; if a signed-in embedded browser cannot read a local plan that an181 anonymous/tool check can read, fix the app/action ownership or access path182 rather than patching one plan by hand. For high-stakes plans (architecture,183 backend, data, multi-file, or risky), also kick off the self-review pass in184 **Self-Review Before Handoff** while the user reads, instead of blocking the185 handoff on it.1865. For hosted plans, call `get-plan-feedback` before editing, after review,187 after any long pause,188 and before the final response. Treat `anchorDetails`, resolver intent, recent189 review events, and any focused screenshots from browser handoff as the source190 of truth for exactly what changed and exactly what each comment points at.1916. For hosted plans, apply changes with `update-visual-plan`, preferring192 targeted `contentPatches`.193 Treat the top-level `content` payload as a full replacement, not a merge; do194 not send a partial `content` object to add a canvas or one block. If a full195 replacement or `replace-blocks` is unavoidable, call `get-visual-plan`196 immediately before the write, pass its `plan.updatedAt` as197 `expectedUpdatedAt`, and carry forward every existing block and visual198 surface. Never reuse a revision from an earlier read or feedback payload.199 For source-control friendly edits, use granular `patch-visual-plan-source`200 operations against the MDX files instead of regenerating the plan;201 `replace-file` is also destructive and requires the same fresh202 `expectedUpdatedAt` fence.2037. After every hosted-plan write, call `get-visual-plan` again and compare the204 persisted text, block IDs/counts, canvas frames, and prototype with the205 intended result. A successful mutation response is not proof that unrelated206 content survived. If the edit addressed agent-targeted feedback, only after207 this verification call `resolve-plan-comment` for the thread and208 `consume-plan-feedback` for its comments; do both so addressed feedback is209 neither visibly open nor returned as pending work.2108. For hosted plans, export with `export-visual-plan` only when the user wants a211 shareable receipt or repo-check-in artifacts.212213## Self-Review Before Handoff214215This adversarial self-review pass is opt-in, not default: run it only for216high-stakes plans — irreversible migrations, security-sensitive work, or when217the user explicitly asks for extra rigor — and skip it otherwise. It roughly218doubles the cost of plan generation, so the default for small, UI-only,219single-decision, or ordinary plans is to skip it, not to run it. Keep the pass220cheap and non-blocking when it does run:221222- **Surface the plan first, review concurrently.** Post the link and let the user223 start reading, then run the review in parallel — never make the user wait on it.224- **Review the written plan; do not re-research.** Critique the plan text and its225 own blocks. The grounding was already done while drafting, so the review checks226 the output instead of re-exploring the repo.227- **Spawn one skeptical reviewer** whose only job is to find what is weak, missing,228 or wrong — not to praise. Point it at: hard-to-reverse decisions made implicitly229 or not at all (wire format, public ids, data-model shape, auth, ownership); steps230 not anchored in real files or symbols; a menu of options where the plan should231 commit to one; obvious missing decisions ("what happens when X?", "why not Y?");232 and padding or single-step filler.233- **Fix vs. ask.** Apply clear-cut fixes yourself with `update-visual-plan`234 `contentPatches` — vague non-goals, unanchored claims, an obvious missing235 decision. Route genuine judgment calls back to the user instead: add them to the236 bottom `question-form` Open Questions block or batch them into the normal237 ask-user-question flow. Do not silently decide them.238- **Do not surprise the user mid-read.** On a large plan, apply the patches before239 the editor loads; otherwise note briefly that a self-review is running so the240 plan changing under them is expected. When you next respond, summarize what the241 review changed and what it surfaced for the user to decide.242243## Visual Surface Choice244245Choose the surface before creating the plan or after reading the source plan. Do246not add visual chrome by default:247248For UI/product plans, the top canvas is usually the primary review surface. Put249the first meaningful wireframes there, not buried as document-body blocks. Use250multiple canvas artboards when states matter, such as the default view, an251overflow menu or popover, a side panel, loading, or error. Put short annotations252beside frames with `targetId` plus `placement`; keep implementation details,253tradeoffs, file maps, data contracts, risks, and verification in the document254body below the canvas.255256When the user asks for a flow, storyboard, journey, wireframe, canvas, or "what257this looks like", treat that as a canvas-first request. Make one artboard per258user-visible state, connect only adjacent transitions, and use short canvas259annotations for the product notes. Do not substitute a document-body `diagram`260block for the requested storyboard just because HTML diagrams are faster to261write; diagrams belong below the canvas for backend mechanics, architecture, or262data-flow explanation.263264Keep product wireframes and explanatory/meta diagrams separate. Start with pure265screens that look like the app state under discussion, without callout prose or266architecture notes embedded inside the UI. Put arrows, labels, contracts, data267flow, and mode explanations in separate annotations, separate canvas diagrams,268or the document body.269270When the plan touches an existing app, inspect the current shell/components271before drawing. The first artboard should look like the real app at the same272density: existing sidebars, toolbar placement, overflow menus, app chrome, and273framework agent chrome stay in their real places. Model secondary surfaces as274separate states, such as a top-right overflow popover, sheet, panel, loading275state, or separate AgentSidebar, rather than inventing a permanent inspector or276folding framework chrome into the product UI.277278- **No visual surface** for architecture-only, backend-only, data migration,279 copy-only, or otherwise non-visual plans. Do not use the top canvas for280 architecture diagrams, dependency maps, file plans, API contracts, or281 data-flow-only reviews. Use a strong document with local inline diagrams282 only when relationships need a visual explanation, usually one spatial diagram283 per recommendation or decision. Prefer grouped regions, layers, quadrants,284 matrices, or before/after panels over a single-axis chain unless the285 relationship is truly sequential.286- **Canvas only** for one static screen, a before/after comparison, a component287 state, a small popover, or a visual direction that does not require clicking.288 Put those wireframes in `content.canvas` and omit `content.prototype`.289- **Canvas + prototype** for multi-step UI flows, onboarding, wizards,290 review/approval flows, navigation changes, or anything where the reviewer291 needs to operate the behavior. Keep the static wireframes in292 `content.canvas`, add the aligned functional prototype in293 `content.prototype`, and rely on the top visual tabs to switch between them.294 When both surfaces are present, open the Wireframes tab by default; the295 prototype remains available as the interactive follow-up view.296- **Default to wireframes.** A clean, minimal UI, a high UX bar, or references297 to Linear/Vercel describe the content and density bar; they do not request298 full-fidelity design mode. Use renderer-owned wireframes unless the user299 explicitly asks for branded, pixel-accurate, production-like, or full visual300 design. This keeps every canvas screen inspectable and its full content visible.301- **Prototype-first** when the user asks to operate the UI or when interaction is302 the main question. Use `create-prototype-plan`, which still preserves static303 mocks where useful.304305For mixed canvas + prototype plans, reuse labels and IDs; patch surfaces306together unless explicitly single-surface. For output audits, read the307observability skill: support single-app and workspace tables, preserve app308previews, and keep audit, synthesis, diffs, and applying changes admin-gated.309310Treat “higher fidelity,” “pixel-accurate,” “polished mockup,” “production-like,”311“real design,” and “not a sketch/wireframe” as design-first language even when312the request also says “mockup.” For a new plan, use `create-plan-design`. For313an existing plan, keep the same plan id and call `update-visual-plan` with a314`set-visual-render-mode` patch using `renderMode: "design"` plus the upgraded315screen HTML/CSS in the same update. Ground the result in the real app shell,316tokens, typography, spacing, and states, and add stable `data-design-id`317targets. Put scoped styles in each screen's `css` field, never in a `<style>`318tag. The viewer-local Clean toggle only changes one browser's wireframe319preference; it is not a fidelity upgrade. Do not create a duplicate plan to320handle a fidelity follow-up.321322## Wireframe quality — read `references/wireframe.md`323324UI recap/plan wireframes must meet a strict quality bar — full-width chrome,325pinned bottom bars, real product content, before/after comparability, the right326`surface` preset, `--wf-*` tokens instead of hex, and no `<html>`/`<style>`/font327tags. Before authoring ANY wireframe / `<Screen>` / `WireframeBlock`, READ328`references/wireframe.md` in this skill directory — it is the single source of329truth for HTML wireframe quality, shared word for word with `/visual-plan`330and `/visual-recap`. Do not author wireframes from memory.331332## Canvas — read `references/canvas.md`333334The canvas is the single source of truth for static UI mockups: the `surface`335locks each artboard's footprint, mixed surfaces lay out336in lanes, annotations are plain-text designer notes anchored by337`targetId`/`placement`, and edits are surgical `contentPatches`. Before338authoring or editing ANY canvas, artboard, or annotation, READ339`references/canvas.md` in this skill directory — it is the single source of truth340for canvas/artboard mechanics. Do not author canvas layouts from memory.341Canvas artboards use the same HTML wireframe path as document-body342`WireframeBlock` screens: author `<Screen surface="..." html={...} />` with a343semantic HTML fragment. Do not author fresh kit-tree children such as344`<FrameScreen>`, `<Card>`, `<Row>`, or `<Btn>` inside canvas `<Screen>` tags;345those are legacy compatibility markup for old plans and produce brittle canvas346layouts.347348## Document quality — read `references/document-quality.md`349350The document is a serious technical plan, not marketing: outcome-first,351prose-first, self-contained, built from the right native blocks, with open352questions in a single bottom `question-form` and a pre-handoff visual check.353Before authoring the plan document, READ `references/document-quality.md` in this354skill directory — it is the single source of truth for the document quality bar.355Do not write the document from memory.356357## Good vs. bad exemplar — read `references/exemplar.md`358359For a worked example of the bar — a great UI-first plan and `/visual-plan`, plus360the anti-patterns to avoid — READ `references/exemplar.md` in this skill361directory before authoring a plan.362363## Authoring invariants364365Treat these as data-integrity checks, not optional polish:366367- `content` is a complete replacement. Pass either `content` or the mode's368 convenience arrays (`screens`/`transitions` or `states`/`components`),369 never both. The create actions reject mixed sources so a second payload cannot370 silently discard CSS, frames, or document blocks.371- A design screen's scoped `css` is part of the artifact. Keep it on both the372 prototype screen and its matching canvas frame, and use renderer-owned373 `--wf-*` tokens for portable color and typography.374- Rich-text `data.markdown` must contain actual runtime line breaks. Do not375 hand a plan a one-line Markdown value containing literal `\n` escape text,376 which renders the whole section as one heading. Escaped newlines are fine in377 code examples when the surrounding Markdown still has real line breaks.378- Canvas artboards do not scroll. Keep wireframe HTML in natural flow and set a379 larger frame `height` when a screen exceeds the surface preset; preserve the380 surface width and inspect the bottom edge at default zoom before handoff.381- After every hosted write, re-read the structured content and inspect the live382 Plan surface. A valid JSON payload is not proof that CSS loaded or Markdown383 rendered into the intended heading, paragraph, and list structure.384385## Tool Guidance386387- `create-visual-plan`: start one structured visual plan per agent task/run, or388 import an existing text plan by passing `planText`; `content` may include no389 visual surface, canvas only, or canvas + prototype.390- `create-ui-plan`: start a UI-first plan when the work is primarily product UI.391- `create-prototype-plan`: start a prototype-first plan with a functional top392 review surface. If the interaction itself must also be high fidelity, set each393 screen's `renderMode` to `design` and pass scoped styles through `css`;394 otherwise use `create-plan-design` for design-first review.395- `create-plan-design`: start a full-fidelity branded Design-tab plan with an396 optional matching Prototype tab.397- `convert-visual-plan-to-prototype`: convert an existing HTML wireframe canvas398 into a prototype plan.399- `create-visual-questions`: use only when the user explicitly asks for a visual400 intake questionnaire, not as `/visual-plan` preflight.401- `update-visual-plan`: revise content, status, or comments with targeted402 `contentPatches` (see Core Workflow steps 6-7). Use403 `set-visual-render-mode` with `renderMode: "design"` when promoting an404 existing plan to high fidelity, together with deliberate screen HTML/CSS;405 render mode alone only removes sketch treatment. `replace-blocks` and full406 `content` replacement require `expectedUpdatedAt` from a fresh407 `get-visual-plan` call.408- `read-visual-plan-source`: read the normalized plan as `plan.mdx`,409 optional `canvas.mdx`, optional `.plan-state.json`, and JSON.410- `patch-visual-plan-source`: apply granular MDX AST patches by stable block,411 artboard, annotation, component, or wireframe-node id. Prefer those targeted412 operations; `replace-file` requires `expectedUpdatedAt` from a fresh413 `get-visual-plan` call.414- `import-visual-plan-source`: create or replace a plan from an MDX folder.415- `get-visual-plan`: read the current structured plan, exported HTML,416 annotations, and `plan.updatedAt`; it also returns the MDX folder for source417 workflows. Re-read immediately before a destructive write for its concurrency418 fence and again after every write to verify persisted state.419- `get-plan-feedback`: read unconsumed human feedback. Use it frequently; it420 returns grouped threads, exact anchor details, expected resolver, and recent421 review-event payloads so agents can act only on the comments meant for them.422- `get-plan-blocks`: resolve block tags before authoring — do not memorize tags;423 call this first to get the authoritative tag names, required fields, and prop424 shapes from the live block registry.425- `export-visual-plan`: export HTML, Markdown fallback, structured JSON, and MDX426 files for repo check-in.427428When the user critiques a plan's look or structure, fix the renderer or this429skill — never hand-edit one stored plan. Turn feedback into better guidance.430431## Local-Files Privacy Mode — read `references/local-files.md`432433When the user wants no hosted Plan database writes — no DB writes, no Plan MCP434publish, fully local/offline/private planning, repo-owned source-controlled435artifacts, or `AGENT_NATIVE_PLANS_MODE=local-files` — do not call any hosted Plan436tool except the schema-only `get-plan-blocks` catalog lookup. Author a local MDX437folder and438preview it with `plan local check` / `plan local serve` / `plan local verify`.439Before using local-files mode, READ `references/local-files.md` in this skill440directory — it is the single source of truth for the full contract (catalog441lookup, MDX folder layout, the local bridge commands, and the hosted tools you442must not call). Carry forward only the code-research and plan-composition443guidance from Core Workflow; everything hosted is replaced by the local bridge.444445## Interpreting comment anchors446447This section applies to hosted plans with `get-plan-feedback` /448`update-visual-plan`. In local-files mode, do not call hosted feedback or update449tools; interpret file/chat feedback directly, edit the MDX files, rerun the450local bridge check/serve/verify command, and report the new local URL.451452`get-plan-feedback` returns rich anchors — read them before acting on any comment.453454- **Coordinate frames.** `targetX`/`targetY` are percentages *within* the455 element named by `targetSelector`/`targetKind`. Bare `x`/`y` are percentages456 of the whole plan document. `canvasX`/`canvasY` are raw board-world pixels on457 the design canvas (board size given when available).458- **Wireframe pins.** Anchors on wireframes include `targetNodeId` and459 `targetNodePath` (e.g. `card > list > listItem "Acme Inc"`) identifying the460 exact kit node. Use `targetNodeId` directly with wireframe node patch ops;461 use `data-design-id` values from design artboards with462 `update-design-element-style`. Prefer the node id/path over raw coordinates;463 fall back to coordinates plus the focused screenshot (red ring marks the exact464 point) only when no node id is present.465- **Text quotes.** Resolve `textQuote` against current prose using466 `contextBefore`/`contextAfter` for disambiguation. If `ambiguous: true`, ask467 the user — do not guess which occurrence is meant.468- **Detached comments.** `get-plan-feedback` flags threads whose quoted text no469 longer exists as `detached` (in `detachedThreads`). Reconcile these against470 rewritten content — never silently drop them.471- **Routing.** `resolutionTarget` is the only routing signal: act on `agent`,472 treat `human` as context only. `@mentions` are people to notify, never a473 routing signal.474- **Two-axis state.** Mark every ingested comment as consumed475 (`consumedCommentIds` on `update-visual-plan`). Set `status=resolved` only on476 agent-targeted comments you actually addressed; leave human-targeted comments477 open. When an edit addresses feedback, first re-read the persisted plan and478 verify the requested change. Only then call `resolve-plan-comment` for the479 addressed thread and `consume-plan-feedback` for its comments; never mark480 addressed feedback along only one axis.481482## Visibility & Sharing483484Use `set-resource-visibility` to change who can see a plan (e.g. public, login,485or org-scoped). Use `share-resource` to grant specific users or roles access486by email or role. Gate visibility before sharing any plan that covers487unreleased or private work — default to the narrowest scope that meets the488review need.489490## Setup & Authentication491492There are two ways into Plans.493494**Coding agent (CLI).** Install once with the Agent-Native CLI. The command495installs the Plans skills, registers the hosted Plans MCP connector, and runs496auth/setup for the selected local client(s) in the same step (a one-time browser497sign-in at setup — this is intended), so the first tool call in that client does498not hit an OAuth wall:499500```bash501npx @agent-native/core@latest skills add visual-plans502```503504After that, `/visual-plan`, `/visual-recap`, and `/visualize-repo` are the505installed slash commands. If you only need one command, use506`skills add visual-plan`, `skills add visual-recap`, or507`skills add visualize-repo` instead. The other planning modes508(`create-ui-plan`, `create-prototype-plan`, `create-plan-design`,509`create-visual-questions`) are MCP tools reachable from `/visual-plan`, not510separate slash commands. Pass `--no-connect` to register the connector without511authenticating, then run512`npx @agent-native/core@latest connect https://plan.agent-native.com --client all`513whenever you are ready, or choose a narrower `--client`. Auth and MCP tool514loading are per client config/session.515516**Browser (people you share with).** Open the Plans editor and create & edit517with no sign-up — you work as a guest. Sign in only when you want to save or518share; signing in claims the plans you made as a guest into your account.519520Sharing and commenting require an account: public/shared plans are viewable by521anyone with the link, but commenting on them needs an agent-native account.522523For fully offline, no-account use, run the Plans app locally and sync plans to524your repo as MDX. This local mode is a separate advanced path, not the default525hosted flow.526527For repo-wide visual docs, run528`npx @agent-native/core@latest visualize-repo --open` to create/update529`agent-native.json`, seed `.agent-native/visual-docs/repo-overview`, and open530the local bridge.531532If a Plans tool returns `needs auth`, `Unauthorized`, or `Session terminated`, do533not keep retrying it — stop and give the user the per-client reconnect step from534`references/connection.md`, then continue once the connector is available.535536Hosted default: connect `https://plan.agent-native.com/mcp`. Do537not put shared secrets in skill files.