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).