generate-visual-plan

Read cards/visual-plan.md. Use cards/code-walkthrough.md for any section that mainly explains code.

Load the visual-explainer skill, then generate a comprehensive visual implementation plan for $@ as a self-contained HTML page.

Authoring contract. Prefer the MDX/React pipeline. Write the editable plan as .mdx by default, or .tsx when the plan needs heavier custom state, bespoke generated diagrams, or interaction beyond reusable components. Use shared components from visual-explainer-mdx/components.tsx for shells, sections, pipelines, tables, callouts, and risk ledgers. Export the generated standalone HTML with:

npm run ve:export -- <source.mdx> --out ~/.agent/diagrams/<feature-name>-plan.html

The generated HTML is the artifact, not the source of truth. If facts change or review feedback arrives, edit the MDX/TSX source and re-export. Use the legacy HTML reference templates only for layout and aesthetic guidance; do not hand-write final HTML unless the MDX/React path is blocked and you explicitly report that fallback.

Clarify. This is a Tier 1 command per ./references/clarify.md. Ask via AskUserQuestion only if the feature scope, audience, or required depth is unclear. Skip the ask if the request + codebase context answer all four brief dimensions. Bypass with --no-ask.

Follow the visual-explainer skill workflow and the card. Use the default OA Design preset and read references/oa-design.md unless the user requests a named alternative.

Data gathering phase — understand the context before designing:

1. Parse the feature request. Extract:

   • The core problem being solved
   • Desired user-facing behavior
   • Any constraints or requirements mentioned
   • Scope boundaries (what's explicitly out of scope)

2. Read the relevant codebase. Identify:

   • Files that will need modification
   • Existing patterns to follow (code style, architecture, naming conventions)
   • Related functionality that the feature should integrate with
   • Types, interfaces, and APIs the feature must conform to

3. Understand the extension points. Look for:

   • Hook points, event systems, or plugin architectures
   • Configuration options or flags
   • Public APIs that might need extension
   • Test patterns used in the codebase

4. Check for prior art. Search for:

   • Similar features already implemented
   • Related issues or discussions
   • Existing code that can be reused or extended

Design phase — work through the implementation before writing HTML:

1. State design. What new state variables are needed? What existing state is affected? Draw the state machine if behavior has multiple modes.

2. API design. What commands, functions, or endpoints are added? What are the signatures? What are the error cases?

3. Integration design. How does this feature interact with existing functionality? What hooks or events are involved?

4. Edge cases. Walk through unusual scenarios: concurrent operations, error conditions, boundary values, user mistakes.

Verification checkpoint — before generating HTML, produce a structured fact sheet:

• Every state variable (new and modified) with its type and purpose
• Every function/command/API with its signature
• Every file that needs modification with the specific changes
• Every edge case with expected behavior
• Every assumption about the codebase that the plan relies on Verify each against the code. If something cannot be verified, mark it as uncertain. This fact sheet is your source of truth during HTML generation.

Diagram structure — the page should include:

1. Header — feature name, one-line description, scope summary. Visual treatment: use a distinctive header with monospace label ("Feature Plan", "Implementation Spec", etc.), large italic title, and muted subtitle. Set the tone for the page.

2. The Problem — side-by-side comparison panels showing current behavior vs. desired behavior. Use concrete examples, not abstract descriptions. Show what the user experiences or what the code does, step by step. Visual treatment: two-column grid with rose-tinted "Before" header and sage-tinted "After" header. Numbered flow steps with arrows between them.