haac-aikit 0.8.1 → 0.8.3

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 (5) hide show
  1. package/catalog/commands/html.md +8 -5
  2. package/catalog/skills/tier1/html-artifacts.md +36 -7
  3. package/dist/cli.mjs +3 -3
  4. package/dist/cli.mjs.map +1 -1
  5. package/package.json +1 -1
package/catalog/commands/html.md CHANGED
@@ -10,17 +10,20 @@ Generate an HTML artifact for the current context using the html-artifacts skill
10
10
  - If called with no args: infer intent from the current conversation — what task is in progress, what was just discussed, what files are open.
11
11
 
12
12
  2. **Pick the use-case pattern**
13
- Using the `html-artifacts` skill, identify which of the five patterns fits:
14
- Spec/Planning, Code Review, Report/Research, Prototype, or Custom Editor.
13
+ Using the `html-artifacts` skill, identify which of the eight patterns fits:
14
+ Spec/Planning, Code Review, Report/Research, Prototype, Custom Editor, Visual Explainer, Deck, or Design System.
15
15
 
16
16
  3. **Generate the artifact**
17
17
  - Apply the built-in design system CSS tokens
18
18
  - If `docs/aikit-html-design-system.html` exists in the project, read it first and inherit its CSS variable values
19
19
  - Follow the structure guidance for the chosen pattern
20
20
  - Pure HTML/CSS/JS only — no external CDN dependencies
21
+ - Include in `<head>`: `<title>`, `<meta name="description" content="...">`, and `<meta name="aikit-pattern" content="...">` (the pattern name from step 2) — required for the index
21
22
 
22
23
  4. **Save and report**
23
24
  - Determine a short slug from the intent (e.g. `code-review-auth-pr`, `weekly-report`)
24
- - Save to `.aikit/artifacts/<slug>-<timestamp>.html`
25
- - Print the full path
26
- - Suggest opening: `open <path>` (macOS) / `xdg-open <path>` (Linux)
25
+ - Determine `NN` by listing existing files in `.aikit/artifacts/` (excluding `index.html`) and incrementing the highest number; start at `01`
26
+ - Save to `.aikit/artifacts/NN-<slug>.html` (e.g. `07-code-review-auth-pr.html`)
27
+ - Regenerate `.aikit/artifacts/index.html` per the "Index page (gallery)" section of the `html-artifacts` skill
28
+ - Print both paths
29
+ - Suggest opening: `open .aikit/artifacts/index.html` (macOS) / `xdg-open .aikit/artifacts/index.html` (Linux)
package/catalog/skills/tier1/html-artifacts.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: html-artifacts
3
- description: Use when generating output that would benefit from rich formatting — specs, plans, reports, code review explainers, design prototypes, or custom editors. Teaches when to proactively offer HTML instead of markdown and how to structure each artifact type.
4
- version: "1.0.0"
3
+ 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).
4
+ version: "1.1.0"
5
5
  source: haac-aikit
6
6
  license: MIT
7
7
  ---
@@ -19,7 +19,7 @@ When conditions above are met but the user didn't explicitly ask for HTML, say o
19
19
 
20
20
  Wait for a yes/no. If yes, proceed with HTML. If no, use markdown.
21
21
 
22
- ## Five use-case patterns
22
+ ## Use-case patterns
23
23
 
24
24
  ### 1. Spec / Planning
25
25
  **Trigger:** Long spec, multiple options to compare
@@ -46,6 +46,21 @@ Wait for a yes/no. If yes, proceed with HTML. If no, use markdown.
46
46
  **Structure:** Drag/sort or form UI, constraint warnings, "copy as JSON/prompt" export button
47
47
  **Don't:** Let the editor be the only output — always export
48
48
 
49
+ ### 6. Visual Explainer
50
+ **Trigger:** Explaining a concept, system, or workflow where a diagram beats prose
51
+ **Structure:** One hero inline `<svg>` with labelled regions, short text blocks anchored to those regions, "view source" toggle that reveals the underlying data
52
+ **Don't:** Use raster images or external icon CDNs — keep SVG inline so the artifact stays self-contained and editable
53
+
54
+ ### 7. Deck
55
+ **Trigger:** Slide presentation, talk preview, pitch, "walk me through this"
56
+ **Structure:** One slide per viewport (`100vh`), large body type (≥32px), arrow-key navigation, single idea per slide, speaker notes hidden behind a key press
57
+ **Don't:** Generate scrolling content — if the user would scroll, it's a Report, not a Deck
58
+
59
+ ### 8. Design System
60
+ **Trigger:** Building or documenting a design system, component library reference, token palette
61
+ **Structure:** Live component samples beside their source HTML/CSS, swatches for color/spacing/type tokens, copy-on-click for each token value
62
+ **Don't:** Use screenshots of components — the components on the page must be the real, live HTML
63
+
49
64
  ## Built-in design system
50
65
 
51
66
  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.
@@ -71,10 +86,24 @@ Inject this CSS block into every artifact. If the project has `docs/aikit-html-d
71
86
  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`.
72
87
 
73
88
  ## Output rules
74
- - Save to `.aikit/artifacts/<slug>-<timestamp>.html` (this path is gitignored)
75
- - After saving, print the path and suggest: `open <path>` (macOS) or `xdg-open <path>` (Linux)
76
- - Pure HTML/CSS/JS only — no external CDN dependencies, no build step
77
- - Mobile-responsive: use `max-width` + `padding` on body, `<meta name="viewport">`
89
+ - Save to `.aikit/artifacts/NN-<slug>.html` where `NN` is a zero-padded sequence (`07-auth-spec.html`). This path is gitignored.
90
+ - Determine `NN` by listing existing files in `.aikit/artifacts/` (ignore `index.html`) and incrementing the highest number; start at `01`.
91
+ - 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.
92
+ - Every artifact MUST include `<title>` and `<meta name="description">` — the index renders these.
93
+ - Pure HTML/CSS/JS only — no external CDN dependencies, no build step.
94
+ - Mobile-responsive: use `max-width` + `padding` on body, `<meta name="viewport">`.
95
+ - 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).
96
+
97
+ ## Index page (gallery)
98
+ The index is auto-maintained. After every artifact write, regenerate `.aikit/artifacts/index.html` from scratch — do not try to surgically edit it:
99
+
100
+ 1. List `.aikit/artifacts/*.html` excluding `index.html` itself
101
+ 2. For each file, read `<title>`, `<meta name="description">`, and `<meta name="aikit-pattern">`
102
+ 3. Group entries by pattern (Spec, Code Review, Report, Prototype, Editor, Visual Explainer, Deck, Design System)
103
+ 4. Render each group as a section with cards: filename badge, title, one-line description, link to the file
104
+ 5. Reuse the built-in design system CSS so the gallery matches the artifacts
105
+
106
+ 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.
78
107
 
79
108
  ## Markdown-first rule
80
109
  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.
package/dist/cli.mjs CHANGED
@@ -3407,7 +3407,7 @@ FLAGS
3407
3407
  --no-color Disable ANSI colours
3408
3408
  --config=<path> Use a specific .aikitrc.json location
3409
3409
  --tools=<list> Comma-separated tool list (claude,cursor,copilot,...)
3410
- --preset=<scope> minimal | standard | everything
3410
+ --scope=<scope> minimal | standard | everything (--preset is an alias)
3411
3411
  --rules (with doctor) Show rule-observability buckets
3412
3412
  --format=<fmt> (with report / doctor --rules) markdown | json
3413
3413
  --since=<date> (with report) Restrict events to after this ISO date
@@ -3418,8 +3418,8 @@ FLAGS
3418
3418
  async function main() {
3419
3419
  const argv = lib_default(process.argv.slice(2), {
3420
3420
  boolean: ["yes", "dry-run", "force", "skip-git-check", "no-color", "help", "version", "rules"],
3421
- string: ["config", "tools", "preset", "format", "since", "limit"],
3422
- alias: { y: "yes", h: "help", v: "version" },
3421
+ string: ["config", "tools", "preset", "scope", "format", "since", "limit"],
3422
+ alias: { y: "yes", h: "help", v: "version", scope: "preset" },
3423
3423
  default: {
3424
3424
  yes: false,
3425
3425
  "dry-run": false,