presentation

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` in the background, then dogfood with the **`/browse` skill** (never `mcp__claude-in-chrome__*`): load `http://localhost:4321/roadmap/<slug>/` (standalone: `:5173/<slug>/`), click the map, run a stepper, toggle the theme, open a deep-dive, open `#/spec` and confirm every markdown file renders (mermaid fences live, no raw frontmatter). Zero console errors; no horizontal body scroll at 375px. - `pnpm build && pnpm preview`, then `/browse http://localhost:4321/roadmap/` (standalone: `:4173/`): the spec appears on the roadmap timeline in date order under its month, its card shows the frontmatter title/tagline/tags with the day marker in the timeline gutter, and clicking it lands on `/roadmap/<slug>/`. If the spec previously served the md-only viewer, confirm the deck replaced it at the same URL. - **If anything under `<base>/src/` was touched (a promotion): run the full site build** — a shared change must not break sibling decks. - Run `reference/quality-bar.md` end to end; fix anything red. ### 6. Hand off Report: the deck path (`<base>/<slug>/`), the dev URL, the slide list, which interactions are live, the frontmatter written, and any promoted components (with their registry entries). Offer to flip `status: draft` → `live`. Deploy is not a step: **in iii, merging to main ships everything via `.github/workflows/deploy-website.yml` to `iii.dev/roadmap/<slug>/`**; in other repos `dist/` is a portable static site for whatever CI they use. Do **not** commit, push, or configure hosting unless asked. Never run `vercel`. ## Rules - **The shared layer is law**: never edit `<base>/src/**`, the base's build glue (iii: `website/src/pages/roadmap/` and `scripts/validate-roadmap.ts`; standalone: `build.mjs` and `vite.config.ts`), tsconfigs, `package.json`, or the gallery in a deck run. Sole exception: additive component promotion under `reference/component-standards.md`, always paired with a `COMPONENTS.md` entry. - A deck run's write surface is `<base>/<slug>/**` plus the frontmatter block of `tech-specs/<slug>/README.md`. Nothing else. - `tech-specs/` holds markdown only. Never write a non-md file there; never create a `presentation/` directory inside it. - Reuse first: consult `COMPONENTS.md` before building any visual; the repo registry outranks the bundled catalog. - Slug = the spec directory basename, used identically as the deck dir and the URL. Never prettify it. `slug` is never a frontmatter field. - One claim per slide. Put depth behind a `<SpecSheet>` (`<details>`), closed by default — execs skim, engineers drill. - Ration the accent (success / active / CTA only). Lowercase copy; identifiers keep their casing. No em-dashes. No "robust / comprehensive / crucial / seamless / unlock". - Ground every claim in the spec. Keep one honest trade-offs/open-questions beat — honesty reads as credibility. - Quantify the win: use the spec's numbers verbatim; if you compute one, say so. ## Decisions Ask the user: the narrative outline (Phase 2, always); output location when occupied; audience tilt (execs vs engineers; default balanced); fonts offline vs CDN (default CDN); scope cap when a spec has many domain docs; first-run base location + gallery identity + the `pnpm-workspace.yaml` edit; any **modification** to an existing shared component; flipping `status` to `live`. Decide yourself: which archetype each slide uses; slide order within the arc; hero line and stats; SVG coordinates and step counts; what goes behind a `<details>`; copy voice; the frontmatter field values; deck-local vs promote per the component protocol (announce promotions in the outline and hand-off — don't ask). Everything under `<base>/src/` and the build glue is settled — never re-litigate it in a deck run. ## Verify `pnpm type-check` and the roadmap build (iii: `pnpm --filter iii-website build`; standalone: `node build.mjs --only=<slug>`) are green with zero registry/frontmatter warnings; `/browse` shows zero console errors, working interactions, and a frontmatter-free `#/spec`; the roadmap timeline lists the spec in date order, its card rendered from the frontmatter; `reference/quality-bar.md` passes; a promotion ran the full build (`reference/hosting.md` has the layout this all serves).