Htmlspec

htmlspec

Purpose

Produce an engineering implementation plan as one self-contained, text-only HTML page — specs/<plan-name>.html — that you can open directly in a browser. Unlike a markdown spec, the plan is authored directly in HTML using the template below, and a dedicated Freeform zone 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. No images are generated — all visual enrichment comes from inline HTML, CSS, SVG, and JS authored directly into the page.

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. 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/htmlspec-<PLAN_SLUG>.html — the filename MUST always begin with the htmlspec- prefix

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/htmlspec-<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 reads as one body of work.
• Do not include any <figure>/<img> elements — this skill is text-only.

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. This is the most valuable part of the page: with no image generation, freeform is where the plan earns its richness, so lean into it heavily.

• Communicate concrete implementation work. Freeform is not decoration — it is where another developer learns exactly what to build. Encode the things prose makes muddy: 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 architecture diagrams, data flow, state machines, sequence diagrams, dependency graphs, decision trees, timelines, ER diagrams, and topology maps. SVG is your image substitute — use it liberally.
  • <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.
• 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. SVG strokes/fills should use the same palette.
• 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.