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. ## Workflow ### Phase 1 — Plan 1. THINK HARD: parse the USER_PROMPT; settle task type, complexity, and the architecture. 2. Explore the codebase for patterns and relevant files. 3. Decide the section set and the PLAN_SLUG. ### Phase 2 — Author the HTML 4. Create `specs/` if missing. Write `specs/htmlspec-<PLAN_SLUG>.html` from the **HTML Plan Template**, filling every applicable section with detailed content. Emit no `<figure>`/`<img>` elements — this skill is text-only. ### Phase 3 — Freeform enrichment 5. Author the **Freeform** section and any in-section enrichments per the **Freeform Instruction Set** above — inline SVG/CSS/JS, self-contained, on-theme, additive. ### Phase 4 — Finish 6. Validate the HTML is well-formed (see Validation). 7. Follow the **Report Format**. ## HTML Plan Template Author the page from this skeleton. Keep the `<head>`/`<style>` block intact (it defines the shared theme); fill the `{{…}}` slots; drop the conditional sections that don't apply. ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Plan: {{TASK_NAME}}</title> <style> :root{ --bg:#0A0E1A; --panel:#111726; --ink:#F5F5F0; --muted:#9AA4B2; --cyan:#22D3EE; --amber:#F59E0B; --red:#EF4444; --line:#1E2A3C; } *{box-sizing:border-box} body{margin:0;background:var(--bg);color:var(--ink); font:16px/1.65 -apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif} .wrap{max-width:980px;margin:0 auto;padding:48px 24px 96px} header.hero{text-align:center;margin-bottom:36px} header.hero h1{font-size:2.2rem;margin:0 0 10px;letter-spacing:-.02em} .meta{color:var(--muted);font-size:.9rem} .badge{display:inline-block;background:var(--cyan);color:#001018;border-radius:999px; padding:2px 11px;font-size:.72rem;font-weight:700;text-transform:uppercase;letter-spacing:.04em} section{background:var(--panel);border:1px solid var(--line);border-radius:14px; padding:24px 28px;margin:20px 0} section>h2{margin:0 0 14px;color:var(--cyan);font-size:1.3rem; border-bottom:1px solid var(--line);padding-bottom:10px} ul,ol{padding-left:22px} li{margin:4px 0} table{width:100%;border-collapse:collapse;margin:12px 0} th,td{border:1px solid var(--line);padding:8px 12px;text-align:left;vertical-align:top} th{background:#0d1422;color:var(--cyan)} pre{background:#0d1422;border:1px solid var(--line);border-radius:8px;padding:14px;overflow:auto} code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.86em} :not(pre)>code{background:#0d1422;border:1px solid var(--line);border-radius:6px; padding:2px 6px;color:var(--amber)} .freeform{border-style:dashed;border-color:var(--cyan)} .freeform>h2::after{content:" · author anything that helps";color:var(--muted); font-size:.7rem;font-weight:400;text-transform:none} a{color:var(--cyan)} </style> </head> <body> <div class="wrap"> <header class="hero"> <h1>Plan: {{TASK_NAME}}</h1> <p class="meta"><span class="badge">{{TASK_TYPE}}</span> &middot; {{COMPLEXITY}}</p> </header> <section> <h2>Task Description</h2> {{TASK_DESCRIPTION_HTML}} </section> <section> <h2>Objective</h2> {{OBJECTIVE_HTML}} </section> <!-- include if task_type is feature OR complexity is medium/complex --> <section> <h2>Problem Statement</h2> {{PROBLEM_STATEMENT_HTML}} </section> <section> <h2>Solution Approach</h2> {{SOLUTION_APPROACH_HTML}} </section> <!-- /conditional --> <section> <h2>Relevant Files</h2> {{RELEVANT_FILES_HTML}} <!-- include an h3 'New Files' list if needed --> </section> <!-- include if complexity is medium/complex --> <section> <h2>Implementation Phases</h2> {{PHASES_HTML}} <!-- Phase 1: Foundation / Phase 2: Core / Phase 3: Integration & Polish --> </section> <!-- /conditional --> <section> <h2>Step by Step Tasks</h2> {{STEPS_HTML}} <!-- ordered list; foundational first; last step validates the work --> </section> <!-- include if task_type is feature OR complexity is medium/complex --> <section> <h2>Testing Strategy</h2> {{TESTING_HTML}} </section> <!-- /conditional --> <section> <h2>Acceptance Criteria</h2> {{ACCEPTANCE_HTML}} <!-- specific, measurable --> </section> <section> <h2>Validation Commands</h2> <pre><code>{{VALIDATION_COMMANDS}}</code></pre> </section> <!-- FREEFORM ZONE: author ANY self-contained, on-theme HTML/CSS/SVG/JS that aids the plan --> <section class="freeform"> <h2>Freeform</h2> {{FREEFORM_HTML}} </section> <section> <h2>Notes</h2> {{NOTES_HTML}} <!-- dependencies (uv add ...), external assets used by freeform, caveats --> </section> </div> </body> </html> ``` ## Report Format ```markdown ✅ HTML Implementation Plan Created (text-only) File: specs/htmlspec-<PLAN_SLUG>.html (open in a browser) Topic: <brief description of what the plan covers> Freeform: <one line on what custom HTML you added, if any> Key Components: - <main component 1> - <main component 2> - <main component 3> Open with: open specs/htmlspec-<PLAN_SLUG>.html ``` ## Validation ```bash # file exists and is non-trivial HTML test -s specs/htmlspec-<PLAN_SLUG>.html && head -1 specs/htmlspec-<PLAN_SLUG>.html | grep -qi '<!DOCTYPE html>' && echo "HTML ok" # text-only: no <img> tags should be present ! grep -q '<img ' specs/htmlspec-<PLAN_SLUG>.html && echo "text-only ok" ```