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