haac-aikit 0.11.1 → 0.12.0

package/README.md

@@ -1,66 +1,60 @@
 # haac-aikit
 
-[![npm version](https://img.shields.io/npm/v/haac-aikit.svg)](https://www.npmjs.com/package/haac-aikit)
-[![GitHub](https://img.shields.io/badge/github-Hamad--Center%2Fhaac--aikit-blue?logo=github)](https://github.com/Hamad-Center/haac-aikit)
+[![npm](https://img.shields.io/npm/v/haac-aikit.svg)](https://www.npmjs.com/package/haac-aikit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-**Docs that update themselves.** A cross-tool AI-coding kit (Claude Code, Cursor, Copilot, Windsurf, Aider, Gemini, Codex) that drops opinionated rules + skills + safety hooks into any repo. Headline feature: two new skills that maintain your project's HTML documentation and decision log as the code changes.
+One `AGENTS.md` config, seven AI coding tools see it. Plus four HTML skills that produce single-page artifacts instead of walls of markdown.
+
+Works with **Claude Code · Cursor · Copilot · Windsurf · Aider · Gemini CLI · OpenAI Codex CLI**.
+
+## Install
 
 ```bash
 npx haac-aikit
 ```
 
-## The two headline skills (v0.11)
-
-- **`/docs`** — keeps a living HTML documentation tree at `docs/` current. The agent reads only the section it needs (via marker-bounded blocks), proposes the edit in chat, writes after you confirm. Your README stops going stale.
-- **`/decide`** — generates one rich HTML tradeoff page per architectural choice, saved to `docs/decisions/YYYY-MM-DD-<slug>.html`. Options as cards, pros/cons as colored dots, technical bit explained in plain language. A permanent decision log accumulates.
+30-second wizard. Headless: `npx haac-aikit --yes --tools=claude`.
 
-Built on Thariq Shihipar's [Unreasonable Effectiveness of HTML for Claude Code](https://thariqs.github.io/html-effectiveness/) — generating HTML instead of markdown gives you scannable, interactive output. We took the insight and built the workflows that compound the longest.
-
-## What else you get
+## The four HTML skills
 
-Beyond `/docs` and `/decide`, a `standard` install drops in:
+```bash
+aikit add --html
+```
 
-- **Cross-tool rules** — one canonical `AGENTS.md`, dialect-translated per tool (proper MDC for Cursor, emphasis tokens for Claude, imperative phrasing for Aider). Stop maintaining four copies.
-- **Safety hooks** — block force-push to main, secret commits, `rm -rf`, reads of `.env*` / `.ssh*` / `.aws*`. Fires before the tool call.
-- **Rule observability** — telemetry tells you which rules fire, get violated, or are dead weight. `aikit doctor --rules` shows the buckets.
-- **Learn from PR history** — `aikit learn --limit=30` mines merged PR reviews for repeated corrections, proposes them as new rules.
-- **18 process skills + 14 agents** — TDD, brainstorming, debugging, planner, reviewer, debugger, pr-describer, more.
-- **CI templates** — gitleaks, standard CI, optional `@claude` PR responder.
+| Skill | Use it when | Output |
+|---|---|---|
+| **`/docs`** | Documenting a feature or gotcha | `docs/<name>.html` |
+| **`/decide`** | Picking between 2-4 technical options | `docs/decisions/<date>-<slug>.html` |
+| **`/directions`** | Exploring visual design variants | `docs/directions/<date>-<slug>.html` |
+| **`/roadmap`** | Handing an implementation plan to an implementer | `docs/roadmaps/<date>-<slug>.html` |
 
-Run `npx haac-aikit` for the wizard, or `npx haac-aikit --yes --tools=claude --preset=standard` for headless / CI.
+Each command writes one self-contained HTML file — no build step, no CDN, commit and share the link. Built on [Thariq Shihipar's "Unreasonable Effectiveness of HTML for Claude Code"](https://thariqs.github.io/html-effectiveness/).
 
-## How it compares
+## What else you get
 
-| | haac-aikit | rulesync | ruler | claudekit |
-|---|---|---|---|---|
-| Includes content (skills, agents, hooks) | yes | no | no | Claude-only |
-| Cross-tool (7 tools) | yes | yes | yes | no |
-| Rule observability | yes | no | no | no |
-| Dialect translation | yes | no | no | no |
-| Learn from PR history | yes | no | no | no |
-| Living HTML docs (`/docs`) + decision log (`/decide`) | yes | no | no | no |
-| Idempotent BEGIN/END markers | yes | no | `.bak` backups | no |
+- **Cross-tool fan-out.** Skills, agents, hooks, and MCP servers fan out per selected tool in its native format. Pick `--tools=cursor` and get `.cursor/rules/` + `.cursor/hooks.json` + `.cursor/mcp.json`. Pick `--tools=codex` and get `.codex/agents/*.toml` + `.codex/config.toml` with MCP servers.
+- **Safety hooks.** Blocks force-push to `main`, secret commits, `rm -rf` on sensitive paths, reads of `.ssh/` / `.aws/` / `secrets/`.
+- **Rule observability.** Telemetry tracks which rules fire, which are violated, which are dead weight. `aikit doctor --rules` shows the report.
+- **Built-in skills + agents.** 14 always-on skills (TDD, debugging, brainstorming, planning, ...) + 11 opt-in. Specialist agents for orchestration and PR description.
 
 ## Commands
 
 ```
-aikit                       interactive wizard
-aikit sync                  regenerate from .aikitrc.json
-aikit update                pull latest templates, show diff
-aikit add <item>            add a single skill / command / agent / hook
-aikit list                  show installed items + catalog
-aikit doctor [--rules]      sanity / observability check
-aikit report [--format=...] adherence summary (markdown or json)
-aikit learn --limit=30      propose rules from your PR review history
+aikit                interactive wizard
+aikit add --html     install the four HTML skills + templates
+aikit add <name>     add a single skill / agent / hook
+aikit sync           regenerate per-tool files from .aikitrc.json
+aikit doctor --rules sanity check + observability report
+aikit report         rule-adherence summary (markdown or json)
 ```
 
-## Status & links
+Full reference: `aikit --help`. Detailed audit per tool: [`AUDIT.md`](AUDIT.md).
+
+## Status
 
-**0.11.0** — holding 1.0 until at least three external teams have used the observability loop on real PRs. Expect breaking changes between minor versions until then.
+Pre-1.0. Expect breaking changes between minor versions. **0.12.0** ships with cross-tool parity for 6 of 7 tools (Aider has no native rule loader; we ship a skills index in `CONVENTIONS.md` instead). All blockers from the [pre-publish audit](audits/) have been fixed.
 
 - Site: <https://hamad-center.github.io/haac-aikit/>
-- Discussion / try-it sign-up: [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1)
-- Why we cut the old 20-template HTML skill: [the landing page](https://hamad-center.github.io/haac-aikit/) explains it — short version: developers don't browse a 20-template menu, two real workflows do 100% of the job. Recover the deleted templates with `git checkout v0.10.0 -- catalog/templates/html-artifacts/` if you want them.
+- Try / discuss: [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1)
 
 MIT. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md).

package/catalog/commands/directions.md

@@ -0,0 +1,29 @@
+Render 2-4 visual design directions on a single self-contained HTML page using the `directions` skill.
+
+## Usage
+`/directions <surface>`
+
+Examples:
+- `/directions empty state for the projects view`
+- `/directions hero section for the marketing landing`
+- `/directions dashboard card — three density options`
+
+## Steps
+
+1. **Confirm the brief** with the user before writing. Say back: *"Directions page for `<surface>` with `<N>` variants emphasizing `<axes>` (e.g. minimal · illustrated · instructional). I'll render each live on light and dark stages. Okay?"* Wait for yes.
+
+2. **Read the template** at `.aikit/templates/directions/template.html`. Copy its structure verbatim — design tokens, sticky toolbar, artboard grid, light/dark stage flip.
+
+3. **Pick variants that differ in strategy, not detail.** Each direction should have a one-word personality (`Minimal`, `Illustrated`, `Playful`, `Instructional`, `Editorial`, `Technical`). A 1px font tweak isn't a direction.
+
+4. **Render, don't describe.** Each variant's stage must contain real HTML/CSS that actually displays the design. A wall of bullet points describing the variant defeats the skill.
+
+5. **Use the user's domain language.** Real copy ("New task", "No projects yet"), not lorem ipsum.
+
+6. **Write the file** to `docs/directions/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug from the surface).
+
+7. **Report.** Print the file path and suggest `open docs/directions/YYYY-MM-DD-<slug>.html` (macOS) / `xdg-open` (Linux). One-sentence summary of what each variant emphasizes.
+
+## Fallback
+
+If `.aikit/templates/directions/template.html` is missing, run `aikit sync` first.

package/catalog/commands/roadmap.md

@@ -0,0 +1,31 @@
+Generate a thorough single-page implementation roadmap as HTML using the `roadmap` skill.
+
+## Usage
+`/roadmap <feature>`
+
+Examples:
+- `/roadmap comment threads on task cards`
+- `/roadmap migrate session store from cookies to Redis`
+- `/roadmap add real-time presence to the editor`
+
+## Steps
+
+1. **Confirm the shape** with the user before writing. Say back: *"Roadmap for `<feature>`. I'll lay out ~`<N>` milestones, a data-flow diagram, mockups of `<surfaces>`, code for the migration and the `<key piece>`, and a risk table. Anything I should change before I write?"* Wait for yes.
+
+2. **Read the template** at `.aikit/templates/roadmap/template.html`. Copy its structure verbatim — design tokens, summary strip, milestone timeline, SVG diagram pattern, mockup grid, code panel, risk table, open-questions callouts.
+
+3. **Gather concrete inputs**: real package/file names, real effort estimates, real risks. If you don't know a number, ask — don't invent one.
+
+4. **Render mockups as HTML**, not screenshots. Use the project's real domain language and component names.
+
+5. **Code blocks are illustrative.** 15-30 lines of the load-bearing logic per block (migration + the optimistic mutation, say). Don't dump entire files.
+
+6. **Every roadmap needs at least one open question.** If you genuinely can't think of one, state explicitly *why* the design is fully settled in a one-sentence aside.
+
+7. **Write the file** to `docs/roadmaps/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug from the feature).
+
+8. **Report.** Print the file path and suggest `open docs/roadmaps/YYYY-MM-DD-<slug>.html` (macOS) / `xdg-open` (Linux). One-sentence summary of milestone count, surfaces touched, and severity-high risks.
+
+## Fallback
+
+If `.aikit/templates/roadmap/template.html` is missing, run `aikit sync` first.

package/catalog/rules/AGENTS.md.tmpl

@@ -53,9 +53,9 @@ TODO: Project-specific security notes.
      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.
+- <!-- id: skills.html-artifacts --> For HTML artifact production, this kit ships four skills under `.claude/skills/`: `docs` (living project documentation tree at `docs/`), `decide` (single-page tradeoff doc under `docs/decisions/`), `directions` (2-4 live-rendered visual design variants under `docs/directions/`), and `roadmap` (single-page implementation roadmap under `docs/roadmaps/`). Each skill has a matching slash command (`/docs`, `/decide`, `/directions`, `/roadmap`) and a reference template under `.aikit/templates/<name>/`. **Read the matching template first** before writing; do not invent HTML structure from scratch.
+- <!-- id: skills.html-install --> Install or refresh just the HTML-artifact bundle (skills + commands + templates) with `aikit add --html`. Run `aikit list` to see what's already installed.
+- <!-- id: artifacts.output-path --> HTML artifacts go to `docs/<file>.html` (docs), `docs/decisions/YYYY-MM-DD-<slug>.html` (decide), `docs/directions/YYYY-MM-DD-<slug>.html` (directions), or `docs/roadmaps/YYYY-MM-DD-<slug>.html` (roadmap). All four are committed to git as a permanent log.
 
 ## Gotchas
 <!-- High-signal section. Add things the agent repeatedly gets wrong.
@@ -72,6 +72,5 @@ TODO
 Always preserve: the full list of files modified this session, any failing test names + error messages, and the current task being worked on.
 
 ## Further reading
-- `docs/claude-md-reference.md` — Anthropic 2026 reference for CLAUDE.md / memory / `.claude/rules/` (shipped by `aikit` when `claude` is selected at scope ≥ standard).
 - `.claude/rules/` — drop topic-scoped or path-scoped rule files here (see the example shipped with this kit). Path-scoped rules load only when Claude reads matching files, saving context.
 <!-- END:haac-aikit -->

package/catalog/rules/aikit-rules.json

@@ -1,36 +1,22 @@
 {
   "$schema": "https://raw.githubusercontent.com/Hamad-Center/haac-aikit/main/schema/aikit-rules.schema.json",
   "version": 1,
-  "comment": "Maps rule IDs (in AGENTS.md / .claude/rules/*.md) to machine-checkable patterns. The PostToolUse hook reads this to detect violations in just-written files. Pattern-checkable rules are a SUBSET of all rules — many rules can only be observed (loaded/cited) but not auto-validated. Add your own; remove what you don't want.",
+  "comment": "Maps rule IDs (in AGENTS.md / .claude/rules/*.md) to machine-checkable patterns. The PostToolUse hook reads this to detect violations in just-written files. The rules below are a starter set — language-agnostic safety patterns + a TypeScript example to copy. Add patterns for your stack and delete what you don't need.",
   "rules": [
+    {
+      "id": "security.no-hardcoded-secrets",
+      "title": "No hardcoded API keys, tokens, or passwords",
+      "pattern": "(?i)(api[_-]?key|secret|token|password|access[_-]?key)\\s*[:=]\\s*['\"][A-Za-z0-9_\\-]{16,}['\"]",
+      "fileGlobs": ["**/*"],
+      "exclude": ["**/*.test.*", "**/*.spec.*", "**/fixtures/**", "**/__mocks__/**", "**/node_modules/**"],
+      "severity": "error"
+    },
     {
       "id": "code-style.no-console-log",
-      "title": "No console.log in production code",
+      "title": "Example: no console.log in production code (TypeScript / JavaScript)",
       "pattern": "(?<!//\\s)console\\.log\\(",
       "fileGlobs": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx"],
-      "exclude": ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"],
-      "severity": "warn"
-    },
-    {
-      "id": "code-style.no-default-export",
-      "title": "Use named exports, not default",
-      "pattern": "^\\s*export\\s+default\\b",
-      "fileGlobs": ["src/**/*.ts", "src/**/*.tsx"],
-      "severity": "warn"
-    },
-    {
-      "id": "code-style.no-any",
-      "title": "Use unknown + type guards, not any",
-      "pattern": ":\\s*any\\b|<any>|as\\s+any\\b",
-      "fileGlobs": ["src/**/*.ts", "src/**/*.tsx"],
-      "exclude": ["**/*.d.ts"],
-      "severity": "warn"
-    },
-    {
-      "id": "code-style.no-ts-ignore-without-comment",
-      "title": "@ts-ignore must include a reason",
-      "pattern": "@ts-ignore(?!\\s*[—:-])",
-      "fileGlobs": ["src/**/*.ts", "src/**/*.tsx"],
+      "exclude": ["**/*.test.*", "**/*.spec.*"],
       "severity": "warn"
     }
   ]

package/catalog/skills/tier1/directions.md

@@ -0,0 +1,72 @@
+---
+name: directions
+description: Use when the user is exploring visual options for a UI surface and wants 2-4 design directions rendered side-by-side on a single self-contained HTML page they can scan, A/B compare on light/dark, and commit to the project's exploration log. Generates one HTML file per exploration under `docs/directions/YYYY-MM-DD-<slug>.html`. Opt-in only — do not invoke without user request.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+
+Explicit invocation only: `/directions <surface>`, "use the directions skill", "show me design directions for X", "explore visual options for the empty state / hero / dashboard card".
+
+Do **not** invoke proactively. This is divergent-exploration tooling — the user picks the moment they want options laid out. Silent generation creates noise and surprise files.
+
+## What this skill is for (and what it isn't)
+
+- **It is for**: rendering 2-4 visual *takes* on the same surface side by side so a human can pick by looking, not by reading.
+- **It isn't for**: choosing between technical options (use `/decide`), writing a sequenced build plan (use `/roadmap`), or producing a finished design system page (use `/docs`).
+
+The output is one HTML page; each variant is rendered live on its own "stage". The user picks one, mixes traits, or asks for round two.
+
+## Structure of a directions page
+
+Every page has the same five blocks. Order is load-bearing — first paint must let the reader see the variants without scrolling past explanations.
+
+1. **Sticky toolbar** — light/dark toggle (and optional density/locale toggles). Variants must hold up on both surfaces; the toggle is how reviewers check.
+2. **Page header** — eyebrow + h1 + a `prompt-box` echoing the user's original ask, so the page carries its own provenance.
+3. **Artboard grid (2-4 cards)** — one card per variant. Each card has:
+   - A monospace tag (e.g. `A — Minimal`, `B — Illustrated`).
+   - A `stage` element with the variant rendered live (real HTML/CSS, not screenshots, not descriptions).
+   - A one-paragraph `rationale` below the stage: what this direction emphasizes and when it's the right choice.
+4. **Comparison row (optional)** — small chip grid or table summarizing the dimensions that matter (density, tone, motion, accessibility load).
+5. **Pick guidance** — a short closing aside: "Pick A if X, pick B if Y. Mix A's typography with C's illustration if you want Z."
+
+## Output
+
+- Path: `docs/directions/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug from the surface name).
+- Template: `.aikit/templates/directions/template.html` — read first, copy structure verbatim, fill placeholders.
+- Self-contained: pure HTML/CSS/JS, no CDNs, no build step.
+- Committed to git (permanent exploration log — round two often references round one).
+
+## Variant rules (non-negotiable)
+
+- **Render, don't describe.** Each variant must actually display — typography, colors, layout, motion if relevant. A wall of bullet points describing the variant defeats the point of the skill.
+- **Theme-aware.** Variants use CSS custom properties scoped under `.stage`; `.stage.dark` flips the theme tokens. The toolbar's light/dark toggle just swaps a class.
+- **Real content, not lorem.** Use the user's domain language ("New task", "Inbox empty", "No projects yet") so the comparison is meaningful.
+- **2-4 variants.** Three is the sweet spot. One isn't an exploration; five becomes a catalog.
+- **Each variant gets a one-word personality.** `Minimal`, `Illustrated`, `Playful`, `Instructional`, `Editorial`, `Technical`. The personality tag is the shortcut a reviewer uses to talk about it.
+
+## Voice rule for rationale paragraphs
+
+- One sentence on what the direction emphasizes.
+- One sentence on when it's the right choice (the user persona or context it serves).
+- Optionally one sentence on its tradeoff.
+- Plain-language verbs, concrete objects. *"A small spot illustration anchors the eye and explains the object model"* beats *"Leverages illustration to communicate information architecture"*.
+
+## A11y baseline (every directions page)
+
+- `<title>`, exactly one `<h1>`, heading hierarchy never skips levels.
+- Landmark roles: `<main>` for the artboard grid, the toolbar is a sticky `<nav>` or unstyled `<div>` with explicit `role` only if needed.
+- Color contrast ≥ 4.5:1 for body text on both light and dark surfaces — design tokens already meet this; don't override per-variant.
+- Inline SVG illustrations get `aria-hidden="true"` if purely decorative; meaningful diagrams get `<title>` + `aria-labelledby`.
+- The light/dark toggle uses native radio inputs (already in the template) — don't replace with custom toggles that break keyboard navigation.
+
+## Anti-patterns
+
+- **Describing variants instead of rendering them.** This is the single most common failure. If a variant is "a card with a softer feel", that's a description — write the CSS that makes it softer and show it.
+- **More than 4 variants.** Past four, the page becomes hard to scan and impossible to mentally diff. Pre-narrow.
+- **Variants that are too similar.** A 1px font-size change isn't a direction; it's a tweak. Each direction should differ in *strategy* (typography-led, illustration-led, motion-led, density-led, etc.).
+- **Silent generation.** Opt-in only. Wait for explicit `/directions`.
+- **Skipping the date in the filename.** The directions log sorts chronologically; round-two filenames reference round-one slugs.
+- **CDN dependencies.** The page must render offline. No `<link rel="stylesheet" href="https://...">`, no remote fonts (system stacks only).

package/catalog/skills/tier1/roadmap.md

@@ -0,0 +1,71 @@
+---
+name: roadmap
+description: Use when the user has agreed on what to build and now wants a thorough, skimmable single-page implementation artifact — milestones, data-flow diagram, mockups, key code snippets, risks, and open questions — to hand to an implementer or a reviewer. Generates one HTML file per feature under `docs/roadmaps/YYYY-MM-DD-<slug>.html`. Opt-in only — do not invoke without user request. This is the visual artifact for hand-off; for AI-executable text plans use `writing-plans`.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+
+Explicit invocation only: `/roadmap <feature>`, "use the roadmap skill", "draw up a roadmap for X", "I want a one-page implementation doc for the new comments feature".
+
+Do **not** invoke proactively. Roadmaps are committed artifacts — they go in git and get referenced in PRs. Surprise generation creates noise.
+
+## Roadmap vs. adjacent skills
+
+- **Use `/decide`** when you're picking *which* approach (option A vs B vs C). `/roadmap` assumes the approach is settled.
+- **Use `/directions`** when you're exploring *visual* options. `/roadmap` is structural and engineering-facing.
+- **Use `writing-plans`** when you want a text plan an AI agent will execute step by step. `/roadmap` is for humans — implementers reading on a phone, reviewers skimming on a Monday.
+- **Use `/docs`** when the feature is already built and you're recording how it works for the team. `/roadmap` is forward-looking; `/docs` is backward-looking.
+
+## Structure of a roadmap page
+
+Every page has the same six sections. Order matters: a phone reader scans top-to-bottom and should know the shape by the time they reach milestones.
+
+1. **Header + prompt-box** — eyebrow + h1 + a `prompt-box` echoing the user's original ask, so the page carries its own provenance.
+2. **Summary strip (4 cells)** — at-a-glance: `Effort` (e.g. `~2 weeks`), `Surfaces touched` (e.g. `3 packages`), one concrete unit (e.g. `New tables: 2`), and feature-flag/ramp identifier. These are the numbers a manager will quote in standup.
+3. **Milestones** — vertical timeline with 3-5 slices. Each slice has a *when* (Week 1 · Mon–Tue), a dot (`done` filled, future hollow), a title, a one-paragraph description, and tag chips for packages/surfaces touched. Slices should be independently reviewable.
+4. **Data flow** — inline SVG diagram. Boxes are components/services; arrows are calls; solid lines = request path, dashed clay = realtime/async/fan-out. Always include a one-line caption distinguishing the two.
+5. **Mockups (2 panels)** — two mock cards in a 2-up grid showing the *most ambiguous surfaces* (the comment thread + the digest, the editor + the toast, etc.). Render as real HTML, not screenshots. These exist to lock down nesting, placement, and copy — not pixel-final.
+6. **Key code** — two side-by-side code blocks for *the two pieces most likely to be done wrong* (e.g. the migration and the optimistic mutation). Syntax-highlighted via classed spans (`.kw`, `.str`, `.cm`, `.fn`). Don't dump entire files; show the load-bearing 15-30 lines.
+7. **Risks & mitigations table** — three columns (Risk · Severity · Mitigation). Severity chips: `HIGH` clay-pink, `MED` oat, `LOW` olive-pale. Three rows max for v1; more becomes noise.
+8. **Open questions** — clay-bordered callouts. Each: question title, one-paragraph context, owner line (`Decide with · design, before slice 2`). These force the document to admit what's unsettled.
+
+## Output
+
+- Path: `docs/roadmaps/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug from the feature).
+- Template: `.aikit/templates/roadmap/template.html` — read first, copy structure verbatim, fill placeholders.
+- Self-contained: pure HTML/CSS/SVG, no CDNs, no build step.
+- Committed to git (permanent implementation record).
+
+## Content rules (non-negotiable)
+
+- **Concrete numbers, not vibes.** "~2 weeks" beats "moderate effort". "3 packages" beats "a few surfaces". If you don't have a number, ask the user — don't invent one.
+- **Real package and file names** in tags and labels. `packages/db`, `apps/web`, `migration 0042`. Generic labels like `frontend` and `backend` are anti-signal.
+- **Real risks, not platitudes.** "Realtime duplicate when socket append races the HTTP response" is a risk. "Things might be slow" is not. If you can't write the mitigation in one sentence, the risk isn't sharp enough.
+- **Open questions are required.** Every non-trivial feature has at least one unsettled point. A roadmap with zero open questions is hiding something — flag it.
+- **Code blocks are illustrative, not complete.** 15-30 lines of the load-bearing logic. Use ellipsis or comments for omitted boilerplate; the reader is a senior engineer, not a copy-paste consumer.
+
+## Voice rule
+
+- Plain-language verbs + concrete objects in body prose. *"Ship in four slices, each independently reviewable, each behind the flag"* beats *"Leverage a phased rollout strategy"*.
+- Jargon lives in `<code>` chips or table cells, never in main body prose.
+- Section intros are one sentence. The point of the artifact is the *content*, not the prose explaining the content.
+
+## A11y baseline
+
+- `<title>`, exactly one `<h1>`, heading hierarchy never skips levels.
+- Each section gets `<section>` with an `aria-labelledby` linking to its heading.
+- Inline SVG diagrams get `<title>` + `<desc>` and `aria-labelledby`; the caption underneath also describes the diagram in prose for screen readers.
+- Severity chips have text content (`HIGH`, `MED`, `LOW`), not just color — color is reinforcement, never the only signal.
+- Color contrast ≥ 4.5:1 — design tokens already meet this; don't override.
+
+## Anti-patterns
+
+- **One giant milestone.** If your timeline has a single 3-week slice, the artifact has no shape. Split into 3-5 reviewable pieces.
+- **Mockups that are screenshots.** Render as HTML. Screenshots rot the moment a class name changes; HTML mocks update with the design system.
+- **Code dumps.** A roadmap with 200 lines of code in one block is a draft PR, not a roadmap. Show only the parts most likely to be done wrong.
+- **Risk table with HIGH for everything.** Severity loses meaning. If three risks are HIGH, the project shouldn't ship in the proposed shape — escalate instead.
+- **Zero open questions.** No real feature has zero ambiguity. If the answer is genuinely "nothing unsettled", state that explicitly with one sentence on why ("All API contracts already exist; this is purely UI assembly").
+- **Silent generation.** Opt-in only. Wait for explicit `/roadmap`.

package/catalog/templates/decide/template.html

@@ -22,6 +22,19 @@
   --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
   --sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
 }
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --ivory: #1a1714;
+    --slate: #FAF9F5;
+    --oat: #2a241e;
+    --gray-150: #211d18;
+    --gray-300: #3a3530;
+    --gray-500: #8a8682;
+    --gray-700: #c8c4be;
+    --white: #211d18;
+  }
+}
 * { box-sizing: border-box; }
 body {
   margin: 0;