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.

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

✅ 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

# 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"