Plan Authoring Flow

---
name: plan-authoring-flow
description: >-
  Which Plan command and creation action fits a request — document-first,
  UI-first, prototype-first, design-first, recap, or visual intake — plus how to
  raise an existing plan to design fidelity. Use when creating, routing, or
  re-rendering a plan.
---

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