@diottodev/runic 1.0.0 → 1.1.0

package/content/markdown-html-orchestrator/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: markdown-html-orchestrator
+description: Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks. Triggers on "convert this markdown to HTML", "make this an HTML file", "turn this into an interactive document", "render this report as HTML", "PR writeup as HTML", "slides from this markdown". Forks context to route to one of three converter sub-skills (md-document, md-review, md-slides) based on a deterministic doctype classifier, after the user has run the design-system onboarding once. Refuses if input is under 100 lines (per Shihipar — markdown still wins below the threshold) or design-system isn't onboarded. Distinct from Anthropic's official Playground plugin (which is interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from marketing/landing/ (which is a landing-page generator).
+context: fork
+version: 2.10.0
+author: Alireza Rezvani
+license: MIT
+tags: [markdown, html, converter, orchestrator, documentation, code-review, slides, design-system]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# Markdown → HTML — Domain Orchestrator
+
+Thariq Shihipar's argument (Claude Code HTML output essay, Medium 2026): **markdown collapses past 100 lines for agent-generated artifacts.** Long specs, code reviews, and architecture explainers lose density, hierarchy, and lightweight interaction the moment they exceed a screen of text. HTML restores all three — single-file, browser-native, shareable.
+
+This orchestrator forks context, classifies the input markdown deterministically, routes to the right converter sub-skill, and returns a digest with the output path. Heavy intake (full markdown bodies, diffs, slide decks) stays in the forked context.
+
+**Foundation status (v2.10.0):** orchestrator + `design-system` (onboarding + shared brand tokens) are live. Converter sub-skills (`md-document`, `md-review`, `md-slides`) land in v2.10.1 follow-up PRs. Until they land, this skill still runs the classifier and the design-system gate, and surfaces the routing recommendation — it just hands the rendering work back to Claude with the structured brief.
+
+## When to invoke
+
+| Symptom | Sub-skill |
+|---|---|
+| "Convert this RFC / spec / report / explainer to HTML" — long-form doc | `md-document` |
+| "Turn this PR writeup / code review into HTML" — markdown with diff blocks | `md-review` |
+| "Make a slide deck from this markdown" — `---` boundaries or H1 cadence | `md-slides` |
+
+## Pre-flight gates (hard refusals)
+
+1. **Below the 100-line threshold.** Markdown wins below 100 lines (Shihipar). The classifier prints `below_min_lines: true` and `route_explainer.py` refuses. Tell the user to keep their input as markdown.
+2. **Design-system not onboarded.** If `~/.config/markdown-html/design-system.json` doesn't exist (or its `setup_completed_at` is null), refuse. Point the user at `python3 markdown-html/skills/design-system/scripts/onboard.py` (or `--defaults` for a zero-touch run).
+3. **Unwritable save location.** `output_path_resolver.py` refuses if the configured `default_output_dir` (or `--out` override) isn't writable.
+
+## Routing logic (deterministic)
+
+Two-signal threshold pattern lifted from `research-ops/skills/research-ops-skills/SKILL.md`. Filename hint = 2 points; each content signal = 1 point. Silent-route allowed when winner ≥ 3 AND (runner-up = 0 OR winner ≥ 2× runner-up). Below threshold → one clarifying question with a recommended answer.
+
+### Signal table
+
+| Signal class | Filename hints | Content signals | Sub-skill |
+|---|---|---|---|
+| DOCUMENT | `report.md`, `*-doc.md`, `spec.md`, `rfc-*.md`, `*-analysis.md`, `*-explainer.md` | `## Table of Contents` (2), `^# `, `^## `, markdown table rows, `> [!NOTE]/[!TIP]/[!IMPORTANT]` callouts | `md-document` |
+| REVIEW | `review.md`, `*-pr-*.md`, `*.diff.md`, `code-review*.md` | ` ```diff ` (2), `^[-+]{3} ` (2), `^@@` (2), `> [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT]` (2), `LGTM`/`nit:`/`blocker:` | `md-review` |
+| SLIDES | `deck.md`, `slides.md`, `*-talk.md`, `presentation*.md` | `^---$` ≥ 3 (2 + per-boundary), `<!-- notes:` (2), H1 count ≥ 5 with median gap ≤ 12 lines (2) | `md-slides` |
+
+The pipeline:
+
+```bash
+python3 skills/markdown-html-orchestrator/scripts/doctype_classifier.py \
+    --input <path>.md --output json \
+  | python3 skills/markdown-html-orchestrator/scripts/route_explainer.py
+```
+
+`route_explainer.py` checks the design-system status, applies the < 100-line refusal, and prints one of: `ROUTE_SILENTLY -> md-<type>`, `ASK_USER one question: ...`, or `REFUSE — fix the issues above`.
+
+## Workflow
+
+### Step 1 — Confirm onboarding
+
+If the user has never run onboarding, surface the one-time setup:
+
+```bash
+python3 markdown-html/skills/design-system/scripts/onboard.py
+```
+
+Ten questions, 1-2 minutes. Captures brand primary + accent + heading/body Google Fonts + design style (editorial/technical/minimal/playful) + default output dir + syntax theme + TOC behavior + optional logo/company. Stored at `~/.config/markdown-html/design-system.json`. Re-runnable with `--scope project` for per-repo overrides.
+
+### Step 2 — Classify the input
+
+Run `doctype_classifier.py` on the markdown. Inspect the verdict.
+
+### Step 3 — Route or ask
+
+Pipe the classification into `route_explainer.py`. If it says `ROUTE_SILENTLY`, forward the original markdown + the design-system config into the named sub-skill's renderer in the forked context. If it says `ASK_USER`, ask ONE question with the recommended answer.
+
+### Step 4 — Resolve the output path
+
+```bash
+python3 skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
+    --input <path>.md --doctype <document|review|slides>
+```
+
+Collision handling defaults to `-2 / -3 / ...` suffix; `--on-collision timestamp` for stamped names.
+
+### Step 5 — Hand off to the sub-skill (when shipped)
+
+In v2.10.1+, the converter sub-skill's renderer takes the input markdown, the design-system config, and the resolved output path, and writes a single self-contained HTML file. The orchestrator returns a ≤ 100-word digest: input lines, output path, design style applied, top 3 features used (TOC, search, code-copy, etc.), and one forcing question for the user.
+
+Until v2.10.1, the orchestrator's job stops at step 4 — it returns the classification + routing brief and lets Claude do the rendering inline with the design-system tokens.
+
+## Forcing-question library (Matt Pocock grill-with-docs pattern)
+
+Walk these one at a time, with a recommended answer per question, citing the canon. Lift this list into `/cs:grill-markdown-html` for plan-stage interrogation.
+
+1. **What decision does this HTML drive — is the reader skimming, deciding, or presenting?**
+   Recommended: name it first; density follows from purpose. Canon: Shihipar — "match output format to consumption context"; Tufte — *Visual Display of Quantitative Information*, ch. 1.
+2. **Is the input markdown ≥ 100 lines?**
+   Recommended: yes — below that, keep it as markdown. Canon: Shihipar — markdown still wins under 100 lines.
+3. **Is the design-system onboarded?**
+   Recommended: yes, globally (`~/.config/markdown-html/design-system.json`). Canon: research-ops onboarding pattern (`research-ops/CLAUDE.md` §8); WCAG 2.2 §1.4.3 (text contrast 4.5:1).
+4. **Where does the output save, and will it overwrite anything?**
+   Recommended: the configured `default_output_dir` with `--on-collision suffix`. Canon: Matt Pocock `handoff` skill — never silently overwrite a working artifact.
+5. **Document type confidence — silent-route or one question?**
+   Recommended: silent-route only when the classifier's verdict is one of `document/review/slides` AND `silent_route_allowed: true`. Otherwise ask. Canon: research-ops two-signal threshold (`research-ops/skills/research-ops-skills/SKILL.md` §"Routing logic").
+
+Never run a sub-skill before the lane is locked.
+
+## Assumptions
+
+1. User has a markdown file ≥ 100 lines they want to convert.
+2. User has run onboarding once (`~/.config/markdown-html/design-system.json` exists with `setup_completed_at` populated).
+3. Single-file HTML output is acceptable (no multi-file site, no embedded server, no build step).
+4. Externals limited to Google Fonts CSS + Prism.js CDN (jsdelivr / cdnjs).
+
+## Non-goals
+
+- Not a landing-page generator (use `marketing/landing/`).
+- Not an interactive prompt-tuning playground (use Anthropic's official `playground` plugin).
+- Not a static-site generator (no multi-file output, no site index).
+- Not a PDF generator (slides use `@media print`; user prints from browser).
+- Not a watch / live-reload pipeline (conversion is one-shot).
+
+## Distinct from
+
+- **Anthropic Playground plugin** (`/playground`) — builds interactive controls (sliders, knobs, drag-drop) for prompt tuning, with a copy-prompt-back loop. This plugin converts existing markdown documents to HTML. Different tools for different jobs.
+- **`marketing/landing/`** — generates landing pages from scratch (Phase-0 intake → 3 sections → branded TSX/HTML). This plugin converts an existing markdown file you already have.
+- **`engineering/handoff/` + `productivity/handoff/`** — preserve session continuity between Claude conversations. Different artifact type (handoff brief vs. document conversion).
+
+## Output artifacts
+
+| Sub-skill | Artifact | Status |
+|---|---|---|
+| `md-document` | `doc-<slug>.html` (single file, sticky TOC, collapsibles, search, code-copy, scrollspy) | v2.10.1 |
+| `md-review` | `review-<slug>.html` (2-col diff + severity margin notes + jump-nav) | v2.10.1 |
+| `md-slides` | `deck-<slug>.html` (arrow-key nav + presenter mode + print-to-PDF) | v2.10.1 |
+
+## Anti-patterns (do not)
+
+- ❌ Convert markdown < 100 lines — markdown still wins. Refuse and tell the user.
+- ❌ Run the orchestrator before the design-system is onboarded. The output looks broken without tokens.
+- ❌ Silently chain two sub-skills (e.g., "convert doc AND make slides from it"). Pick one, finish, ask before chaining.
+- ❌ Use external JS frameworks (React/Vue/Svelte). Vanilla JS + IntersectionObserver only. Prism.js CDN is the single exception.
+- ❌ Multi-file output (extracted CSS, asset directories). Single file or nothing — that's the whole point.
+- ❌ Overwrite an existing output file by default. The path resolver suffixes `-2`, `-3`, …; `--on-collision overwrite` is opt-in only.
+
+## References
+
+- Spec: Thariq Shihipar — "Claude Code HTML output" (Medium, 2026)
+- Forking pattern: `research-ops/skills/research-ops-skills/SKILL.md` (`context: fork`, two-signal routing)
+- Customization pattern: `research-ops/skills/clinical-research/scripts/` (`onboard.py`, `config_loader.py`)
+- Brand palette math: `marketing/landing/skills/landing/scripts/brand_palette_validator.py` (WCAG + HSL derive)
+- Information-density canon: Tufte; Shihipar's `thariqs.github.io/html-effectiveness/` gallery; Wattenberger interactive essays; Maggie Appleton digital gardens

package/content/md-document/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: md-document
+description: Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens. Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs:md-document. Reads the design-system config via config_loader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file output — Google Fonts + Prism.js CDN are the only externals; no framework runtime, no build step. Use after orchestrator routing or after design-system onboarding is confirmed.
+version: 2.10.1
+author: Alireza Rezvani
+license: MIT
+tags: [markdown, html, documentation, single-file, toc, scrollspy, search, code-copy, design-system]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# md-document — Long-form Markdown to HTML
+
+The general-purpose converter — handles the 90% case Shihipar describes (specs, plans, RFCs, reports, explainers). Three stdlib tools pipeline together:
+
+```
+markdown_parser.py  →  html_renderer.py  →  interactivity_injector.py
+   (md → JSON AST)    (AST + tokens → HTML)    (HTML + JS behavior)
+```
+
+Output is one `.html` file with sticky TOC, search filter, scrollspy, code-copy buttons, and the user's 12 derived brand tokens. Externals limited to Google Fonts CSS + Prism.js CDN.
+
+## When to invoke
+
+| Symptom | Action |
+|---|---|
+| `markdown-html-orchestrator` routes input as DOCUMENT | Invoke this skill |
+| User runs `/cs:md-document <path>.md` directly | Invoke this skill |
+| User says "convert this spec/report/RFC/plan to HTML" | Invoke this skill |
+| Input is a code review (has ` ```diff ` blocks) | Route to `md-review` instead |
+| Input is a slide deck (clear `---` boundaries) | Route to `md-slides` instead |
+| Input is < 100 lines | Refuse (Shihipar threshold — markdown still wins) |
+| Design-system not onboarded | Refuse, surface `/cs:design-system` |
+
+## Pipeline
+
+```bash
+# 1. Parse markdown → JSON AST
+python3 markdown-html/skills/md-document/scripts/markdown_parser.py \
+    --input <path>.md --output sections.json
+
+# 2. Render AST + design-system config → single-file HTML
+python3 markdown-html/skills/md-document/scripts/html_renderer.py \
+    --sections sections.json --output document.html
+
+# 3. Inject lightweight JS (search, copycode, smoothscroll, scrollspy)
+python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
+    --file document.html \
+    --features search,copycode,smoothscroll,scrollspy
+```
+
+Or all-in-one (sample render):
+
+```bash
+python3 markdown-html/skills/md-document/scripts/html_renderer.py --sample \
+  | python3 markdown-html/skills/md-document/scripts/interactivity_injector.py \
+      --file /dev/stdin --output document.html
+```
+
+## What gets rendered
+
+CommonMark subset sufficient for agent-generated artifacts:
+- Headings H1-H6 (every H2+ gets an anchor id and TOC entry)
+- Paragraphs with inline **bold** / *italic* / `code` / [links](url) / ![images](url)
+- Fenced code blocks (` ```python `) with Prism.js highlighting on demand
+- GFM tables with per-column alignment
+- GFM callouts (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`)
+- Blockquotes, ordered + unordered lists (single-level), horizontal rules
+
+Out of scope: nested lists, HTML inlines, footnotes, definition lists, task list checkboxes (rendered as plain text), reference-style links.
+
+## Hard rules
+
+1. **Refuses input < 100 lines.** Markdown wins below the threshold (Shihipar).
+2. **Refuses without onboarding.** `config_loader.setup_completed()` must return `True`. Otherwise surface `/cs:design-system`.
+3. **Single-file output.** All CSS + JS inline. Only externals are `fonts.googleapis.com` and `cdn.jsdelivr.net` (Prism). Anything else is a regression.
+4. **Customization must change behavior.** `design_style=editorial` produces 720px-wide layout with 1.75 line-height; `playful` rounds the callouts and adds shadow; `technical` is dense with 0.875rem code. Smoke-tested.
+5. **WCAG-compliant tokens.** Inherits the design-system's WCAG AA palette — body text ≥ 4.5:1 contrast, links iteratively walked to 4.5:1.
+6. **Idempotent injection.** Re-injecting interactivity is a no-op (marker check). Re-rendering with a different design_style works cleanly.
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+1. **What's the document for — skim, decide, or deep-read?** Recommended: name it; density follows. Canon: Shihipar; Tufte *Envisioning Information*.
+2. **Sticky-sidebar TOC or collapsible-top?** Recommended: sticky-sidebar for > 800 words / 4+ H2s; collapsible-top for shorter mobile-first docs. Canon: NN/g *TOC Best Practices* (2023).
+3. **All four interactive features, or a subset?** Recommended: all four — none of them cost more than ~1 KB. Canon: Wattenberger *Why React isn't great for actually building websites*.
+4. **Code theme — light, dark, or auto?** Recommended: auto (follows OS `prefers-color-scheme`). Canon: WCAG 2.2 §1.4.3.
+5. **Does the document have a clear H1 title?** Recommended: yes — H1 becomes the page `<title>` and is excluded from the TOC.
+
+## Distinct from
+
+- **`md-review`** — that converter renders diff blocks + severity-tagged margin annotations. This one renders prose + tables + code + callouts.
+- **`md-slides`** — that converter splits on `---` boundaries into slides. This one renders one continuous document.
+- **`marketing/landing/`** — that generates landing pages from scratch (no markdown input). This converts existing markdown.
+
+## Output artifact
+
+`{default_output_dir}/doc-{slug}.html` (path resolved by orchestrator's `output_path_resolver.py`; collision suffix `-2`, `-3`, … by default).
+
+## References
+
+- Shihipar — *Claude Code HTML output* (Medium, 2026)
+- Tufte — *Envisioning Information* (1990), ch. 2 "Micro/Macro Readings"
+- NN/g — *Table of Contents Best Practices* (2023)
+- WCAG 2.2 — §1.4.3 contrast, §2.4.5 multiple ways
+- Wattenberger — *Why React isn't great for actually building websites*
+- See `references/` for full citations

package/content/md-review/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: md-review
+description: Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts) into a single-file 2-column HTML review — unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer. Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review. Refuses without explicit --reviewer (a code review must name a human), refuses if no diff hunks present (route to md-document instead), and refuses to encode severity in color only (every badge ships color + icon + aria-label per WCAG 1.4.1). Use after orchestrator routing.
+version: 2.10.2
+author: Alireza Rezvani
+license: MIT
+tags: [markdown, html, code-review, diff, severity, annotations, single-file, design-system, wcag-1.4.1]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# md-review — Code-review markdown → 2-column HTML
+
+The code-review converter from Tier 2 of Shihipar's essay ("Code Review and PR Writeups"). Takes a markdown PR writeup with diff blocks + severity callouts and produces a single-file HTML review with a jump-nav, 2-column diff + annotation layout, and a named reviewer footer.
+
+Three stdlib tools pipeline together:
+
+```
+diff_parser.py  →  annotation_extractor.py  →  review_html_renderer.py
+   (md → diff hunks)   (md → severity-tagged    (hunks + annotations
+                        annotations attached     + tokens → 2-col HTML)
+                        to nearest hunk)
+```
+
+## When to invoke
+
+| Symptom | Action |
+|---|---|
+| `markdown-html-orchestrator` routes input as REVIEW | Invoke this skill |
+| User runs `/cs:md-review <path>.md` directly | Invoke this skill |
+| Input contains ` ```diff ` fenced blocks + `> [!MAJOR]`/`> [!BLOCKER]`/etc. callouts | Invoke this skill |
+| Input is a long-form spec / report (no diff blocks) | Route to `md-document` instead |
+| Input is a slide deck | Route to `md-slides` instead |
+| Input < 100 lines | Refuse (Shihipar threshold) |
+| Design-system not onboarded | Refuse; surface `/cs:design-system` |
+
+## Pipeline
+
+```bash
+# 1. Parse markdown → diff hunks JSON
+python3 markdown-html/skills/md-review/scripts/diff_parser.py \
+    --input <path>.md --output hunks.json
+
+# 2. Extract severity-tagged annotations, attach to nearest preceding hunk
+python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \
+    --input <path>.md --diff-blocks hunks.json --output annotations.json
+
+# 3. Render 2-col HTML (--reviewer is mandatory — refuses without)
+python3 markdown-html/skills/md-review/scripts/review_html_renderer.py \
+    --diff-blocks hunks.json --annotations annotations.json \
+    --reviewer "Jane Doe" --title "PR #123: Add retry logic" \
+    --output review.html
+```
+
+## What gets rendered
+
+- **Top jump-nav** — every annotation with severity badge + 80-char preview + jump link; severity counts in the heading ("3 BLOCKER · 2 MAJOR · 1 NIT")
+- **2-column hunk rows** — unified diff on the left (per-line old/new line numbers, +/− marks, addition/deletion background tint from design-system tokens), annotation cards on the right (color + icon + aria-label per WCAG 1.4.1)
+- **Approval bar** — if `LGTM` markers are present and no severity annotations, a success-tinted "LGTM — no findings flagged" bar
+- **General comments** — annotations not attached to any hunk render at the bottom in their own section
+- **Reviewer footer** — mandatory; refuses to render without `--reviewer`
+- **Responsive** — 2-col collapses to stacked on viewports < 900px
+
+## Hard rules
+
+1. **`--reviewer` is mandatory.** A code review must name a human reviewer. Refuses with exit 3 otherwise. Mirrors research-ops's "named owner" discipline.
+2. **Refuses if no hunks present.** No `--- a/file` + `@@ ... @@` blocks means this isn't a code review — refuses with exit 4 and recommends `md-document`.
+3. **Refuses input < 100 lines.** Markdown wins below the threshold (Shihipar).
+4. **Refuses without onboarding.** Same gate as every converter.
+5. **Severity is never color-only.** Each badge ships color + icon + `aria-label` + text. WCAG 1.4.1 enforced at the renderer level.
+6. **Single-file output.** All CSS inline. Only external is Google Fonts CSS. No Prism in md-review (diff coloring conflicts with syntax highlighting).
+7. **Custom severity convention.** `--severity-convention "critical,important,suggestion,nit"` swaps tier names; position 0 is most severe. Default is BLOCKER / MAJOR / MINOR / NIT (Google Code Review Developer Guide).
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+1. **Who is the named reviewer?** Recommended: the user signing off on the review. Canon: research-ops named-owner pattern; *SWE at Google* ch. 9.
+2. **Which severity convention applies — default (BLOCKER/MAJOR/MINOR/NIT) or custom?** Recommended: default unless your team has a documented alternative. Canon: Google *Code Review Developer Guide*.
+3. **Are annotations anchored to specific hunks, or are some general?** Recommended: anchor everything you can; general goes to the unanchored section. Canon: *SWE at Google* ch. 9 — "Comments must reference a specific line".
+4. **What's the PR title for the `<title>` and header?** Recommended: the actual PR / commit title. Canon: docs-as-context-for-readers.
+5. **Should `LGTM` markers ship as the approval bar?** Recommended: yes if there are no severity annotations; otherwise the findings take precedence.
+
+## Distinct from
+
+- **`md-document`** — that converter renders prose + tables + code + callouts. This one renders diff hunks + margin annotations.
+- **`md-slides`** — that converter splits on `---` boundaries. This one is a single-page artifact.
+- **GitHub PR comments** — those are a thread. This is a single-author snapshot artifact.
+
+## Output artifact
+
+`{default_output_dir}/review-{slug}.html` (path resolved by orchestrator's `output_path_resolver.py`; collision suffix `-2`, `-3`, … by default).
+
+## References
+
+- Shihipar — *Claude Code HTML output* (Medium, 2026), Tier 2 use case
+- *Software Engineering at Google* (Manshreck & Wright, O'Reilly 2020), ch. 9 "Code Review"
+- Google *Code Review Developer Guide* — severity convention source
+- WCAG 2.2 §1.4.1 — color-not-sole-signal enforcement
+- See `references/` for full citations (diff_rendering_canon, severity_coding, pr_annotation_ux)

package/content/md-slides/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: md-slides
+description: Converts a markdown deck (slides separated by `---` HR boundaries or by `# ` H1 headings, with optional `<!-- notes: ... -->` presenter notes blocks) into a single-file HTML presentation with arrow-key / space / PgDn / PgUp / Home / End / P / Esc keyboard navigation, presenter mode (split view with current slide + speaker notes + clock + next-slide preview), URL-hash deep linking, and `@media print` page-per-slide for PDF export. Triggers when the markdown-html-orchestrator classifies an input as SLIDES, or when invoked directly via /cs:md-slides. Reuses md-document's markdown parser for slide-body rendering and reads design-system tokens via config_loader.py. Refuses if input has no clear slide boundaries, produces a 1-slide deck, or `--strict-notes` is on with < 50% notes coverage. Use after orchestrator routing.
+version: 2.10.3
+author: Alireza Rezvani
+license: MIT
+tags: [markdown, html, slides, deck, presenter-mode, keyboard-nav, print-to-pdf, single-file, design-system]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# md-slides — Markdown deck → single-file HTML presentation
+
+The slide-deck converter. Reads a markdown deck (HR or H1 boundaries, optional presenter notes), emits a single-file HTML presentation that runs in any browser with keyboard navigation, presenter mode, and print-to-PDF.
+
+Three stdlib tools pipeline together:
+
+```
+slide_splitter.py  →  presenter_notes_parser.py  →  deck_html_renderer.py
+   (md → ordered      (extract <!-- notes:         (slides + design-system
+    slides with       --> blocks, attach            tokens → single-file
+    titles)           per slide)                    HTML with keyboard nav)
+```
+
+## When to invoke
+
+| Symptom | Action |
+|---|---|
+| `markdown-html-orchestrator` routes input as SLIDES | Invoke this skill |
+| User runs `/cs:md-slides <path>.md` directly | Invoke this skill |
+| Input has 3+ `---` HR lines OR 5+ H1 headings with short bodies | Invoke this skill |
+| Input is a long-form spec | Route to `md-document` instead |
+| Input is a code review | Route to `md-review` instead |
+| Input has no clear slide boundaries | Refuse, route to `md-document` |
+| Input would produce 1 slide | Refuse (it's a poster) |
+
+## Pipeline
+
+```bash
+# 1. Split slides on --- or H1 (auto-detect by default)
+python3 markdown-html/skills/md-slides/scripts/slide_splitter.py \
+    --input <path>.md --output /tmp/slides.json
+
+# 2. Extract <!-- notes: ... --> blocks from each slide
+python3 markdown-html/skills/md-slides/scripts/presenter_notes_parser.py \
+    --slides /tmp/slides.json --output /tmp/deck.json
+
+# 3. Render single-file HTML deck
+python3 markdown-html/skills/md-slides/scripts/deck_html_renderer.py \
+    --slides /tmp/deck.json --title "My Talk" --output deck.html
+```
+
+## What ships in the HTML
+
+- **All slides as `<section class="slide">`** — one visible at a time, controlled by JS
+- **Keyboard nav** — `→` / `Space` / `PgDn` advance; `←` / `PgUp` previous; `Home`/`End` jump; `P` presenter mode; `Esc` exits presenter
+- **URL-hash deep linking** — `#3` jumps to slide 3; browser back/forward walks slides; share `deck.html#5` to send someone directly there
+- **Progress bar** — 3px at top showing position through the deck
+- **Slide counter** — bottom-right ("3 / 12")
+- **Presenter mode** (P key) — splits the window: current slide on left (60% width), panel on right with clock + speaker notes + next-slide preview
+- **Print stylesheet** — `Cmd+P` produces a PDF with one slide per page
+- **`@media (prefers-reduced-motion: reduce)`** honored
+- **12 brand CSS custom properties** from design-system; design_style affects layout density
+- **Reuses md-document's markdown parser** — slide bodies render with consistent paragraph/list/code/table/callout handling
+
+## Hard rules
+
+1. **Refuses input with no clear slide boundaries.** Auto mode needs ≥ 3 HR lines or ≥ 5 H1 headings. Otherwise exit 6 — route to md-document.
+2. **Refuses 1-slide decks.** That's a poster, not a deck. Exit 5.
+3. **Refuses input < 100 lines.** Same Shihipar threshold as all converters.
+4. **Refuses without onboarding.** Same gate as every converter.
+5. **`--strict-notes` refuses < 50% notes coverage.** A deck where most slides have no notes isn't set up for presenter mode. Exit 7.
+6. **Soft-warns slides > 40 source lines.** Signal-to-noise; renders anyway but surfaces the count.
+7. **Single-file output.** All CSS + JS inline. Only external is Google Fonts CSS. Prism.js is opt-in via `--syntax`.
+8. **No JS framework runtime.** Vanilla JS + keyboard event handlers, no React/Vue/Svelte.
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+1. **Is this actually a deck, or a long document?** Recommended: if you can't draw clear slide boundaries, it's not a deck. Canon: Tufte *Cognitive Style of PowerPoint*.
+2. **HR (`---`) or H1 boundaries?** Recommended: HR for typical decks; H1 for outline-driven decks. Canon: Marp / reveal.js / pandoc convergence.
+3. **Will it be presented live or distributed for self-paced reading?** Recommended: live → need presenter notes; self-paced → notes optional. Canon: Weinschenk *100 Things Every Presenter Needs to Know*.
+4. **Is there any slide over 40 source lines?** Recommended: split it. Canon: NN/g — audience attention drops past ~6 bullets / 200 words.
+5. **Is `--syntax` needed?** Recommended: only for decks with substantial code blocks. Default off. Canon: single-file shareability discipline.
+
+## Distinct from
+
+- **`md-document`** — that's one continuous document. This is N discrete slides.
+- **`md-review`** — that renders diff hunks + annotations. This renders prose slides.
+- **`marketing/landing/`** — that's a landing page, not a deck.
+- **Keynote / PowerPoint** — those are graphic-design tools. This is for markdown-authored decks projected from a browser.
+
+## Output artifact
+
+`{default_output_dir}/deck-{slug}.html` (path resolved by orchestrator's `output_path_resolver.py`; collision suffix `-2`, `-3`, … by default).
+
+## References
+
+- Shihipar — *Claude Code HTML output* (Medium, 2026), Tier 3 use case "Slide Decks"
+- Reynolds — *Presentation Zen* (less is more discipline)
+- Atkinson — *Beyond Bullet Points* (the bullet-heavy failure mode)
+- Tufte — *The Cognitive Style of PowerPoint* (the polemic)
+- reveal.js / Big / Marp — convergent markdown-to-deck conventions
+- See `references/` for full citations (presentation_ux, keyboard_nav_patterns, single_file_deck_conventions)

package/dist/index.js

@@ -14,6 +14,17 @@ const DOMAINS = [
     'ai-security',
     'research',
     'research-ops',
+    'marketing',
+    'product',
+    'c-level',
+    'compliance',
+    'content',
+    'finance',
+    'commercial',
+    'productivity',
+    'project-management',
+    'business',
+    'superpowers',
 ];
 function parseFrontmatter(raw) {
     const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/m);
@@ -62,11 +73,61 @@ function loadSkills() {
     }
     return skills;
 }
+function scoreSkills(skills, task) {
+    const lower = task.toLowerCase();
+    const keywords = lower.split(/\s+/);
+    return skills.map(s => {
+        const desc = s.description.toLowerCase();
+        const name = s.name.toLowerCase();
+        let score = 0;
+        for (const kw of keywords) {
+            if (desc.includes(kw))
+                score += 2;
+            if (name.includes(kw))
+                score += 3;
+            if (s.domain.includes(kw))
+                score += 1;
+        }
+        return { ...s, score };
+    }).sort((a, b) => b.score - a.score);
+}
 async function main() {
     const skills = loadSkills();
     const server = new McpServer({
         name: 'runic',
-        version: '1.0.0',
+        version: '1.1.0',
+    });
+    server.tool('runic-prompt-engineer', 'Single entry point for all Runic skills. Analyzes the user task, matches it to the best skill, and returns the skill content with enhanced prompt engineering context. Call this FIRST before using any individual skill tool.', { task: z.string().describe('The user task or request description') }, async ({ task }) => {
+        const scored = scoreSkills(skills, task);
+        const top = scored.filter(s => s.score > 0).slice(0, 3);
+        const text = top.length > 0
+            ? top.map((s, i) => {
+                const role = i === 0
+                    ? 'PRIMARY'
+                    : i === 1
+                        ? 'ALTERNATIVE'
+                        : 'FALLBACK';
+                return [
+                    `## ${role}: ${s.name} (${s.domain})`,
+                    `**Description:** ${s.description}`,
+                    `**Relevance Score:** ${s.score}`,
+                    ``,
+                    s.content,
+                ].join('\n');
+            }).join('\n\n---\n\n')
+            : `No specific skill matched your task. Available skills:\n\n${skills.map(s => `- **${s.name}** (${s.domain}): ${s.description}`).join('\n')}`;
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `# Prompt Engineering Analysis`,
+                        ``,
+                        `**Original Task:** ${task}`,
+                        ``,
+                        text,
+                    ].join('\n'),
+                }],
+        };
     });
     for (const skill of skills) {
         server.tool(skill.name, skill.description, { context: z.string().optional().describe('Additional context from the user') }, async ({ context }) => ({
@@ -78,7 +139,6 @@ async function main() {
                 }],
         }));
     }
-    // List all skills tool
     server.tool('runic-list', 'List all available Runic skills with their names, domains, and descriptions.', {}, async () => ({
         content: [{
                 type: 'text',

package/engineering/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "engineering",
+  "description": "Core AI & dev engineering skills: code review, debugging, testing, refactoring, git commits, docs, LLM optimization, prompt engineering, agent design",
+  "version": "1.0.0",
+  "author": {
+    "name": "Diottodev",
+    "url": "https://github.com/Diottodev/@diottodev/runic"
+  },
+  "homepage": "https://github.com/Diottodev/@diottodev/runic/tree/main/engineering",
+  "repository": "https://github.com/Diottodev/@diottodev/runic",
+  "license": "MIT",
+  "skills": [
+    "./code-review",
+    "./debug-error",
+    "./explain-code",
+    "./generate-tests",
+    "./git-commit",
+    "./refactor",
+    "./write-docs",
+    "./llm-cost-optimizer",
+    "./prompt-engineering",
+    "./agent-designer"
+  ]
+}

package/engineering/CLAUDE.md

@@ -0,0 +1,28 @@
+# Engineering Domain
+
+> 10 skills | Core AI & dev tools
+
+## Skills
+
+| Skill | Trigger |
+|-------|---------|
+| [code-review](./code-review/) | "review", "check", "audit" code |
+| [debug-error](./debug-error/) | error message, stack trace, "not working" |
+| [explain-code](./explain-code/) | "what does this do?", "explain this" |
+| [generate-tests](./generate-tests/) | "write tests", "add coverage" |
+| [git-commit](./git-commit/) | "commit message", "help me commit" |
+| [refactor](./refactor/) | "refactor", "clean up", "simplify" |
+| [write-docs](./write-docs/) | "document", "add JSDoc", "add comments" |
+| [llm-cost-optimizer](./llm-cost-optimizer/) | "reduce costs", "cheaper model", "token usage" |
+| [prompt-engineering](./prompt-engineering/) | "improve prompt", "prompt design", "system prompt" |
+| [agent-designer](./agent-designer/) | "design agent", "tool calling", "multi-agent" |
+
+## Install (standalone)
+
+```bash
+# Claude Code
+claude mcp add @diottodev/runic-engineering node dist/index.js --env SKILL_DOMAIN=engineering
+
+# Cursor — .cursor/mcp.json
+{ "engineering-skills": { "command": "node", "args": ["dist/index.js"] } }
+```