plan-source-sync

---
name: plan-source-sync
description: >-
  The MDX source surface for plans: export, import, patch by semantic ID, DB-free
  local plan folders, `comments.json` sidecars, promotion into a repo, and the
  Desktop folder bridge. Use when a plan must round-trip to or from repo files.
---

# Plan Source Sync

## Source Surface

Runtime plan content is normalized JSON in SQL. MDX is the source-control
surface: `plan.mdx` for frontmatter plus markdown/document blocks,
`prototype.mdx` for optional Prototype/PrototypeScreen/PrototypeTransition
markup, `canvas.mdx` for optional DesignBoard/Section/Artboard/Screen/
Annotation/Connector markup, optional `assets/`, and optional
`.plan-state.json`.

## Rules

- Use `export-visual-plan` or `read-visual-plan-source` when a user or external
  agent wants plan files to check into a repo.
- Use `get-local-plan-folder` to read a DB-free local MDX folder from
  `PLAN_LOCAL_DIR` or from a repo-relative `path`, and
  `update-local-plan-folder` to apply structured `contentPatches` back to that
  same folder. Pass `path` whenever the user is viewing a
  `/local-plans/:slug?path=...` URL. These local-folder actions do not read or
  write SQL.
- Use `update-local-plan-comments` to add, reply to, resolve, or delete review
  comments on a local plan. They persist to a `comments.json` sidecar beside
  `plan.mdx` (committed with the plan, no SQL), are always addressed to the
  agent (`resolutionTarget: "agent"`), and are surfaced by `get-local-plan-folder`.
  Local comments are a one-way handoff to the coding agent — delivery is the
  composer's "Send to agent" copy-to-clipboard, not notifications or sharing.
  In bridge mode the read-only bridge serves no comments, so the colocated
  folder's `comments.json` is merged in for display and persistence.
- Use `promote-local-plan-folder` when a temporary local plan should be saved
  into the repo. Its default target is `apps.plan.roots[0].path/<slug>` from
  `agent-native.json`, falling back to `plans/<slug>`.
- Commit `.plan-state.json` with repo-backed plan folders when present. It is
  source metadata for stable bare-Markdown block IDs, not a disposable preview
  cache.
- Use `import-visual-plan-source` to create or replace a plan from an MDX folder.
- Use `patch-visual-plan-source` for small source edits by stable semantic IDs.
  It patches the MDX AST, runs formatting, parses back to normalized JSON, and
  persists the runtime model. Prefer this over regenerating a whole plan when the
  requested change is a few lines, one annotation, one artboard, or one
  wireframe node.
- `replace-file` is a destructive source operation. Use it only when targeted
  source patches cannot express the edit, after a fresh `get-visual-plan`, and
  pass that read's `plan.updatedAt` as `expectedUpdatedAt`. Re-read the plan
  after the patch and verify that unrelated MDX files and visual surfaces were
  preserved.
- In Agent-Native Desktop, the Plan menu can link a user-chosen local folder for
  the current plan, write the exported MDX files to it, import local edits back
  through `import-visual-plan-source`, and optionally auto-export whenever the
  hosted plan changes. This is a native desktop bridge; it does not require a
  cloned Plan app or CLI process.
- Do not fork the vocabulary. MDX components must map to the same runtime terms:
  `DesignBoard`, `Section`, `Artboard`, `Screen`, `Annotation`, `Connector`, and
  the wireframe kit primitives from `shared/plan-content.ts`.

## Related Skills

- **plan-hosted-writes** — the revision guard `replace-file` depends on.
- **plan-browser-editing** — how local folders autosave from the browser.
- **visualize-repo** — repo-native visual docs built on local plan folders.