htmlify

name	htmlify
description	Generate beautiful, pedagogical HTML companions for superpowers-gstack MD artifacts (design docs, handoffs, plans). Auto-opens via --open; generates per-directory dashboards. Triggered manually or via PostToolUse hook.

/htmlify

Lager visuelt elegante HTML-companions ved siden av MD-artefakter, og en aggregert dashboard-side per katalog. Designet for vibe-codere som ikke orker å lese verbose MD-output fra skills som /office-hours, /autoplan, /plan-eng-review, /context-handoff osv.

Når det aktiveres:

• Bruker sier "html-ify", "lag html av", "generer HTML companion"
• Bruker spør "kan jeg få en penere visning av denne MD-en"
• PostToolUse-hook (når installert) auto-trigger ved Write/Edit på artefakt-MD
• Invoked programmatically by /superpowers-gstack:swiftui-design-consultation for Phase 3 proposal preview and Phase 6 DESIGN.html generation

How to invoke

Skill-katalogen oppdages av Claude Code som "Base directory for this skill" ved invokering. Wrapper-binæren bin/htmlify self-lokaliserer og kan kjøres fra hvilken som helst cwd:

"$SKILL_DIR/bin/htmlify" <args>

Hvor $SKILL_DIR er katalogen denne SKILL.md filen ligger i. Eksempel når installert via Claude Code marketplace:

~/.claude/plugins/cache/paretofilm-plugins/superpowers-gstack/<version>/skills/htmlify/bin/htmlify <args>

Wrapper-en sjekker at bun og deps er installert; printer feilmelding (exit 5) hvis ikke.

First-run setup (one-time)

Deps må installeres én gang per installasjons-lokasjon. Wrapperen forteller deg den nøyaktige kommandoen hvis den feiler:

cd "$SKILL_DIR" && bun install

Etterpå er skill'en klar til bruk uansett antall invokeringer.

Usage

Render én MD til HTML companion

"$SKILL_DIR/bin/htmlify" <path-to-md>

Output: <dir>/.superpowers-html/<name>.html. Også en companion.css blir kopiert til samme katalog.

Med auto-open (macOS)

"$SKILL_DIR/bin/htmlify" <path-to-md> --open

Generer dashboard for en katalog

"$SKILL_DIR/bin/htmlify" dashboard <dir>

Output: <dir>/.superpowers-html/index.html med liste av alle artefakter i katalogen sortert by mtime desc.

Flags

• --plan <plan.json> — Last v2 rendering plan (rik layout: comparison-matrix, flowchart-svg, pullquote, callout-box, stats-bar, two-column, expandable, diff-card, feedback-panel). Uten flagget rendres v1-template.
• --open — Åpne resulterende HTML i Safari (macOS only) som distraksjonsfri leser. Alle eksisterende Safari-vinduer lukkes først så HTML-en er det eneste som vises. Brukerens default-nettleser røres ikke.
• --no-clobber — Skip render hvis HTML er nyere enn MD
• --force-rebuild — Tving render selv ved no-clobber

Enhanced rendering (v2 — plan-driven layout)

v1 gir "penere MD med strukturerte cards" — det er en god default. v2 gjør HTML-en til en informativ plansje med komponenter som comparison-matrix, flowchart-svg, pullquotes, stats-bar, callout-boxes, diff-cards og en interaktiv feedback-panel.

V2 fungerer via en rendering plan (JSON-fil) som du genererer i Claude Code-sesjonen (gratis under Max-plan; bruker IKKE Anthropic API) og sender til CLI med --plan.

Når bruke v2?

• MD-en er lang/tett og ville hatt nytte av visuell hierarki
• Det er en sammenligning, et flytdiagram, før/etter, eller en tidslinje skjult i prosaen
• Du vil ha en feedback-runde fra brukeren (sjekkbokser + radio + kommentar → clipboard JSON)

Hvordan generere en plan (i denne sesjonen)

1. Les MD-en med Read-tool.
2. Identifiser visuelle muligheter:
   • H2 med "Approaches Considered" / "Options" → comparison-matrix
   • H2 med arkitektur/pipeline/flyt → flowchart-svg
   • Memorable quote i teksten → pullquote med after_section
   • "Note:" / "Warning:" / "Insight:" → callout-box
   • Metrics, before/after counts → stats-bar
   • To kolonner som speiler hverandre → two-column
   • Lang side-info som ikke skal dominere → expandable
   • Kodeblokker som er "før/etter" → diff-card
3. Skriv plan-JSON til en temporary fil med strukturen under.
4. Kjør CLI: "$SKILL_DIR/bin/htmlify" <md> --plan <plan.json> --open
5. Sett alltid feedback_panel med relevante premises/approaches + tilpasset spørsmål. Bruker kan trykke "Copy feedback as prompt" og lime inn i neste sesjon.

Plan-JSON skjema

{
  "version": 1,
  "sections": [
    {
      "heading": "Approaches Considered",
      "treatment": "comparison-matrix",
      "data": {
        "items": [
          {"title": "Option A", "summary": "...", "pros": ["..."], "cons": ["..."], "effort": "1d", "risk": "low"},
          {"title": "Option B", "pros": ["..."], "cons": ["..."], "highlighted": true}
        ]
      }
    },
    {
      "heading": "Architecture",
      "treatment": "flowchart-svg",
      "data": {
        "orientation": "LR",
        "nodes": [{"id": "a", "label": "Input"}, {"id": "b", "label": "Process", "emphasis": true}, {"id": "c", "label": "Output"}],
        "edges": [{"from": "a", "to": "b"}, {"from": "b", "to": "c", "label": "transform"}]
      }
    }
  ],
  "pullquotes": [
    {"text": "...", "attribution": "...", "after_section": "Problem Statement"}
  ],
  "feedback_panel": {
    "enabled": true,
    "premises": ["P1 label", "P2 label"],
    "approaches": ["A1 label", "A2 label"],
    "custom_questions": [
      {"id": "q1", "label": "Did this layout help?", "type": "radio", "options": ["yes", "no"]},
      {"id": "q2", "label": "Free notes", "type": "text"}
    ]
  }
}

Treatments-katalogen

Treatment	Når bruke	Data-form
section-card	Default — vanlig prosakort	(ingen — bruker MD-body)
comparison-matrix	2-5 alternativer side-ved-side	{items: [{title, summary?, pros?, cons?, effort?, risk?, highlighted?}]}
flowchart-svg	Pipelines, state machines, arkitektur	{nodes: [{id, label, shape?, emphasis?}], edges: [{from, to, label?}], orientation?: "TB"|"LR"}
pullquote	Memorable quote (kan også stå i pullquotes-array)	{text, attribution?}
callout-box	Note/warning/insight/danger	{level?: "info"|"warn"|"insight"|"danger", title?, body}
stats-bar	Tall, metrics, before/after counts	{items: [{label, value, delta?, trend?: "up"|"down"|"flat"}]}
two-column	Sammenligning innenfor ett tema	{left: {heading?, body}, right: {heading?, body}}
expandable	Lang side-info som skal kunne kollapses	{summary, body, open?}
diff-card	Før/etter kode eller tekst	{title?, before: {label?, content}, after: {label?, content}}

Viktige regler

• Bruk ALDRI API — plan-generering skjer i denne Claude Code-sesjonen (Max-plan compute = gratis)
• Headings må matche MD-en — case-/whitespace-insensitivt. Plan-seksjon uten matching H2 rendres som ny seksjon.
• treatment: "section-card" = ikke override; bruk default rendering
• feedback_panel har alltid et kommentar-felt — uavhengig av om premises/approaches/custom_questions er tomme
• Plan = optional — uten --plan får brukeren v1-rendering (samme som før)

Frontmatter types som støttes

• type: design-doc — fra /office-hours
• type: handoff — fra /context-handoff (eller filnavn handoff.md for legacy)
• type: plan — fra /autoplan
• Manglende eller ukjent frontmatter → generic fallback med banner

Exit codes

• 0 — success
• 1 — usage error (bad CLI args)
• 2 — schema validation failure
• 3 — MD parse error
• 4 — I/O error (file not found, not writable)
• 5 — setup error (deps not installed, bun missing)

Auto-trigger (PostToolUse hook)

For automatisk å fyre htmlify når en skill skriver en artefakt-MD, kjør installeren én gang. Path avhenger av om du jobber fra repo-rota eller fra plugin-installasjonen:

Fra repo (utvikling):

./scripts/setup-htmlify-hook.sh

Fra plugin-installasjonen (marketplace):

~/.claude/plugins/cache/paretofilm-plugins/superpowers-gstack/<version>/scripts/setup-htmlify-hook.sh

Hook'en matcher:

• Filnavn handoff.md
• Mønstre: *-design-YYYYMMDD-HHMMSS.md, *-plan-YYYYMMDD-HHMMSS.md
• Alle MD-er under .gstack/projects/
• Loop-prevention: skip MD-er i .superpowers-html/

Hook-skriptet self-lokaliserer — det vil alltid kalle htmlify fra den katalogen den selv ligger i, så det er trygt å installere hooks fra plugin-cache-stien.

Development

Kun relevant hvis du jobber fra repo-rota i ~/Developer/superpowers-gstack/:

cd skills/htmlify
bun install    # first run
bun test       # 138 tests (v2)

Artefakter brukt under utvikling: se design-doc og test-plan i ~/.gstack/projects/Paretofilm-superpowers-gstack/.