Turn a tech-spec directory into an interactive, marketing-grade web presentation — built so engineers understand the design, the reader is convinced of the why, and the result is shareable in public. Use when someone wants a spec turned into a deck.

Presentation Turn a technical specification into an interactive, persuasive web deck — the kind at iii.dev/roadmap/. The output is a content layer inside the repo's roadmap base (the shared component library, gallery, and markdown spec viewer that build every deck into one static site — Astro routes of the site package in iii, a standalone Vite project in other repos): 1. helps engineers understand the spec — the architecture is a navigable map, not prose; 2. is interactive — steppable diagrams, a selectable system map, live toggles; interactivity is what makes it stick; 3. reads like marketing — it argues the why . if no one is convinced the work should happen, the spec has not done its job; 4. is build in public ready — each deck ships as a static page at /roadmap/<slug / , safe to share. Comparable to A product launch microsite generated from an RFC. Stripe doc clarity meets a keynote narrative, in a monospace drafting sheet style. Activation Use For generating an interactive deck from a tech spec directory refreshing or extending a presentation already generated by this skill Do Not Use For writing the spec itself — use /tech spec static slide exports (pdf / keynote) — use a slide tool general UI work unrelated to a spec — use /design Load First Read these before building (they are the law — do not re derive them): reference/design system.md — the locked tokens, type, motion, layout reference/archetypes.md — the interactive slide library + how to pick one reference/component standards.md — deck local vs promoted components, the promotion checklist, the registry format reference/narrative framework.md — the persuasive arc + outline rules reference/quality bar.md — the checklist to self verify before finishing reference/hosting.md — the two tree layout, the pairing contract, frontmatter registration, and deploy per repo: <base /COMPONENTS.md — the live registry of that repo's shared components. It may exceed the bundled catalog; when it and reference/archetypes.md disagree, the repo registry wins . The skill bundles two scaffolds: template/ — one deck's content layer (App, sections, pages, content data, the spec docs glob). Copy it per spec; everything visual comes from the base's shared src/ via the @lib alias. You generate only content. base/ — the whole per repo presentations site: the shared component library + design tokens, the gallery, the md only spec viewer, and the build glue ( build.mjs , vite.config.ts , one package.json ). Copy once per repo (in iii it already lives at website/roadmap/ ); per deck runs never modify it except additive component promotion per reference/component standards.md . Progress Updates Emit one short line before each phase: ingesting spec → reading the component registry → proposing outline → scaffolding → generating slides (k/N) → registering spec frontmatter → verifying . Workflow Phases are gated. Do not skip Phase 2's approval or Phase 5's verification. 0. Resolve inputs The argument is a tech spec directory: <repo /tech specs/<slug / — markdown only (README.md + domain docs; frontmatter in README.md). If given a path elsewhere, resolve into the spec tree or ask. The slug is the spec directory's basename (e.g. 2026 06 21 devexp — YYYY MM DD <name ; the day prefix orders the roadmap timeline). It is the deck directory name AND the URL segment — the pairing contract in reference/hosting.md . Fix it now and use it everywhere; never prettify it. Resolve the base project : read <repo /tech specs/README.md — the pointer names the base dir (in iii: website/roadmap/ ). Fallback: search for a dir containing both COMPONENTS.md and a shared src/ . Detect its shape: integrated base (shared src/ + scripts/manifest.mjs , no package.json or build.mjs of its own — iii's shape: the site's Astro pages at website/src/pages/roadmap/ render each deck's src/App.tsx as a React island via the base's src/DeckHost.tsx ; deps live in the iii website package) → use it, and scaffold content layers only; standalone base ( build.mjs + own package.json , one index.html per deck — the base/ snapshot's shape) → use it; absent → first run in this repo: pick the location with the user (default website/roadmap/ when website/ exists, else roadmap/ at the repo root) and scaffold it in Phase 3; legacy layout ( tech specs/build.mjs + gallery/ — per deck standalone projects) → stop and offer the port procedure in reference/hosting.md before generating anything new. Output location is <base /<slug / . If it exists and is non empty, ask: overwrite, update in place, or abort. Never write a non markdown file under tech specs/ . Detect the install mode: workspace (repo pnpm workspace.yaml lists the base) vs standalone ( pnpm install ignore workspace inside the base). 1. Deep ingest (read, do not skim) Read the spec README.md in full first: thesis, architecture, principles, cross cutting contracts, migration overview. Note whether it already has a frontmatter block (title/tagline/date/tags/status). Read every domain doc. For each, capture: the one load bearing phrase, the pain it removes, the mechanism, any schema/fields, any sequence/lifecycle, any numbers, any honest trade off. Build a content inventory (architecture, protocol/wire contract, lifecycle, state model, config schema, security, migration, …). This is the raw material for archetype matching. 1b. Component awareness (before planning). Read <base /COMPONENTS.md end to end and list <base /src/components/{schematic,diagrams}/ + src/hooks/ . The registry is the live catalog for this repo and supersedes the bundled reference/archetypes.md where they disagree. Reuse first mandate: a slide may get a bespoke visual only after the catalog demonstrably has no fit for its content shape. Name any planned new component in the Phase 2 outline, marked local or promote (see reference/component standards.md ), so the user approves it at the same gate. 2. Narrative plan — THE GATE Apply the arc in reference/narrative framework.md . Produce a deck outline: an ordered slide list, each with { title, archetype (or reused registry component), the single claim, source section(s), the concrete data it pulls, interactivity, new component: <Name (local promote) — only when nothing fits } . Include candidate deep dive pages. Derive the hero line + three value subhead + stat strip. Choose the wordmark label. Present the outline to the user for approval/edits before scaffolding. This is the cheapest place to turn a dry spec into a story. Skip only if the user explicitly says "just build it". 3. Scaffold (mechanical) The deck: mkdir p <base /<slug / and copy template/ into it — in an integrated base (iii) copy template/src/ only and skip index.html and src/main.tsx (the site's [slug]/index.astro route provides the document shell and mounts src/App.tsx ; the page title/description come from the spec frontmatter). Substitute the SPEC MD GLOB literal in src/spec docs.ts with the computed relative path from <base /<slug /src/ to <specs dir /<slug / .md (in iii: ../../../../tech specs/<slug / .md ); in a standalone base also TITLE / DESCRIPTION in index.html . No per deck install, no per deck config, no lockfile. Ensure deps once: workspace mode → pnpm install at the repo root (only if the base's deps are missing); standalone mode → pnpm install ignore workspace in <base (commit the generated lockfile). Registration: write or update the YAML frontmatter block at the top of tech specs/<slug /README.md (schema in reference/hosting.md ): title + tagline from the approved hero, date: YYYY MM DD (day precision — the roadmap timeline orders and labels by it), 0–4 tags, status: draft . There is no central manifest — the build aggregates every spec's frontmatter, so this run touches nothing shared. If frontmatter already exists, update only the fields this run owns (tagline polish, status). The base project (first run in a repo only): copy base/ into the chosen dir (never its node modules / dist ). Fill the identity once: REPO in package.json ; the GALLERY / WORDMARK LABEL / HERO / ATTRIBUTION / SITE HOST tokens in index.html , src/gallery/site.ts , and README.md ; write the tech specs/README.md pointer. The gallery page is a roadmap : hero copy in roadmap voice ( HERO TITLE ≈ "what we're working on"; HERO LEAD hints at the current priority and what already landed, without naming specs), and the spec list renders as a one column timeline, newest first, grouped by month. In a workspace repo, add the base to pnpm workspace.yaml with user confirmation (a repo level file). Never touch build.mjs , vite.config.ts , tsconfigs, or src/ beyond this copy. 4. Generate the content layer Edit only these — the write surface is <base /<slug / plus the spec's frontmatter block (and an approved promotion): src/content/deck.ts — DECK META.wordmarkLabel , NAV , FOOTER . src/content/<topic .ts — the typed data arrays each archetype consumes (map nodes/edges/info, sequence lanes/steps, reveal stages, cli tracks, metrics, rows). Keep data here, out of components. src/sections/<Name .tsx — one thin section per slide: import the matching archetype from @lib , feed it data, wrap it in <Section . Replace the example sections; delete src/content/example.ts and pages/ExamplePage.tsx . src/pages/<Name .tsx — deep dives via @lib <PageShell . src/App.tsx — wire the ordered SECTIONS array and the PAGES map. The component protocol (when a load bearing concept has no fit in COMPONENTS.md ): 1. Default: build it deck local in <base /<slug /src/diagrams/<Name .tsx , following @lib/components/diagrams/SequencePlayer.tsx conventions. 2. Promote into <base /src/components/ only when all three hold: (a) it is generic over its data — nothing spec specific inside, everything arrives via typed props; (b) it maps to a recurring spec shape (a lifecycle, a tree, a timeline, a fan out…) future decks will plausibly need; (c) it passes the checklist in reference/component standards.md without deck specific hacks. 3. A promotion = the component file plus its COMPONENTS.md entry in the same change . An unregistered shared component is a defect (the base's registry check warns — scripts/validate roadmap.ts in iii, build.mjs standalone; strict mode makes it fatal). 4. Never fork a shared component into the deck to tweak it — extend it via additive, non breaking props, or build a genuinely different deck local one. Modifying an existing shared component requires explicit user approval (it re renders every other deck). Built in spec viewer — do not delete. Every deck ships the /spec page: the template wires spec docs.ts (the compile time glob over the paired spec's markdown) into @lib/pages/SpecPage via PAGES.spec , and the shared TopNav renders the spec link. The shared markdown renderer strips the frontmatter block. It needs no per deck content — leave the wiring in place. 5. Verify — THE SECOND GATE All commands run from <base 's package (iii: pnpm filter iii website <script from the repo root; standalone: inside <base ): pnpm type check — the whole roadmap project (shared src + gallery + every deck) must pass strict; fix every error. The build must succeed with zero frontmatter validation or registry parity warnings — iii: pnpm build (the site build runs the roadmap contract checks and emits dist/roadmap/<slug / ); standalone: node build.mjs only=<slug . pnpm dev