@hybridlabor-api/aos 4.17.0 → 4.18.0

package/skills/global_config/visual-plan/README.md

@@ -1,93 +0,0 @@
-# /visual-plan
-
-Turn ordinary implementation plans into rich interactive visual review surfaces.
-
-`/visual-plan` turns the plan an agent would normally write in chat into a
-human-optimized MDX document. In local-files mode, it writes and serves the MDX locally rather than publishing to the hosted Plan database. Instead of a long wall of prose, reviewers get
-custom components built for understanding: architecture diagrams, wireframes,
-interactive prototypes, file maps, annotated code, OpenAPI-style API specs,
-visual schema maps, open questions, and comments.
-
-It solves for plans that are too important to bury in chat. The output is
-scannable, commentable, and intuitive enough for a human to approve before code
-changes start.
-
-<picture>
-  <img alt="Visual plan review surface" src="../../media/visual-plan.png">
-</picture>
-
-Visual plans are MDX, customizable with your own components, and viewed with the
-[Agent-Native plans app](https://www.agent-native.com/docs/template-plan). The
-hosted app is 100% free and open source; local-files mode writes
-MDX locally, starts a localhost bridge, and opens the hosted Plan UI with no
-sharing.
-[Source here](https://github.com/BuilderIO/agent-native/).
-
-## What It Does
-
-- Grounds plans in real repo files, schemas, actions, and symbols.
-- Chooses the right visual surface: document-only, wireframe canvas, prototype,
-  design direction, or visual intake.
-- Uses MDX and custom components for diagrams, UI flows, API specs, schema maps,
-  diffs, code annotations, and reviewer questions.
-- Publishes the result as an interactive review document instead of inline chat Markdown.
-- Keeps the plan as the approval gate before source edits begin.
-
-## When To Use It
-
-Use it for multi-file, ambiguous, risky, architecture-heavy, data-heavy, or
-UI-heavy work where the wrong direction would be expensive. It is also useful
-when a pasted text plan needs a richer review surface.
-
-Skip it for trivial fixes, single-line changes, or anything whose diff is easier
-to review than a plan.
-
-## What Reviewers Get
-
-Reviewers get a plan link that is built for scanning. Decisions, files,
-diagrams, contracts, UI states, prototype behavior, schema shape, API boundaries,
-and unresolved questions live in one consumable place.
-
-For teams wiring visual plans into their review flow, the
-[Plan app documentation](https://www.agent-native.com/docs/template-plan)
-explains how the review surface is rendered and shared.
-
-The point is not just prettier planning. It is a better medium for human review:
-visual where visuals help, structured where structure helps, and grounded in the
-actual codebase.
-
-## Modes
-
-`/visual-plan` can run in three modes:
-
-- **Hosted Plans, shareable links (recommended):** uses the free, open-source
-  Agent-Native plans app at plan.agent-native.com for shareable links, comments,
-  and the browser editor.
-- **Local files only:** writes a local MDX folder, starts a localhost bridge,
-  and opens the hosted Plan UI against that local source. No sharing, all local,
-  and no plan content is written to the hosted database. The skill must not
-  create a hosted Plan first and export it back to local files.
-- **Self-hosted/custom URL:** connects the skill to your own Plan app or local
-  development tunnel.
-
-Use hosted mode when you want comments and shareable links. Use local files mode
-when the plan itself should live in source control or stay on your machine. Use
-`plans/<slug>/` when you want to check the files in, or a temp/ignored folder
-when you do not. The bridge URL works on the machine running it and is not a
-share link.
-
-## Install
-
-```sh
-npx @agent-native/skills@latest add --skill visual-plan
-```
-
-The interactive installer asks whether to use hosted Plans or local files. To
-force the no-sharing local path:
-
-```sh
-npx @agent-native/skills@latest add --skill visual-plan --mode local-files
-```
-
-The skill expects the [Plan MCP connector](https://www.agent-native.com/docs/template-plan)
-to be available when hosted mode is used.

package/skills/global_config/visual-plan/SKILL.md

@@ -1,544 +0,0 @@
----
-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.
-category: design-ui-ux
-source: BuilderIO/skills
----
-
-# Agent-Native Plans
-
-Agent-Native Plans is structured visual planning mode for coding agents. Build
-the plan you would normally write in Markdown, but as a scannable document with
-editable blocks mixed in: inline diagrams, code snippets,
-open questions, and an optional top visual review area (wireframe canvas, live
-prototype, or both in tabs). Architecture and backend plans stay document-only;
-UI and product plans start with the top canvas/prototype (the Visual Surface
-Choice section owns that rule).
-
-`/visual-plan` is the packaged command and main entry point. Choose the review
-mode from the task: UI-first when the work is primarily product UI and review
-should start with screens, prototype-first when review should start with a
-functional live prototype, design-first when review needs full-fidelity branded
-screens, or visual-intake when the user explicitly wants a questionnaire before
-planning. When a Codex, Claude Code, Markdown, or pasted plan already exists,
-`/visual-plan` uses that source plan as the starting point and builds the review
-surface from it instead of starting over.
-
-## When To Use
-
-Create or adapt a visual plan whenever the plan would be better as a reviewable
-artifact than a chat paragraph. This includes modest work such as a single UI
-surface with states, a small workflow, a before/after product change, or a
-component/API/data-shape decision that needs alignment, plus larger multi-file,
-ambiguous, long-running, risky, or UI-heavy work. Use it when architecture /
-data flow / UI direction / options / open questions would benefit from inline
-diagrams or structured blocks, when the user needs to react to a direction
-before you implement, or when an existing text plan needs a richer review
-surface.
-
-## Plan Discipline
-
-- **Gate thoughtfully.** A visual plan is a richer review surface, not only a
-  tool for giant projects. Use it when the user needs to see, compare, comment
-  on, or approve a direction before code, even for a modest UI/state/workflow
-  change. Skip it for truly trivial, unambiguous work — typos, one-line fixes, a
-  single well-specified function, anything whose diff you could describe in one
-  sentence — and just make the change. Never pad a plan with filler and never
-  ship a single-step plan.
-- **Research before you draft.** Read the real files, actions, schema, and
-  patterns first; name actual files, symbols, and data shapes instead of
-  inventing them. Check existing `actions/` before proposing endpoints and prefer
-  named client helpers over raw fetch. Delegate wide exploration to a sub-agent.
-  Lead with reuse: for each step, name what it reuses — existing actions, schema,
-  components, helpers — before what it adds, so the plan explains the genuinely new
-  delta instead of redescribing what already exists.
-- **Decide the hard-to-reverse bets first.** For non-trivial backend, data, or API
-  work, sketch where the feature is headed, then call out the decisions that are
-  expensive to undo once data or callers depend on them — wire format, public ids,
-  data-model shape, auth and ownership boundaries — and get those right in the plan
-  even if most of the feature ships later. Then scope to the smallest first cut that
-  proves the approach without foreclosing it, stating both what is in and what is
-  explicitly deferred.
-- **Keep examples at the right altitude.** When the user's idea is a broad
-  framework, product, or operating-model change, do not collapse it into the
-  first concrete example, provider, or sync path they mention. Separate the core
-  abstraction from motivating examples and app/provider adapters. Use examples
-  to make the plan legible, but label them as examples unless they are the whole
-  requested scope.
-- **Publish standalone plans.** If the user pasted, referenced, or already has a
-  Codex / Claude Code / Markdown plan, treat it as source material, but rewrite
-  the published plan as a clean standalone proposal. Preserve the source plan's
-  useful intent and codebase facts, label inferred visuals as inferred, and avoid
-  revision language such as "preserve the prior plan", "do not drop the old
-  idea", "unlike the previous version", or "this revision changes...". A reader
-  who never saw the chat or earlier drafts should understand the plan.
-- **Make the first read concrete.** If the plan is meant to be shared with
-  someone outside the chat, or if the concept is abstract, lead near the top with
-  one concrete product example before mode tables, architecture, or roadmaps. For
-  UI-capable concepts, that usually means a top-canvas app state that shows the
-  real user workflow in product terms. Do not rely on phrases that only make
-  sense in conversation, and do not frame the plan as "not the old idea"; state
-  the positive model directly.
-- **Planning is read-only.** Make no source edits while building or reviewing the
-  plan. Start editing only after the user approves the direction.
-- **Clarify vs. assume.** Do not ask how to build it — explore and present the
-  approach and options in the plan. Ask a clarifying question only when an
-  ambiguity would change the design and you cannot resolve it from the code; use
-  the host agent's normal ask-user-question flow and batch 2-4 high-leverage
-  questions before finalizing. Do not call `create-visual-questions` for
-  ordinary clarification or preflight; reserve it for the visual-intake mode when
-  the user explicitly asks for a visual intake questionnaire. Otherwise state the
-  assumption explicitly and proceed, and keep anything unresolved in the plan's
-  single bottom `question-form` Open Questions block. For complex plans, do a
-  final open-question pass before handoff: if a decision would affect
-  architecture, scope, UX, data shape, or rollout, either decide it in the plan
-  with rationale or put it in that bottom form with a recommended default.
-- **The plan is the approval gate.** After surfacing it, ask the user to review
-  and approve before you write code, and name which files/areas the work touches.
-  Presenting the plan and requesting sign-off is the approval step — do not ask a
-  separate "does this look good?" question.
-- **The document is the source of truth, not the chat.** When scope shifts,
-  update the plan with `update-visual-plan` rather than only changing course in
-  chat, and make the updated document stand alone. Do not describe the update as
-  a correction to an earlier draft inside the plan itself. Re-read the approved
-  plan before major steps.
-
-## Create A Structured Agent-Native Plan — Never Inline
-
-The deliverable is ALWAYS a structured Agent-Native Plan, not a chat-only plan.
-The hosted Plan MCP connector (`plan` server, or legacy `agent-native-plans`) is
-the default collaboration and commenting surface; it is not a reason to reject
-the planning pattern as an external dependency or rented layer. Plans are
-portable source artifacts (`plan.mdx`, optional `canvas.mdx` /
-`prototype.mdx`, JSON, and HTML export), and ownership-sensitive workflows can
-use local-files mode or a self-hosted/custom Plan app URL without abandoning the
-skill's review discipline. Do not advise the user to skip `/visual-plan` because
-the default surface is hosted; choose the right Plan mode for the user's
-ownership, privacy, sharing, and branding needs.
-
-By default, create the plan via the Plan MCP connector and NEVER hand it over as
-inline chat content — no Markdown prose, ASCII sketch, table, or fenced
-wireframe. If the `plan` (or legacy `agent-native-plans`) tools are not visible,
-discover them through the host's `tool_search` first; if they are still missing,
-STOP and give the user the client-specific reconnect step rather than improvising
-an inline plan. Before publishing, or whenever a connector or auth error appears,
-READ `references/connection.md` in this skill directory — it is the single source
-of truth for the never-inline rule, connector discovery, and the per-client
-reconnect steps. Local-files privacy mode (after Tool Guidance) is the exception.
-
-## Core Workflow
-
-This section describes the default hosted Plan MCP workflow. If
-`AGENT_NATIVE_PLANS_MODE=local-files` is set, or the user asks for fully local
-files/no hosted Plan writes, use **Local-Files Privacy Mode** instead; carry
-forward only the code-research and plan-composition guidance here.
-
-1. Follow the host agent's normal planning flow: inspect the codebase, delegate
-   wide exploration when useful, gather the info needed, and ask native
-   clarifying questions as needed before generating the plan. If a source plan
-   already exists, gather its exact text from the user's paste, a referenced
-   file, or recent visible agent context; do not invent source text.
-2. Call `get-plan-blocks` for the authoritative block catalog — do not author
-   from memorized tags. Then call the mode-matched create tool:
-   `create-visual-plan` for document-first plans (architecture, backend, data,
-   refactor, API), `create-ui-plan` for UI-first plans, `create-prototype-plan`
-   for prototype-first plans, `create-plan-design` for design-first plans,
-   `create-visual-questions` only when the user explicitly asks for a visual
-   intake questionnaire. When a source plan already exists,
-   pass it as `planText` and preserve the original plan's useful intent while
-   producing a standalone plan document, not a revision memo.
-3. For UI/product plans, compose the top canvas first with the primary
-   wireframes and annotated states, then write the document with native blocks
-   (see `references/canvas.md` and `references/document-quality.md`). For
-   broad product architecture plans with a user-facing implication, add a
-   concrete "what this looks like in the app" visual before the abstract
-   architecture or mode tables. Keep the document close to the standalone
-   Markdown plan the agent would normally output. If an existing plan was
-   provided, carry forward the right facts and decisions without referring to
-   the previous draft or explaining how this version differs. For non-visual
-   plans, skip the top visual surface (Visual Surface Choice below owns the rule)
-   and put `diagram`, `data-model`,
-   `api-endpoint`, `diff`, `file-tree`, `code`, and `annotated-code` blocks
-   directly next to the relevant prose.
-   Wide document layout is renderer-owned and intentionally allowlisted: only
-   literal code-review surfaces (`diff`, `annotated-code`) and `tabs` blocks
-   with vertical orientation or diff-like children break out wider than prose.
-   Keep `api-endpoint`, `openapi-spec`, `data-model`, `json-explorer`,
-   `wireframe`, question, and `custom-html` blocks in normal document flow unless
-   their own renderer says otherwise.
-4. Surface the returned Plans link or inline MCP App and ask the user to review.
-   Always include the actual URL in chat so the next step is a click in CLI or
-   other text-only hosts. When the host exposes an embedded browser/preview panel
-   and a tool can open arbitrary URLs there, open the returned plan URL
-   automatically for convenient review — a convenience and smoke test, never the
-   only handoff or the access
-   model. Plans should load out of the box for the local agent and local browser
-   session; if a signed-in embedded browser cannot read a local plan that an
-   anonymous/tool check can read, fix the app/action ownership or access path
-   rather than patching one plan by hand. For high-stakes plans (architecture,
-   backend, data, multi-file, or risky), also kick off the self-review pass in
-   **Self-Review Before Handoff** while the user reads, instead of blocking the
-   handoff on it.
-5. For hosted plans, call `get-plan-feedback` before editing, after review,
-   after any long pause,
-   and before the final response. Treat `anchorDetails`, resolver intent, recent
-   review events, and any focused screenshots from browser handoff as the source
-   of truth for exactly what changed and exactly what each comment points at.
-6. For hosted plans, apply changes with `update-visual-plan`, preferring
-   targeted `contentPatches`.
-   Treat the top-level `content` payload as a full replacement, not a merge; do
-   not send a partial `content` object to add a canvas or one block. If a full
-   replacement 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.
-7. 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.
-8. 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:
-
-```bash
-npx @agent-native/core@latest skills add visual-plans
-```
-
-After that, `/visual-plan`, `/visual-recap`, and Builder's visualize-repo (not part of AOS) 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.
-
-## AOS notes
-
-This skill is optional and drives the Agent-Native Plan service through an MCP
-connector named `plan` that AOS does NOT register or install — you connect it
-yourself. It may point at a self-hosted or local Plan app URL. Do not run any
-`npx @agent-native/...@latest` command from this skill unless you explicitly
-approved the network access in this conversation. Hosted publishing, posting to
-GitHub, merging, and any other external write need your literal GO (AOS go-gate).
-When the optional local BDB Plan Builder is installed, it can serve the same tool
-names locally (planned, not yet built; say so).