Plan HTML Review App Design

Key Decisions

Generation Pipeline

flowchart LR
    md["docs/superpowers/specs/*.md"] --> script["generate-plan-html.ts"]
    script --> prompt["composePrompt()"]
    prompt --> cli["Agentic CLI\nclaude | codex | gemini"]
    cli --> |"writes JSON + HTML"| tmp["mkdtemp staging dir"]
    tmp --> |"Zod validate"| validate{valid?}
    validate --> |"yes — rename()"| content["src/content/specs/\n slug.json + slug.html"]
    validate --> |"no — rm staging"| fail["report error\nno files promoted"]
    content --> astro["Astro build"]
    astro --> pages["Cloudflare Pages\nsuper-app-plans"]
    

Non-Goals

• Do not move canonical spec content out of docs/superpowers/specs.
• Do not auto-convert specs during astro dev / astro build.
• Do not use MDX as the generated review format.
• Do not build a CMS or editing interface.
• Do not require AI-generated images for every spec.
• Do not produce HTML deterministically — enrichment is delegated to the LLM (ADR-0026).

Astro App Shape

Content storage

Astro Content Collection at src/content/specs/. Each spec → <slug>.json + <slug>.html. Schema shared with generator via Zod.

Archive page (/)

Specs newest-first, status badges, tag filters, client-side MiniSearch search bar.

Detail page (/specs/<slug>)

Astro layout provides hero, sticky TOC (extracted from <h2>/<h3>), footer. Body is <Fragment set:html={bodyHtml} />.

Search engine

MiniSearch over public/search-index.json. Field-weighted: title ×5, key_decisions ×3, tags ×3, summary ×2, search_text ×1.

Index rebuild triggers

End of every generate run + astro:build:done integration hook (same buildSearchIndex() function).

CSS

Independent of apps/platform. Own design tokens, Tailwind v4. Light-mode only in v1. No dark mode.

Deployment

Cloudflare Pages · super-app-plans. Static build, no SSR adapter, no auth. noindex + /robots.txt Disallow.

Script & CLI Flags

Path: frontend/astro/apps/plans/scripts/generate-plan-html.ts (TypeScript via tsx)

Variant System

Variants let you keep multiple CLI outputs for the same spec side-by-side without collision.

Canonical slot

<slug>.json + <slug>.html — drives the archive, search index, and detail page hero.

Variant slot

<slug>.v.<name>.json/html — shown in collapsible <details> sections below the canonical on the detail page.

Archive / search

Canonical only. Variants are excluded from the index.

Usage

pnpm generate <path> --with=codex --variant=codex to generate a codex variant alongside the claude canonical.

Output Schema

One Zod schema (src/lib/spec-schema.ts) is shared by the generator script, the Astro content collection, and the prompt's auto-rendered TypeScript type.

Content Preservation Rule

• Long prose may be compressed when meaning is preserved.
• Detailed information may move lower or into <details> blocks, but must not disappear.
• Every generated page links back to the source markdown via a main-branch GitHub URL.
• The source markdown remains the place to audit exact wording.

Diagrams & Images

Component Catalog (v1 — 20+ classes)

Defined in apps/plans/COMPONENT_CATALOG.md. Enforced by a post-generation lint step in the script. The suggestion loop grows the catalog based on real content needs.

Prompt Template

Path

frontend/astro/apps/plans/prompts/generate-plan.md

Format

Plain markdown with {{VAR}} substitution. One template for all CLIs.

Key variables

SPEC_PATH, OUTPUT_JSON_PATH, OUTPUT_HTML_PATH, SOURCE_MARKDOWN, COMPONENT_CATALOG, JSON_SCHEMA, DIAGRAM_MODE, IMAGES_ENABLED

JSON_SCHEMA

Auto-rendered from Zod via renderAgentSchemaAsTypeScript() — schema and prompt stay in sync automatically.

Evolution

Material changes are commits with rationale. After any change, regenerate ≥1 representative spec with --force and PR-review the diff before claiming it works.

Repo-local Skill

Path

.agents/skills/plan-html/SKILL.md, registered in .claude/skills.yaml

Trigger

"generate plan HTML", "render this spec", "regenerate spec pages", "publish plan"

Behavior

Prompt-then-run: ask before invoking the script. Default command: pnpm --filter @astro/plans generate <spec-path>. Use --all for multiple specs. Use --all --force after prompt/catalog/CSS changes.

Post-run

Surface suggested_components to the human. Spot-check the generated page at desktop + mobile widths.

Testing & Verification

• Script run against the full docs/superpowers/specs corpus — Zod validation passes for every <slug>.json.
• Generated HTML inspected for: title, summary, source link, navigation, all important sections (per content preservation rule).
• Search index contains every canonical spec; client search finds at least one result per spec via title and via a key decision.
• pnpm --filter @astro/plans build succeeds; astro:build:done hook regenerates search-index.json.
• Browser review at desktop and mobile widths.
• --with=codex --diagrams=image produces a diagram image with non-empty alt text and an <img> reference in the HTML.
• Variant system: --variant=codex produces a .v.codex.json/html pair; detail page shows it in a collapsible section below canonical.

Locked Implementation Decisions