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.