npm - haac-aikit - Versions diffs - 0.8.3 → 0.10.0 - Mend

haac-aikit 0.8.3 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/README.md CHANGED Viewed

@@ -6,6 +6,13 @@
 One command drops a working AI-coding setup into any repo — rules, skills, safety hooks, subagents, MCP stub, CI templates — for Claude Code, Cursor, Copilot, Windsurf, Aider, Gemini CLI, and Codex.
+> [!TIP]
+> **Just want HTML output from Claude Code?** Skip the full kit and install only the html-artifacts skill + 20 templates:
+>
+> ```bash
+> npx haac-aikit init html
+> ```
 ## Quickstart
 ```bash

package/catalog/commands/html.md CHANGED Viewed

@@ -1,4 +1,4 @@
-Generate an HTML artifact for the current context using the html-artifacts skill.
+Produce an HTML artifact for the current context using the `html-artifacts` skill and the forked reference templates.
 ## Usage
 `/html [optional intent]`
@@ -6,24 +6,56 @@ Generate an HTML artifact for the current context using the html-artifacts skill
 ## Steps
 1. **Determine intent**
-   - If called with args (e.g. `/html code review of today's PR`): use the args as the intent.
-   - If called with no args: infer intent from the current conversation — what task is in progress, what was just discussed, what files are open.
-2. **Pick the use-case pattern**
-   Using the `html-artifacts` skill, identify which of the eight patterns fits:
-   Spec/Planning, Code Review, Report/Research, Prototype, Custom Editor, Visual Explainer, Deck, or Design System.
-3. **Generate the artifact**
-   - Apply the built-in design system CSS tokens
-   - If `docs/aikit-html-design-system.html` exists in the project, read it first and inherit its CSS variable values
-   - Follow the structure guidance for the chosen pattern
-   - Pure HTML/CSS/JS only — no external CDN dependencies
-   - Include in `<head>`: `<title>`, `<meta name="description" content="...">`, and `<meta name="aikit-pattern" content="...">` (the pattern name from step 2) — required for the index
-4. **Save and report**
-   - Determine a short slug from the intent (e.g. `code-review-auth-pr`, `weekly-report`)
-   - Determine `NN` by listing existing files in `.aikit/artifacts/` (excluding `index.html`) and incrementing the highest number; start at `01`
-   - Save to `.aikit/artifacts/NN-<slug>.html` (e.g. `07-code-review-auth-pr.html`)
-   - Regenerate `.aikit/artifacts/index.html` per the "Index page (gallery)" section of the `html-artifacts` skill
-   - Print both paths
-   - Suggest opening: `open .aikit/artifacts/index.html` (macOS) / `xdg-open .aikit/artifacts/index.html` (Linux)
+   - With args (e.g. `/html code review of today's PR`): use the args as the intent.
+   - Without args: infer from the current conversation — what task is in progress, what was just discussed, what files are open.
+2. **Pick the pattern**
+   Match the intent to one of the **9 patterns** in `.claude/skills/html-artifacts.md`:
+   - Exploration & Planning (code approaches · visual directions · implementation plans)
+   - Code Review & Understanding (PR review · PR writeup · module map)
+   - Design (design system · component variants)
+   - Prototyping (animation · interaction)
+   - Illustrations & Diagrams (SVG figures · flowcharts)
+   - Decks (slide presentations)
+   - Research & Learning (feature explainer · concept explainer)
+   - Reports (status · incident)
+   - Custom Editing Interfaces (triage board · feature flags · prompt tuner)
+3. **Look up the template**
+   Read `.aikit/templates/html-artifacts/MANIFEST.json`. Find the entry whose `category` matches the pattern from step 2 and whose `slug` matches the intent best (e.g. for a PR review intent → slug `pr-review`).
+4. **Read the template**
+   Use the Read tool on `.aikit/templates/html-artifacts/<file>.html` for that entry. This is the structural ground truth — copy its CSS variables, class names, layout grids, and visual conventions **verbatim**.
+5. **Gather project context**
+   Pull real facts the artifact needs to display:
+   - For Code Review: `git diff main...HEAD`, file list with classifications
+   - For Reports: `git log --since=...`, deploy logs, incident notes
+   - For Design System: read `docs/aikit-html-design-system.html` if it exists, else use the tokens from the template
+   - For Research/Explainer: read the source files the explainer covers
+   - For Implementation Plan: milestones, packages affected, risky code
+6. **Produce the filled artifact**
+   Write a new HTML file that mirrors the template's structure but with the gathered context replacing the placeholder content. Preserve:
+   - All CSS `:root` design tokens
+   - All class names and layout grids
+   - All cross-cutting techniques (sticky toolbars, scroll-margin-top, microinteractions, `<details>` collapsibles)
+   - The visual language: severity colors, badge styles, dot indicators, monospace meta text
+   Required in `<head>`:
+   - `<title>` and `<meta name="description">`
+   - `<meta name="aikit-pattern" content="...">` — exactly one of: `Exploration`, `Code Review`, `Design`, `Prototype`, `Illustrations`, `Deck`, `Research`, `Report`, `Editor`
+   Add an `AUTO-GENERATED` pill top-right and a provenance footer (`Sources: ... — generated <ISO timestamp>`).
+7. **Save with sequential numbering**
+   - Slug from intent: e.g. `code-review-auth-pr`, `weekly-status-mar-10`
+   - Determine `NN` by listing `.aikit/artifacts/*.html` (excluding `index.html`) and incrementing the highest number; start at `01`
+   - Save to `.aikit/artifacts/NN-<slug>.html`
+8. **Regenerate the gallery index**
+   Rebuild `.aikit/artifacts/index.html` from scratch per the "Gallery index protocol" in the skill. List all artifacts, group by `<meta name="aikit-pattern">`, drop empty groups.
+9. **Report**
+   Print both paths and suggest: `open .aikit/artifacts/index.html` (macOS) / `xdg-open .aikit/artifacts/index.html` (Linux).
+## Fallback
+If `.aikit/templates/html-artifacts/` does not exist (e.g. project synced before this kit version), run `aikit sync` first, or use the user-driven path: `aikit scaffold html <slug>` to drop a starter, then ask the agent to fill it.

package/catalog/release-notes.json ADDED Viewed

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "releases": [
+    {
+      "version": "0.9.0",
+      "date": "2026-05-12",
+      "headline": "HTML artifact scaffolding + 20 forked templates + cross-tool skill discovery",
+      "highlights": [
+        "NEW `aikit scaffold html <slug>` — drops one of 20 HTML reference templates into the current dir",
+        "NEW 20 forked templates at `.aikit/templates/html-artifacts/` (with permission from ThariqS)",
+        "NEW `aikit whatsnew` command for release notes",
+        "NEW Update-available banner (runs once per 24h; opt out with AIKIT_NO_UPDATE_CHECK=1)",
+        "CHANGED `html-artifacts` skill v1.1.0 → v2.0.0: 9 patterns, mandatory template-read protocol",
+        "CHANGED `aikit sync` now also syncs templates; `aikit list` shows them as a category",
+        "CHANGED Skill discovery propagates to all 6 non-Claude tools via AGENTS.md.tmpl",
+        "FIXED gitignore — only `.aikit/artifacts/` ignored; templates are now committable"
+      ],
+      "breaking": [
+        "`html-artifacts.md` skill is a complete rewrite — if you customized it, `aikit sync` will flag a conflict"
+      ],
+      "migration": [
+        "Run `aikit sync` to pull the 20 new templates into `.aikit/templates/html-artifacts/`",
+        "Templates will now appear in `git status` after sync (intentional — they're reference material)"
+      ],
+      "links": {
+        "changelog": "https://github.com/Hamad-Center/haac-aikit/blob/main/CHANGELOG.md#090--2026-05-12",
+        "release": "https://github.com/Hamad-Center/haac-aikit/releases/tag/v0.9.0"
+      }
+    }
+  ]
+}

package/catalog/rules/AGENTS.md.tmpl CHANGED Viewed

@@ -47,6 +47,16 @@ TODO: How to run a single test; framework quirks.
 TODO: Project-specific security notes.
+## Skills and templates
+<!-- This section is shipped by haac-aikit so every tool (Claude, Cursor, Aider,
+     Copilot, Windsurf, Gemini, Codex) sees the same skill-discovery rules.
+     The .claude/ path name is historical; the content there is tool-agnostic. -->
+- <!-- id: skills.read-on-match --> Skill instructions live at `.claude/skills/*.md`. When a task matches a skill's `## When to use` rules, **read that skill before producing output** — it ships pattern-specific techniques and protocols that this file does not repeat.
+- <!-- id: skills.html-artifacts --> For HTML artifact production (specs, plans, PR reviews, design systems, prototypes, diagrams, decks, research explainers, reports, custom editing interfaces): the `html-artifacts` skill at `.claude/skills/html-artifacts.md` is **mandatory**. Forked reference templates live at `.aikit/templates/html-artifacts/` with a machine-readable `MANIFEST.json`. **Read the matching template first** before writing; do not invent HTML structure from scratch.
+- <!-- id: skills.scaffold-cli --> User-driven scaffolding: `aikit scaffold html <slug>` drops a starter template into the current directory. Run `aikit scaffold html --list` to see all 20.
+- <!-- id: artifacts.output-path --> Filled artifacts go to `.aikit/artifacts/NN-<slug>.html` (incrementing `NN`). Regenerate `.aikit/artifacts/index.html` after each write; the gallery is auto-maintained.
 ## Gotchas
 <!-- High-signal section. Add things the agent repeatedly gets wrong.
      Tip: prefix the most load-bearing rules with `IMPORTANT:` or `YOU MUST` —

package/catalog/skills/tier1/html-artifacts.md CHANGED Viewed

@@ -1,109 +1,205 @@
 ---
 name: html-artifacts
-description: Use when generating output that would benefit from rich formatting — specs, plans, reports, code review explainers, prototypes, decks, design-system pages, visual explainers, or custom editors. Maintains a gallery index at .aikit/artifacts/index.html so artifacts compound into a navigable project archive. Inspired by Thariq Shihipar's "Unreasonable Effectiveness of HTML" (Anthropic, 2026).
-version: "1.1.0"
+description: Use when producing structured output that benefits from rich layout, comparison, drill-in, or interaction — specs, plans, PR reviews, design systems, prototypes, diagrams, decks, research explainers, reports, and custom editors. Scaffolds from 20 forked reference templates at `.aikit/templates/html-artifacts/` and fills them with project context. Maintains a gallery at `.aikit/artifacts/index.html`.
+version: "2.3.0"
 source: haac-aikit
 license: MIT
+inspired-by: https://thariqs.github.io/html-effectiveness (templates forked with permission, 2026-05-12)
 ---
 ## When to use
-- Output is > ~80 lines of content
-- Task involves comparison, multiple options, or visual layout
-- User asks for a spec, plan, report, PR explainer, or prototype
-- User mentions "share", "send to team", or "easy to read"
+- Output is comparison, drill-in, or interactive — not linear prose
+- Task is a spec, plan, review, report, prototype, design system, diagram, deck, explainer, or editor
+- User says "share", "review", "scan", "click through", "demo", "tune"
+- Output would otherwise be > ~80 lines of markdown
+Default to markdown for linear prose. HTML earns its weight only when structure or interaction is the point.
 ## Proactive offer rule
-When conditions above are met but the user didn't explicitly ask for HTML, say one sentence before proceeding:
-> "I can generate this as an HTML artifact for easier reading — want that?"
-Wait for a yes/no. If yes, proceed with HTML. If no, use markdown.
-## Use-case patterns
-### 1. Spec / Planning
-**Trigger:** Long spec, multiple options to compare
-**Structure:** Tabs per option, decision log section, embedded mockup slots
-**Don't:** Skip the decision rationale — that's the whole point of the doc
-### 2. Code Review
-**Trigger:** PR explainer, diff walkthrough, architecture audit
-**Structure:** Rendered diff with color, severity badges (ok/warn/error), inline margin annotations
-**Don't:** Show a raw unified diff without color — unreadable
-### 3. Report / Research
-**Trigger:** Status report, incident summary, research synthesis
-**Structure:** Executive summary at top, SVG diagrams, section anchors for navigation
-**Don't:** Bury the conclusion — lead with it
-### 4. Prototype
-**Trigger:** Animation tuning, layout exploration, parameter tweaking
-**Structure:** Sliders/knobs for live adjustment, preview pane, "copy params" export button
-**Don't:** Ship without an export mechanism — the params need to go somewhere
-### 5. Custom Editor
-**Trigger:** Ticket triage, config editing, dataset curation
-**Structure:** Drag/sort or form UI, constraint warnings, "copy as JSON/prompt" export button
-**Don't:** Let the editor be the only output — always export
-### 6. Visual Explainer
-**Trigger:** Explaining a concept, system, or workflow where a diagram beats prose
-**Structure:** One hero inline `<svg>` with labelled regions, short text blocks anchored to those regions, "view source" toggle that reveals the underlying data
-**Don't:** Use raster images or external icon CDNs — keep SVG inline so the artifact stays self-contained and editable
-### 7. Deck
-**Trigger:** Slide presentation, talk preview, pitch, "walk me through this"
-**Structure:** One slide per viewport (`100vh`), large body type (≥32px), arrow-key navigation, single idea per slide, speaker notes hidden behind a key press
-**Don't:** Generate scrolling content — if the user would scroll, it's a Report, not a Deck
-### 8. Design System
-**Trigger:** Building or documenting a design system, component library reference, token palette
-**Structure:** Live component samples beside their source HTML/CSS, swatches for color/spacing/type tokens, copy-on-click for each token value
-**Don't:** Use screenshots of components — the components on the page must be the real, live HTML
-## Built-in design system
-Inject this CSS block into every artifact. If the project has `docs/aikit-html-design-system.html`, read it first and use those variable values instead.
-```css
-:root {
-  --color-bg:      #0f1117;
-  --color-surface: #1a1d27;
-  --color-border:  #2e3143;
-  --color-text:    #e2e8f0;
-  --color-muted:   #8892a4;
-  --color-accent:  #6366f1;
-  --color-ok:      #22c55e;
-  --color-warn:    #f59e0b;
-  --color-error:   #ef4444;
-  --radius:        6px;
-  --font-sans:     system-ui, -apple-system, sans-serif;
-  --font-mono:     "JetBrains Mono", "Fira Code", monospace;
-  --space:         4px;
-}
-```
-Pre-built components available: `.card`, `.badge` (`.badge-ok/warn/error/info`), `.tabs` + `.tab` + `.tab-panel`, `.code-block`, `.diff-block` + `.diff-line` + `.diff-line-add/del/ctx`.
+When conditions match but the user didn't ask for HTML, say one sentence and wait:
+> "I can produce this as an interactive HTML artifact (scaffolded from a template) — want that?"
+## Cross-cutting techniques (apply to ALL patterns)
+- **Design tokens** in `:root`: `--clay #D97757`, `--slate #141413`, `--ivory #FAF9F5`, `--oat #E3DACC`, `--olive #788C5D`, `--gray-150 #F0EEE6`, `--gray-300 #D1CFC5`, `--gray-500 #87867F`, `--gray-700 #3D3D3A`, `--white #FFFFFF`
+- **Font stack**: `system-ui, -apple-system, "Segoe UI", Roboto` for sans; `ui-serif, Georgia` for `--serif`; `ui-monospace, "SF Mono"` for `--mono`
+- **Layout**: CSS Grid for structure; flex + gap for toolbars and rows
+- **Sticky**: toolbars / TOCs / column headers use `position: sticky; top: 0; z-index: 1`
+- **Responsive type**: `font-size: clamp(min, Nvw, max)` for headings — no breakpoint jumps
+- **Microinteractions**: `:hover { transform: translateY(-1px) }`, `:active { transform: translateY(1px) }`, transitions 120–600ms with explicit properties — **never `transition: all`**
+- **Semantic HTML**: `<details>`, `<summary>`, native `<button>`, native `<input>` — **never div-button hacks**
+- **Mobile**: at least one `@media (max-width: 960px)` breakpoint per artifact
+- **Dot indicators**: small colored circles via `::before` pseudo-elements (severity, ownership, status)
+- **Shadows**: subtle only — `0 1px 3px rgba(20, 20, 19, 0.06)`; never heavy drop shadows
+- **Anchors**: every section heading has an `id`; `scroll-margin-top: 28px` on sections
+- **Provenance footer**: every generated artifact ends with `Sources: … — generated <ISO timestamp>`
+- **AUTO-GENERATED pill**: top-right badge on agent-produced artifacts so readers know the origin
+- **Prompt callout**: exploration / planning artifacts preserve the originating user request in a cream-tinted box at top
+- **Density-adaptive rendering**: when the artifact's total visible items (milestones + risks + cards + rows across all sections) is ≤ 6, drop decorations designed for dense pages — section numbers, tag chips, colored dot indicators, multi-column summary cards. These visuals were tuned for ~12-item artifacts; on sparse content they read as noise instead of hierarchy. The point of structure is signal; if there's little content, decoration buries it.
+- **Decision callout first**: any artifact that asks the user to decide something starts with a "Decision needed" block at the top — the call-to-action in one sentence, options in chips (`A —` / `B —`), the recommendation marked. Don't make decision-makers scroll to find what to approve.
+## Accessibility (a11y)
+Decision documents get read on phones, with screen readers, in high-contrast mode, by keyboard-only users. The bar is the same as the voice rule — make the artifact work for the actual reading environment, not just a desktop browser.
+**Hard rules:**
+1. **Landmark roles** — wrap top-level structure in `<main>`, `<nav>`, `<article>`, `<aside>`. Screen readers use these to navigate; readers without them have to crawl the document linearly.
+2. **Alt text on every diagram and icon** — inline `<svg>` gets `<title>` + `aria-labelledby` or `aria-label`; `<img>` gets `alt="..."`. Purely decorative icons get `aria-hidden="true"` so they don't announce as noise.
+3. **Heading hierarchy never skips levels** — `<h1>` → `<h2>` → `<h3>`. Exactly one `<h1>` per artifact (the title).
+4. **Native form controls only** — `<input>` paired with `<label for="...">`, `<button>` for buttons, native `<select>`. No div-button hacks.
+5. **Color contrast ≥ 4.5:1 for body text, ≥ 3:1 for large text** — design tokens already meet WCAG AA; don't override per-artifact in ways that break the ratio.
+6. **Keyboard focus visible** — never `outline: none` without a `:focus-visible` replacement that meets contrast.
+## Voice & plain-language rule
+The default reader is a smart non-specialist taking a decision. They should understand every sentence on first read without expanding tooltips, looking up jargon, or having prior domain context.
+**Four sub-rules:**
+1. **One concept per sentence** — no "X with Y and Z" compounds.
+2. **Plain-language verb + concrete object** — "Load images only when the reader scrolls to them" beats "Implement lazy-loading via IntersectionObserver."
+3. **Jargon lives in tag chips, `<code>` spans, or collapsed `<details>`** — never in the main reading path.
+4. **Concrete first, abstract term in parens** — "Make sure failed requests retry safely (idempotent)" beats "Idempotent retry on failure."
+**Three side-by-side examples (bad → good):**
+| Bad | Good |
+| --- | --- |
+| "Schema & API contract — tRPC router stubs reviewed before anything else lands" | "Define the API the backend will expose. Review the contract before any UI work." |
+| "Optimistic insert with rollback on failure, one level of nesting only" | "Show the comment immediately. Roll back if the server rejects it. One level of replies — no deeper threads." |
+| "Fan-out via realtime channel, per-user read cursors track unread state" | "When a card is open, listen for new comments on it. Push updates to everyone watching." |
+The technical details (`tRPC`, `optimistic insert`, `fan-out`) still appear in the artifact — but as tag chips beneath the prose, not in the reading path. The visible layer is decision-grade scannable; the chip layer keeps the artifact grep-able and AI-readable.
+## Pattern playbook (9 patterns, aligned with the source)
+### 1. Exploration & Planning
+**Templates**: `01-exploration-code-approaches.html`, `02-exploration-visual-designs.html`, `16-implementation-plan.html`
+**Use for**: comparing N approaches, exploring visual directions, handing off a plan
+**Concrete techniques**: numbered approach badges (`01`/`02`/`03`) in oat chips · equal-width code blocks for visual symmetry · pro/con tables with colored dot bullets (olive=pro, clay=con) · chip metrics footer (bundle, testability, reuse, SSR safety) · recommendation callout with left clay border + serif 22px · light/dark toggle via single `:root` swap · numbered milestone rows with date columns on left · phase cards with package chips · risks table (RISK / SEV / MITIGATION) · "Decide with · person · before slice N" footer on open questions
+**Must-haves**: preserve the originating prompt as a top callout; numbered section dots if > 4 sections; **Decision needed block at the very top** — a clay-bordered card stating the call-to-action, the options considered (chips: `A —` / `B —`), and which one is recommended. Buried decisions are the failure mode this prevents.
+### 2. Code Review & Understanding
+**Templates**: `03-code-review-pr.html`, `17-pr-writeup.html`, `04-code-understanding.html`
+**Use for**: PR reviews, author writeups, module / architecture explainers
+**Concrete techniques**: PR header card (repo · PR# · title · author avatar · branch arrow `→` · `+lines / -lines` · file count) · risk map: horizontal chip cluster with 3-state legend (safe / worth a look / needs attention) · per-file expandable `<details>` with severity badge + line-count chip · diff grid `[line# | mark | code]` on dark slate, `.add/.del/.ctx/.hunk` states at 15% opacity · review comment bubble: left accent + `::before` triangle pointer + line# tag + BLOCKING (clay) / NIT (gray) label · "Suggested next steps" checkbox list at the end · for module maps: inline SVG with hot path in clay, right sidebar with "Key files" + "Gotchas" panels · `<details>` "show source" toggle on long code blocks
+**Must-haves**: severity color coding; collapsed files at the end; clickable jump links between sections
+### 3. Design
+**Templates**: `05-design-system.html`, `06-component-variants.html`
+**Use for**: design system references, component-variant matrices
+**Concrete techniques**: color groups in named bands (PRIMARY / NEUTRAL / SEMANTIC) · each swatch shows 64×64 chip + hex + token name · typography table with shared specimen text repeated at each scale, size/leading/weight as right-aligned monospace meta · vertical spacing-bar ruler (`overflow-x: auto`) · radius + elevation showcase cards · core-components stage with `<Button />`-style XML labels above each section · for variants: live control panel (slider + segmented + checkbox) affecting all variants live · "best for: ..." rationale below each variant · hovered-variant code-preview pane
+**Must-haves**: tokens have both hex AND name; components on the page are real HTML, not images
+### 4. Prototyping
+**Templates**: `07-prototype-animation.html`, `08-prototype-interaction.html`
+**Use for**: animation tuning, interaction prototypes
+**Concrete techniques**: stage area with the actual interactive element + "click to toggle" caption · right-side knob panel: easing presets as selectable cards with `cubic-bezier(...)` formulas visible · keyframe timeline strip with milestone markers (`fill 0ms · check 80ms · strike 120ms · confetti 200ms · collapse 600ms`) · copy-paste CSS panel below stage with commented sections · for interactions: 2-col layout with stage left, "What you're feeling" design-notes right, "Open questions" deferral panel below
+**Must-haves**: explicit "design decisions baked in" annotations; explicit "open questions" deferred to reviewer; exportable CSS/params
+### 5. Illustrations & Diagrams
+**Templates**: `10-svg-illustrations.html`, `13-flowchart-diagram.html`
+**Use for**: SVG figure sheets, interactive flowcharts
+**Concrete techniques**: inline SVG with CSS-var theming (`fill="var(--panel)"`, `stroke="var(--line)"`) · per-figure card with download-each-as-standalone button · "Palette & rules" section at bottom (palette swatches + stroke/radius/label rules) · for flowcharts: process rectangles · decision diamonds · terminal rounded nodes (✅ green for success) · failure paths drawn dashed clay · edge labels on arrows (pass / fail / healthy) · legend at bottom (process step / decision / terminal success / failure path) · click-to-detail right sidebar showing clicked node's metadata
+**Must-haves**: every figure self-contained with its own `<style>` block (downloadable standalone); legend visible for non-trivial diagrams
+### 6. Decks
+**Template**: `09-slide-deck.html`
+**Use for**: slide presentations, walkthroughs, pitches
+**Concrete techniques**: `width: 100vw; height: 100vh` per slide · `scroll-snap-type: y mandatory` on body, `scroll-snap-stop: always` on `.slide` · responsive type `font-size: clamp(40px, 6vw, 64px)` · invert variant (`.slide.invert { bg slate; color ivory }`) for decision slides · large-serif metric values (52px) · slide counter top-right (`N / total`) · uppercase mono eyebrow on each slide ("SHIPPED THIS WEEK", "DECISION NEEDED", "ON DECK") · decision card with option chips prefixed `A —` / `B —` · footnote at bottom (absolute, monospace 11px)
+**Must-haves**: arrow-key nav (or scroll-snap); one idea per slide; if user would scroll inside a slide, it's a Report not a Deck
+### 7. Research & Learning
+**Templates**: `14-research-feature-explainer.html`, `15-research-concept-explainer.html`
+**Use for**: explaining a feature in your repo, teaching a concept
+**Concrete techniques**: sticky left "ON THIS PAGE" TOC (200px) with nested children · "FILES READ" panel below TOC for provenance · TL;DR callout with clay left border · collapsed `<details>` step rows that expand on click · file:line tags right-aligned in step headers · tabbed code blocks (e.g., `limits.yaml` / `route.ts` / `client response`) for the same concept in different views · ★ tip callouts with cream background distinct from • bullets · for concepts: live interactive widget (manipulable, not just diagram) · hover-linked glossary terms underlined in prose, defined in right sidebar · comparison table with color-coded values (red=bad, green=good)
+**Must-haves**: TL;DR at the very top; clickable TOC; explicit "FILES READ" provenance for repo-specific explainers
+### 8. Reports
+**Templates**: `11-status-report.html`, `12-incident-report.html`
+**Use for**: weekly status, sprint reviews, incident post-mortems
+**Concrete techniques**: 4-card metric band with delta sub-labels ("+3 vs wk10", "±0", "SEV-2 · 47m") · incident pills (SEV-2 clay / Resolved olive / Duration / Detected / Owner) · dark TL;DR box at top of incidents · vertical timeline with colored dots (clay = impact, olive = mitigated) and monospace time chips · shipped table with PR# / TITLE / AUTHOR / RISK columns and colored risk badges · velocity bar chart with the spike day colored · carryover items prefixed with status pills (IN REVIEW / BLOCKED / SLIPPED) · impact table (Requests failed / Peak error rate / Users affected / Data loss / SLA breach) · action-items checklist with avatar + due date · footer cites sources ("git log main..HEAD · CI dashboard · deploy log") and generation timestamp · "AUTO-GENERATED" pill top-right
+**Must-haves**: provenance footer; quantified impact for incidents; action items with owners + dates
+### 9. Custom Editing Interfaces
+**Templates**: `18-editor-triage-board.html`, `19-editor-feature-flags.html`, `20-editor-prompt-tuner.html`
+**Use for**: throwaway editors for tasks that are hard to describe — kanban, flag configs, prompt tuning
+**Concrete techniques**: native drag-and-drop (`draggable="true"` + `dragstart` / `dragover` / `drop`) with `.dragover` 2px dashed outline · 4-col kanban grid with `data-col` attribute → colored `border-top: 3px` per column · sticky column headers · filter toggle: `display: none` → `inline-block` on `.on` · live summary row that updates on drag · checkbox-based toggle switches with large click targets · dependency warning banners (`display: none` → `flex` on `.show`) · 2-col layout with sticky 320px right control panel · for prompt tuners: editable textarea left + sample-input panels right that re-render live
+**Must-haves**: **always end with an export button** — "Copy as markdown" / "Copy diff" / "Copy params" — that turns the in-UI state back into something pasteable to the next prompt or committable to the repo
+## Failure modes (anti-patterns)
+- `transition: all` — animates layout shifts and lags; use explicit property lists
+- Div-based button hacks — breaks keyboard nav; use native `<button>`
+- Unlabeled colors — every swatch and badge needs hex AND token AND role
+- Desktop-only layouts — every artifact needs at least one `@media` breakpoint
+- Hover-only critical info — invisible on touch; use `<details>` or always-visible cards
+- Static code blocks for diffs — color and structure are the point; render `.add`/`.del`/`.ctx` states
+- Walls of prose where structure would earn its weight — re-evaluate; default to markdown
+- Missing `scroll-margin-top` — anchors land under sticky headers
+- Neglected `:active` feedback — clicks feel dead without `translateY(1px)`
+- Missing keyboard nav for editors — native form controls, not div-clicks
+- Missing AUTO-GENERATED badge on agent-produced artifacts — readers deserve to know
+- Missing provenance footer — "where did these numbers come from?" should always be answerable
+- **Jargon-heavy main prose** — using `tRPC`, `fan-out`, `idempotent`, `IntersectionObserver` in the reading path makes the artifact unreadable for non-specialists. Plain-language verb + concrete object in prose; technical terms in tag chips and code blocks.
+- **Decision buried below the fold** — artifact asks the user to approve, choose, or sign off but the call-to-action lives in Milestones or Risks, not at the top. Decision-makers shouldn't have to scroll to find what they're approving.
+- **Missing alt text / aria-label on SVG and `<img>`** — diagrams and charts become invisible to screen readers, low-vision users, and search / indexing. Every visual element gets a text equivalent.
+## Template scaffolding
+**YOU MUST NOT invent HTML structure from scratch.** Reference templates are the ground truth. Reading one before writing is mandatory.
+**Template location**: `.aikit/templates/html-artifacts/` (synced from the catalog). Manifest at `.aikit/templates/html-artifacts/MANIFEST.json` maps `slug` → `category` → `file`.
+### Scaffolding protocol (agent-driven — follow exactly)
+1. **Read the manifest first**: `Read .aikit/templates/html-artifacts/MANIFEST.json`. Find the entry whose `category` matches the pattern from the playbook above and whose `slug` best matches the user's intent.
+2. **Read the matching template**: `Read .aikit/templates/html-artifacts/<file>.html` (the `file` field from the manifest entry). This is non-optional. If the file is missing, ask the user to run `aikit sync`; do not proceed without it.
+3. **Gather real project context**: run the appropriate commands — `git diff main...HEAD`, `git log --since=...`, read files mentioned in the prompt, etc. Replace the template's placeholder content with these real facts.
+4. **Prune irrelevant sections before filling**. Scan the template's `<section>` blocks; for any not required by the user's intent, OMIT them from the filled artifact entirely (don't render them with empty placeholders). Aim for the minimum sections that carry signal — keeping all sections "just in case" forces the reader to skim each one to decide whether it's relevant. Section-keep guide:
+   | Templates | Always include | Optional (only if relevant) |
+   | --- | --- | --- |
+   | `01`, `02`, `16` (Exploration & Planning) | Milestones / Approaches + Risks | Data flow §02 (only if client↔server movement) · Mockups §03 (only if UI work) · Key code §04 (only if specific patterns to highlight) |
+   | `03`, `17`, `04` (Code Review) | PR header · Per-file details · Comments | Risk map (only if multiple severities) · Module-map SVG (only for arch reviews) |
+   | `11`, `12` (Reports) | Metric band + main table | Velocity chart (only if time series) · Incident timeline (only for incidents) |
+   | `18`, `19`, `20` (Editors) | Real columns + export button | Dependency warnings (only if dependencies) |
+   | All others | Core content sections of the pattern | Any section where placeholders would carry no signal |
+5. **Preserve structure verbatim** when writing the filled artifact:
+   - All `:root` CSS variables (`--clay`, `--slate`, `--ivory`, `--oat`, `--olive`, `--gray-*`)
+   - All class names, layout grids, and microinteraction conventions
+   - All cross-cutting techniques (sticky positioning, `scroll-margin-top`, `<details>` collapsibles, native form controls)
+   - The pattern's visual language (severity colors, badge styles, dot indicators, monospace meta text)
+   - **Apply the Voice & plain-language rule** when writing prose into content nodes (`<p>`, `<h3>`, milestone bodies, risk explanations). Jargon goes in tag chips, `<code>` spans, or `<details>` — never in main prose.
+6. **Add required `<head>` elements**: `<title>`, `<meta name="description">`, and `<meta name="aikit-pattern" content="...">` with one of: `Exploration`, `Code Review`, `Design`, `Prototype`, `Illustrations`, `Deck`, `Research`, `Report`, `Editor`.
+7. **Add AUTO-GENERATED pill** top-right and **provenance footer** (`Sources: ... — generated <ISO timestamp>`).
+8. **Save** to `.aikit/artifacts/NN-<slug>.html` (increment `NN` from existing files).
+9. **Regenerate gallery index** per the protocol below.
+### User-driven scaffolding (alternative)
+When the user wants a pristine starter to look at first: `aikit scaffold html <slug>` drops the template into the current directory unmodified. Slugs match the manifest: `code-approaches`, `visual-designs`, `pr-review`, `pr-writeup`, `code-understanding`, `design-system`, `component-variants`, `animation`, `interaction`, `slide-deck`, `svg-illustrations`, `status-report`, `incident-report`, `flowchart`, `feature-explainer`, `concept-explainer`, `implementation-plan`, `triage-board`, `feature-flags`, `prompt-tuner`. Numbers (`03`) and `--list` also work.
 ## Output rules
-- Save to `.aikit/artifacts/NN-<slug>.html` where `NN` is a zero-padded sequence (`07-auth-spec.html`). This path is gitignored.
-- Determine `NN` by listing existing files in `.aikit/artifacts/` (ignore `index.html`) and incrementing the highest number; start at `01`.
-- Every artifact MUST include `<meta name="aikit-pattern" content="...">` in `<head>` with one of: `Spec`, `Code Review`, `Report`, `Prototype`, `Editor`, `Visual Explainer`, `Deck`, `Design System`. The index uses this to group entries.
-- Every artifact MUST include `<title>` and `<meta name="description">` — the index renders these.
-- Pure HTML/CSS/JS only — no external CDN dependencies, no build step.
-- Mobile-responsive: use `max-width` + `padding` on body, `<meta name="viewport">`.
-- After saving, also rewrite `.aikit/artifacts/index.html` (see below), then print both paths and suggest: `open .aikit/artifacts/index.html` (macOS) or `xdg-open` (Linux).
-## Index page (gallery)
-The index is auto-maintained. After every artifact write, regenerate `.aikit/artifacts/index.html` from scratch — do not try to surgically edit it:
-1. List `.aikit/artifacts/*.html` excluding `index.html` itself
-2. For each file, read `<title>`, `<meta name="description">`, and `<meta name="aikit-pattern">`
-3. Group entries by pattern (Spec, Code Review, Report, Prototype, Editor, Visual Explainer, Deck, Design System)
-4. Render each group as a section with cards: filename badge, title, one-line description, link to the file
-5. Reuse the built-in design system CSS so the gallery matches the artifacts
-Drop empty groups. Sort entries within a group by filename (which is by `NN`). The index itself uses `<meta name="aikit-pattern" content="Index">` so future tooling can recognize it but it is excluded from its own listing.
+- Save filled artifacts to `.aikit/artifacts/NN-<slug>.html` (`NN` zero-padded; increment from existing files; start at `01`). This path is gitignored.
+- Every artifact MUST include `<meta name="aikit-pattern" content="...">` in `<head>`. Valid values match the 9-pattern playbook: `Exploration`, `Code Review`, `Design`, `Prototype`, `Illustrations`, `Deck`, `Research`, `Report`, `Editor`. The gallery groups by this.
+- Every artifact MUST include `<title>` and `<meta name="description">` — the gallery renders these.
+- Pure HTML / CSS / JS only — no CDNs, no build step. Inline `<style>` and `<script>` blocks are fine.
+- After saving, **regenerate `.aikit/artifacts/index.html` from scratch** (see Gallery protocol below), then print both paths and suggest `open .aikit/artifacts/index.html`.
+## Gallery index protocol
+After every artifact write, rebuild `.aikit/artifacts/index.html`:
+1. List `.aikit/artifacts/*.html` excluding `index.html`.
+2. For each file read `<title>`, `<meta name="description">`, `<meta name="aikit-pattern">`.
+3. Group by pattern; drop empty groups; sort within a group by filename (`NN` order).
+4. Render each group as a section with cards: filename badge, title, one-line description, link.
+5. Reuse the cross-cutting design tokens so the gallery matches the artifacts.
+6. The gallery itself uses `<meta name="aikit-pattern" content="Index">` so future tooling can recognize it; it is excluded from its own listing.
 ## Markdown-first rule
-Existing brainstorming and planning skills stay markdown-first. Only switch to HTML when the user accepts the proactive offer or explicitly requests it (e.g. via `/html`). This preserves cross-tool compatibility.
+Existing brainstorming, debugging, and planning skills stay markdown-first. Only switch to HTML when the user accepts the proactive offer or explicitly invokes `/html`. Cross-tool compatibility depends on this.
+## Attribution
+Templates forked with permission from [github.com/ThariqS/html-effectiveness](https://github.com/ThariqS/html-effectiveness) (2026-05-12). The pattern taxonomy, sub-types, and technique inventory above are derived from the same source. Adapted for cross-tool agent scaffolding under haac-aikit's MIT license.