haac-aikit 0.11.0 → 0.12.0

package/README.md

@@ -1,114 +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)
 
-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.
+One `AGENTS.md` config, seven AI coding tools see it. Plus four HTML skills that produce single-page artifacts instead of walls of markdown.
 
-## Quickstart
+Works with **Claude Code · Cursor · Copilot · Windsurf · Aider · Gemini CLI · OpenAI Codex CLI**.
+
+## Install
 
 ```bash
 npx haac-aikit
 ```
 
-30-second wizard, writes a `.aikitrc.json` you can commit. Re-run anytime with `aikit sync`.
+30-second wizard. Headless: `npx haac-aikit --yes --tools=claude`.
 
-For CI or scripts:
+## The four HTML skills
 
 ```bash
-npx haac-aikit --yes --tools=claude,cursor,copilot --preset=standard
+aikit add --html
 ```
 
-## What you get
-
-### Minimal scope
-
-| File | Purpose |
-|---|---|
-| `AGENTS.md` | Canonical rules — your edits outside BEGIN/END markers are never touched |
-| `CLAUDE.md` | Five-line shim that imports `@AGENTS.md` |
-| `.cursor/rules/000-base.mdc` | Dialect-translated MDC (not a generic copy) |
-| Per-tool shims | Copilot, Gemini, Windsurf, Aider |
-| `.mcp.json` | MCP stub: filesystem, memory, fetch |
-| `.claude/settings.json` | Hardened permissions: deny list for secrets and destructive commands |
-
-### Standard scope adds
-
-- **18 process skills** in `.claude/skills/` — TDD, brainstorming, debugging, git workflows, and more. Bodies load on demand, ~100 tokens at rest.
-- **14 agents** in `.claude/agents/` — planner, reviewer, debugger, pr-describer, and more.
-- **Safety hooks** — blocks force-push to main, secret commits, `rm -rf`, reads of `.env*` / `.ssh*` / `.aws*`. Fires before the tool call, doesn't rely on the model cooperating.
-- **Rule observability hooks** — logs which rules load and which get violated, feeds `aikit doctor --rules`.
-- **`/docs` skill** — keeps a small HTML documentation tree at `docs/` current. Section-bounded updates so the agent reads/edits one block, not the whole file.
-- **`/decide` skill (opt-in)** — generates one rich HTML tradeoff page per decision under `docs/decisions/`. Plain-language pros/cons, recommended option marked, written so a non-engineer stakeholder can scan it.
-- CI workflows: gitleaks, standard CI, optional `@claude` PR responder.
-
-### Everything scope adds
-
-Dev container, OTel exporter, plugin wrapper, auto-sync CI, shape-specific agents (frontend / backend / mobile).
-
-## What makes it different
-
-**Rule observability.** Telemetry hooks tell you which rules fire, which get violated, and which are dead weight. `aikit doctor --rules` shows the buckets; `aikit report` formats them for a PR comment. → [docs/observability.md](docs/observability.md)
-
-**Dialect translation.** One canonical `AGENTS.md`, reformatted per tool — proper MDC frontmatter for Cursor, emphasis tokens for Claude, imperative phrasing for Aider. You stop maintaining four copies of the same rules. → [docs/dialects.md](docs/dialects.md)
+| 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` |
 
-**Learn from your PR history.** `aikit learn --limit=30` mines merged PR review comments for repeated corrections and proposes them as new rules. No ML — just regex, a stopword list, and Jaccard similarity. → [docs/learn.md](docs/learn.md)
+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/).
 
-## Why the HTML side stays small (one starter, not 20 templates)
+## What else you get
 
-An earlier version of this kit shipped 20 HTML templates — PR reviews, slide decks, design systems, prototype animations, feature-flag editors, prompt tuners. Beautiful catalog. **We deleted it.** Here's the honest reason:
-
-- **Developers don't browse a 20-template catalog.** They open the skill, see the wall of patterns, scroll past it, and write whatever HTML they were going to write anyway. Most of those templates were never reached for in practice. A library nobody borrows from is just shelves.
-- **A 205-line always-on skill is expensive to keep around.** Every agent invocation paid for that context, even when the user wasn't generating HTML at all. We were taxing every conversation to support a rare action.
-- **Two real jobs, not twenty edge cases.** When we asked what people actually needed HTML for, two patterns kept surfacing: (1) **living project docs** they could share for handover, and (2) **tradeoff pages** when there's a decision to make. Everything else was a curated showcase, not a tool.
-
-So `/html` got split into two focused skills:
-
-- **`/docs`** — always-on, ~80-line skill, one starter HTML template. Maintains an HTML doc tree at `docs/` with section-bounded surgical updates.
-- **`/decide`** — opt-in tier2, ~50-line skill, one rich tradeoff template. Each call writes a new dated file under `docs/decisions/`.
-
-Both lean on the marker engine for section-level reads/writes (HTML stays cheap because the agent never reloads the whole file). The skill files together are smaller than the old single skill alone. **Less to read, less to maintain, more actual usage.**
-
-If you want the deleted templates back, fork the previous release (`git checkout v0.10.0 -- catalog/templates/html-artifacts/`) — they're forks of [github.com/ThariqS/html-effectiveness](https://github.com/ThariqS/html-effectiveness) and still useful as reference material.
+- **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 (idempotent)
-aikit update                  pull latest templates, show diff, prompt
-aikit diff                    show drift between current state and a fresh sync
-aikit add <item>              add a single skill, command, agent, or hook
-aikit list                    show installed items + catalog availability
-aikit doctor                  schema, triggers, broken-link checks
-aikit doctor --rules          rule observability buckets
-aikit report                  Markdown adherence summary
-aikit report --format=json    same data, structured for CI
-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)
 ```
 
-## How it compares
-
-| | 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 |
-| Idempotent BEGIN/END markers | yes | no | `.bak` backups | no |
+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. Until then, expect breaking changes between minor versions.
-
-Looking for teams to try it — feedback shapes 1.0. Comment on [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1).
-
-## Contributing
-
-Issues and PRs welcome at [github.com/Hamad-Center/haac-aikit](https://github.com/Hamad-Center/haac-aikit).
+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.
 
-## License
+- Site: <https://hamad-center.github.io/haac-aikit/>
+- 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;