Htmlvspec

htmlvspec

Purpose

Produce a visual engineering implementation plan as one self-contained HTML page — specs/<plan-name>.html — that you can open directly in a browser. The plan is authored directly in HTML using the template below, with one AI-generated diagram image per section (hero + per major H2) generated in parallel and embedded inline, and a dedicated Freeform zone that lets you author any HTML you want (interactive toggles, animated SVG flows, comparison matrices, decision trees, etc.) to make the plan clearer and richer than prose could.

Phases, in order:

1. Plan phase — analyze, explore, design (same thinking as a normal spec).
2. HTML authoring phase — write the plan into the HTML Plan Template.
3. Image phase — generate one diagram per section in parallel and embed them inline.
4. Freeform phase — enrich the page with custom HTML per the Freeform Instruction Set.

Variables

USER_PROMPT: $1 ALL_ARGUMENTS: $ARGUMENTS PLAN_OUTPUT_DIRECTORY: specs/ PLAN_SLUG: kebab-case name derived from the plan topic (e.g. in-memory-ttl-lru-cache) HTML_OUTPUT: specs/htmlvspec-<PLAN_SLUG>.html — the filename MUST always begin with the htmlvspec- prefix IMAGE_DIR: specs/htmlvspec-<PLAN_SLUG>/ — sibling directory matching the HTML filename (same htmlvspec- prefix) IMAGE_GENERATOR: ~/.claude/skills/htmlvspec/scripts/generate_image.py IMAGE_SIZE: 2048x1152 (wide 16:9 by default) IMAGE_QUALITY: high HERO_IMAGE_NAME: 00-hero.png MAX_TEXT_LABELS_PER_IMAGE: 10 MAX_TOTAL_IMAGES: 10

Instructions

Plan phase

• IMPORTANT: If no USER_PROMPT is provided, stop and ask the user to provide it.
• Carefully analyze the USER_PROMPT. Determine task type (chore|feature|refactor|fix|enhancement) and complexity (simple|medium|complex).
• Think deeply (ultrathink) about the best implementation approach.
• Explore the codebase to understand existing patterns and architecture.
• Decide which sections from the HTML Plan Template apply (include the conditional sections only when task type/complexity warrants them, exactly like a normal spec).
• Generate a descriptive kebab-case PLAN_SLUG from the topic.

HTML authoring phase

• Author the plan directly in HTML using the HTML Plan Template below — do not write a markdown file. The output is a single specs/htmlvspec-<PLAN_SLUG>.html.
• Keep the page self-contained: all CSS inline in <style>, any JS inline in <script>, no external network/CDN dependencies unless genuinely required (and if so, note it in Notes).
• Fill every applicable section with real, detailed content — the plan must be implementable by another developer. Use semantic HTML: <ul>/<ol> for lists, <table> for comparisons, <pre><code> for code/commands.
• Preserve the dark visual theme defined by the template's CSS tokens so the page and the generated diagrams read as one body of work.
• Include the template's <figure>/<img> slots for the hero and every section that benefits from a diagram.

Image phase

• Always generate images — this is the defining feature of this skill; skipping the image phase is a defect. At minimum generate the hero plus one image for every major section in the template that survives (Solution Approach, Implementation Phases, plus any section whose ideas are inherently spatial — architecture, data model, sequence, state).
• Be liberal, not stingy. A section benefits from a generated image whenever the underlying concept is spatial, structural, temporal, or topological — architecture views, data/control flow, request lifecycles, state machines, queue/worker topology, deployment layout, module boundaries, fan-out/fan-in, before/after system shapes. When in doubt, generate one. The only hard ceiling is MAX_TOTAL_IMAGES (10); the soft floor is "hero + every major section".
• Generate at most one image per section header (no duplicates within a section). Cap total images at MAX_TOTAL_IMAGES (10) or fewer.
• Each image is a picture, not a document: emphasize architecture, nodes, components, communication/data flow, state transitions — the structure and meaning. No more than MAX_TEXT_LABELS_PER_IMAGE (10) text labels per image; list the exact labels in the prompt and state they are the complete set. Fine-grained detail (field types, function signatures, code) belongs in freeform HTML, not in the generated picture.
• All images share one visual language: write a shared style brief once (palette hex codes matching the page's CSS tokens, background, line weight, node/arrow conventions, recurring-element color/shape mapping, full negation list) and prepend it verbatim to every prompt.
• Use the bundled generator at IMAGE_GENERATOR. Do not call, reference, or depend on any other image skill — this skill is fully self-contained.
• Generate every image in parallel — this is mandatory, not a suggestion. Each generate_image.py call takes many seconds (often 20–60s). Running N images sequentially costs N × that latency; running them in parallel costs ~1× that latency. There is no reason to wait for one image to finish before starting the next — the calls are independent. Fire them all at once as background bash jobs in a single shell (uv run "$GEN" ... & per image, then a single wait), or as multiple Bash tool calls in the same turn. Never generate them one after another. Sequential generation is the single biggest thing that makes this skill slow and is treated as a defect.
• Embed each image inline in its section with <figure><img src="htmlvspec-<PLAN_SLUG>/NN-section.png" alt="..."><figcaption>…</figcaption></figure> using a relative path (the .html file and its image folder travel together, both carrying the htmlvspec- prefix).

Freeform Instruction Set

The HTML Plan Template includes a Freeform zone (<section class="freeform">). Here — and anywhere else a visual would help more than prose — you have full creative latitude to author any HTML you want. Freeform is additive on top of the generated images; it uses inline HTML/SVG, not generated images. Lean into freeform — even with per-section images, the fine-grained implementation detail lives here.

• Communicate concrete implementation work. Freeform is not decoration — it is where another developer learns exactly what to build. The generated images convey the shape of the system; freeform conveys the specifics: file paths to touch, function signatures with full type info, data shapes (request/response/DB rows), the precise sequence of operations, decision points with the chosen branch, edge cases and what happens at each, error/timeout/retry behavior, ordering and concurrency constraints, before/after diffs, migration steps, and any invariants the implementation must preserve. Always prefer specific over abstract — names, types, numbers, paths.
• Use a wide variety of HTML tags to convey meaning. Different ideas deserve different shapes. Reach for:
  • <details>/<summary> for expandable deep-dives, alternative-considered-and-rejected, and FAQ-style "why not X".
  • <table> for comparison matrices (option A vs B vs C), API contracts (field · type · required · description), decision matrices (criterion × option), and before/after columns.
  • <dl>/<dt>/<dd> for definitions, glossaries, and field-by-field schema docs.
  • Inline SVG for fine-grained diagrams that complement (not duplicate) the section's generated image — sequence diagrams, state machines, ER diagrams, decision trees, mini-timelines, callout overlays.
  • <pre><code> blocks (with a language hint) for code snippets, shell sessions, JSON/YAML payloads, SQL, and diffs. Use <samp> for expected output and <kbd> for keystrokes/commands.
  • <aside> (styled as a callout) for warnings, "gotchas", and side notes that would interrupt the main flow.
  • <mark> to highlight the critical word/line a reader must not miss.
  • Nested <ol> for ordered, branching procedures; nested <ul> for grouped checklists.
  • <figure> wrapping inline SVG with a <figcaption> so the diagram has a citable label.
  • Animated SVG / CSS transitions and tabbed views only where they genuinely make the plan faster to absorb.
• Don't duplicate the section image. If the generated <figure> already shows the architecture, the freeform SVG/table should drill deeper (e.g. the image shows services and arrows; freeform shows the wire format on each arrow).
• Self-contained only. Inline all CSS and JS. Do not pull external scripts/styles/fonts over the network unless truly necessary; if you must, declare it under Notes.
• Stay on-theme. Reuse the template's CSS custom properties (--bg, --cyan, --amber, --red, --line, etc.) so freeform content matches the rest of the page and the generated images. SVG strokes/fills should use the same palette as both.
• Don't break the core plan. The standard sections must remain present and complete; freeform is additive enrichment, not a replacement.
• Earn its place. No decorative filler — every freeform element should make the spec clearer or faster to act on. If an SVG diagram or table would not change what the developer types next, don't include it.