plan-source-sync

# 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.