@agent-native/core 0.101.14 → 0.102.1

package/corpus/templates/tasks/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/tasks/.agents/skills/visual-plan/SKILL.md

@@ -0,0 +1,547 @@
+---
+name: visual-plan
+description: >-
+  Turn ordinary text plans into rich interactive visual plans with diagrams,
+  file maps, annotated code, open questions, and UI/prototype review when
+  useful.
+metadata:
+  visibility: exported
+---
+
+## Installed Mode
+
+Default storage for this installation: local files. Create and update plans and
+recaps as MDX folders under `plans/<slug>/` when they should be checked in, or
+under a repo-ignored/temp folder when they should stay private scratch. Before
+authoring structured MDX, run
+`npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read the
+no-auth block catalog; it sends no plan content. Then run
+`npx @agent-native/core@latest plan local check --dir plans/<slug>`, then
+`npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan|recap --open`,
+and report the local bridge URL from stdout or `plans/<slug>/.plan-url`. Treat
+`.plan-url` as a local token file and do not commit it. It opens the hosted Plan
+UI but reads from the localhost bridge on this machine, so it is not shareable
+across machines. On macOS, use Chrome/Chromium if Safari blocks the localhost
+bridge; run `plan local verify --dir plans/<slug> --kind plan|recap` for
+headless diagnostics. No sharing, all local. Use a hosted or self-hosted Plan MCP
+connector only if the user explicitly asks to publish or share.
+
+
+# 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. NEVER hand the plan over
+as inline chat content — no Markdown prose, ASCII sketch, table, or fenced
+wireframe. Some clients lazy-load connector tools through a deferred tool
+registry instead of showing the `plan` namespace upfront; before declaring the
+connector missing, search/load tools with the host's discovery surface
+(`tool_search` when available) for `create_visual_plan`, `create_ui_plan`, or
+`get_plan_blocks`, then use the Plan MCP tools it exposes. If the connector's
+tools are still missing after discovery, do NOT fall back to inline output: the
+usual cause is a connector that did not finish connecting this session (it
+registers zero tools), not auth. Stop and give the user the exact restore step
+for their current client: in Codex/Codex Desktop run
+`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
+and start a new Codex session; in Claude Code run `/mcp` and choose
+Authenticate/Reconnect (or run the same reconnect command with
+`--client claude-code` and restart Claude). Auth is stored per client
+config/session, so one client's reconnect does not make another running client
+load tools. Never reinstall from scratch just to fix auth. Publish once the tool
+is reachable. 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
+
+Use local-files privacy mode when the user explicitly asks for no DB writes,
+no hosted Plan database writes, no Plan MCP publish, fully local files, offline/private
+planning, repo-owned/source-controlled planning artifacts, or when
+`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo
+policy says a plan must stay under their own brand, domain, source control, or
+infrastructure. In this mode the plan data must never be sent to the Plan MCP
+server or Plan app action surface. Schema-only block catalog lookup is allowed
+because it sends no plan content: use the MCP `get-plan-blocks` tool if it is
+already available, or run
+`npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
+file before authoring MDX.
+
+The local-files contract is:
+
+- Read source context from local files and shell commands only.
+- Fetch/read the block catalog before writing structured MDX. The
+  `plan blocks` command calls the public no-auth `get-plan-blocks` route and
+  writes only registry metadata to disk; use `--format schema` if exact nested
+  fields are needed. If network access is unavailable, use the bundled
+  references and rely on `plan local check` / `plan local serve` to catch
+  invalid tags. For `checklist` and `question-form`, copy the catalog examples
+  verbatim: checklist items need `id` and `label`; question-form questions need
+  `id`, `title`, and `mode`; and each option needs `id` and `label`. `plan local
+  check` validates these required fields against the renderer schema.
+- Write the plan as a local MDX folder: use `plans/<slug>/` when the user
+  wants the artifact checked into the repo, or use a repo-ignored/temporary
+  folder such as `.agent-native/plans/<slug>/` or `/tmp/agent-native-plans/<slug>/`
+  when it should not be checked in. The folder contains `plan.mdx`, optional
+  `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`. Use
+  that exact chosen folder as `<plan-dir>` in every local CLI command below.
+- Run `npx @agent-native/core@latest plan local check --dir <plan-dir>` before
+  serving, then run
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind plan --open`.
+  Report the returned local bridge URL from stdout or `<plan-dir>/.plan-url`.
+  Treat `.plan-url` as a local token file and do not commit it. The URL opens
+  the hosted Plan UI but reads from the localhost bridge on this machine, so it
+  is not shareable across machines. On macOS, `--open` prefers Chromium browsers;
+  if Safari opens, switch to Chrome/Chromium because Safari can block the hosted
+  HTTPS page from fetching the HTTP localhost bridge. If the Plan app itself is
+  running locally with the same `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route
+  is also valid.
+- For headless verification, run
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind plan`.
+  It starts the bridge, checks the private-network preflight and JSON payload,
+  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
+  the `bridgeUrl` from the verify/serve JSON to read the concrete validation
+  error.
+- Do **not** call `create-visual-plan`, `create-ui-plan`,
+  `create-prototype-plan`, `create-plan-design`, `import-visual-plan-source`,
+  `update-visual-plan`, `patch-visual-plan-source`, `get-plan-feedback`,
+  `export-visual-plan`, or any hosted Plan tool for that plan except the
+  schema-only block catalog lookup above.
+- Treat feedback as file or chat feedback: update the MDX files directly, rerun
+  the local bridge command, and summarize the new local bridge URL. Hosted
+  comments, sharing, history, and publish/export receipts are unavailable until
+  the user explicitly opts into publishing.
+
+Local-files mode prevents plan content from going to the Agent-Native Plan
+database. It does not by itself make the coding agent's language model local;
+for that stronger privacy boundary, the host agent/model must also be local or
+otherwise approved by the user.
+
+## 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-plan
+```
+
+After that, `/visual-plan` and `/visual-recap` are the two installed slash
+commands. 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 the tool. Stop and give the user the reconnect step for the
+client they are using: Codex/Codex Desktop should run
+`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
+and start a new Codex session; Claude Code should run `/mcp` and choose
+Authenticate/Reconnect for the plan connector, or run the reconnect command with
+`--client claude-code` and restart Claude. To refresh every local client config
+that already has the Plan entry, use `--client all`, then restart/reload each
+client. Reconnect re-authenticates WITHOUT reinstalling and finds the entry by
+URL regardless of connector name. Never reinstall from scratch just to fix auth.
+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.

package/corpus/templates/tasks/.agents/skills/visual-plan/agent-native-skill.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "source": "agent-native",
+  "appSkillId": "visual-plans",
+  "displayName": "Agent-Native Plan",
+  "skillName": "visual-plan",
+  "contentHash": "c99dd919b61d7b7e",
+  "mcpUrl": "",
+  "installedAt": "2026-06-24T09:25:14.733Z",
+  "updateCommand": "npx @agent-native/core@latest skills update visual-plan",
+  "planMode": "local-files"
+}