plan-authoring-flow

# Plan Authoring Flow The plan skills carry the shared Wireframe & Canvas and Document Quality cores, so those rules are not restated in `AGENTS.md`. When the user critiques a plan's look or structure, fix the renderer or the sync-guarded skills (not just one stored plan) so the improvement sticks. ## Plan Content Surface material assumptions only when they change behavior, data, security, tests, deployment, or definition of done. ## Wireframe Markup New canvas wireframes must use `<Screen html={...} />` / `data.html` semantic HTML. Nested kit-tree nodes such as `FrameScreen`, `Card`, `Row`, and `Btn` are legacy compatibility only and should not be authored for new plans/recaps. ## Normal Planning Flow `/visual-plan` is the main command. Treat it like the host agent's standard planning mode: inspect the codebase, use parallel agents when useful, gather the information needed, ask clarifying questions through the host's native ask-user-question tools when needed, then call `create-visual-plan` to publish the plan. When the user pasted, referenced, or already has a Codex / Claude Code / Markdown plan, keep `/visual-plan` as the command and pass the source text to `create-visual-plan` as `planText` so the new review surface builds from what they already have. For UI-first work where the plan leads with product screens, use `/visual-plan` and call `create-ui-plan`. For prototype-first work — when the user needs to operate the behavior before implementation — use `/visual-plan` and call `create-prototype-plan`. Prototype plans must be functional review surfaces with local state and realistic controls; do not pass off static screen-to-screen navigation as a prototype. Keep static mocks in the document and use the top viewer for functional review, comments, rough/clean mode, dark/light mode, and prototype popout. (`create-prototype-plan` is an MCP tool reached from `/visual-plan`, not a separate slash command.) For full-fidelity branded UI design before implementation, use `/visual-plan` and call `create-plan-design`. Research the real app shell, `design.md` if present, `.fig` brand-kit/design-system data when available, and codebase CSS/Tailwind/ token signals. Pass high-fidelity bounded HTML/CSS screens for the Design tab, stable `data-design-id` attributes for targeted element style edits, and transitions only when a matching Prototype tab should be clickable. Treat the Design tab as the visual source of truth and the Prototype tab as the same direction made interactive. (`create-plan-design` is an MCP tool reached from `/visual-plan`, not a separate slash command.) Treat “higher fidelity,” “pixel-accurate,” “polished mockup,” “production-like,” “real design,” and “not a sketch/wireframe” as design-first requests, even when the prompt also says “mockup.” For an existing plan, do not create a duplicate: call `update-visual-plan` on the same plan id with a `set-visual-render-mode` patch using `renderMode: "design"`, and replace or patch the affected screen HTML/CSS in the same update. Put scoped styles in each screen's `css` field, never in `<style>` tags. Merely switching the viewer-local Clean toggle removes rough.js for one browser but does not create a high-fidelity artifact. Use `/visual-recap` when the user wants a high-level review surface for a PR, commit, branch, or git diff that already changed. Recaps are reverse plans: derive blocks from the real diff, call `create-visual-recap` with the recap MDX source, publish it as a review aid, and state that reviewers still need to inspect the actual changed lines. The markdown/document portion should stay close to the plan the agent would normally produce. Diagrams, wireframes, mockups, annotations, and an optional bottom `question-form` Open Questions block are additive review aids, not a separate intake flow. Do not automatically call `create-visual-questions` from `/visual-plan`. If a normal plan has answerable unresolved decisions, keep them in the same plan as a bottom `question-form` block with single-choice, multi-choice, or freeform questions, recommended options when useful, and wireframe/diagram previews for visual directions. If the user explicitly requests a visual intake questionnaire before planning, call `create-visual-questions` from `/visual-plan`. (`create-visual-questions` is an MCP tool reached from `/visual-plan`, not a separate slash command.) ## Related Skills - **visual-plan** — the canonical `/visual-plan` skill, carrying the shared Wireframe & Canvas and Document Quality cores. - **visual-recap** — `/visual-recap` recap generation. - **plan-hosted-writes** — session, revision guard, and post-write verification for every plan write this flow performs. - **plan-review-recaps** — recap comparison blocks and the PR recap workflow.