haac-aikit 0.11.0 → 0.11.1
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.
- package/README.md +31 -79
- package/catalog/release-notes.json +14 -0
- package/dist/cli.mjs +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,89 +4,31 @@
|
|
|
4
4
|
[](https://github.com/Hamad-Center/haac-aikit)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## Quickstart
|
|
7
|
+
**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.
|
|
10
8
|
|
|
11
9
|
```bash
|
|
12
10
|
npx haac-aikit
|
|
13
11
|
```
|
|
14
12
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
For CI or scripts:
|
|
18
|
-
|
|
19
|
-
```bash
|
|
20
|
-
npx haac-aikit --yes --tools=claude,cursor,copilot --preset=standard
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
## What you get
|
|
24
|
-
|
|
25
|
-
### Minimal scope
|
|
26
|
-
|
|
27
|
-
| File | Purpose |
|
|
28
|
-
|---|---|
|
|
29
|
-
| `AGENTS.md` | Canonical rules — your edits outside BEGIN/END markers are never touched |
|
|
30
|
-
| `CLAUDE.md` | Five-line shim that imports `@AGENTS.md` |
|
|
31
|
-
| `.cursor/rules/000-base.mdc` | Dialect-translated MDC (not a generic copy) |
|
|
32
|
-
| Per-tool shims | Copilot, Gemini, Windsurf, Aider |
|
|
33
|
-
| `.mcp.json` | MCP stub: filesystem, memory, fetch |
|
|
34
|
-
| `.claude/settings.json` | Hardened permissions: deny list for secrets and destructive commands |
|
|
35
|
-
|
|
36
|
-
### Standard scope adds
|
|
37
|
-
|
|
38
|
-
- **18 process skills** in `.claude/skills/` — TDD, brainstorming, debugging, git workflows, and more. Bodies load on demand, ~100 tokens at rest.
|
|
39
|
-
- **14 agents** in `.claude/agents/` — planner, reviewer, debugger, pr-describer, and more.
|
|
40
|
-
- **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.
|
|
41
|
-
- **Rule observability hooks** — logs which rules load and which get violated, feeds `aikit doctor --rules`.
|
|
42
|
-
- **`/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.
|
|
43
|
-
- **`/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.
|
|
44
|
-
- CI workflows: gitleaks, standard CI, optional `@claude` PR responder.
|
|
45
|
-
|
|
46
|
-
### Everything scope adds
|
|
47
|
-
|
|
48
|
-
Dev container, OTel exporter, plugin wrapper, auto-sync CI, shape-specific agents (frontend / backend / mobile).
|
|
49
|
-
|
|
50
|
-
## What makes it different
|
|
13
|
+
## The two headline skills (v0.11)
|
|
51
14
|
|
|
52
|
-
|
|
15
|
+
- **`/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.
|
|
16
|
+
- **`/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.
|
|
53
17
|
|
|
54
|
-
|
|
18
|
+
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.
|
|
55
19
|
|
|
56
|
-
|
|
20
|
+
## What else you get
|
|
57
21
|
|
|
58
|
-
|
|
22
|
+
Beyond `/docs` and `/decide`, a `standard` install drops in:
|
|
59
23
|
|
|
60
|
-
|
|
24
|
+
- **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.
|
|
25
|
+
- **Safety hooks** — block force-push to main, secret commits, `rm -rf`, reads of `.env*` / `.ssh*` / `.aws*`. Fires before the tool call.
|
|
26
|
+
- **Rule observability** — telemetry tells you which rules fire, get violated, or are dead weight. `aikit doctor --rules` shows the buckets.
|
|
27
|
+
- **Learn from PR history** — `aikit learn --limit=30` mines merged PR reviews for repeated corrections, proposes them as new rules.
|
|
28
|
+
- **18 process skills + 14 agents** — TDD, brainstorming, debugging, planner, reviewer, debugger, pr-describer, more.
|
|
29
|
+
- **CI templates** — gitleaks, standard CI, optional `@claude` PR responder.
|
|
61
30
|
|
|
62
|
-
|
|
63
|
-
- **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.
|
|
64
|
-
- **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.
|
|
65
|
-
|
|
66
|
-
So `/html` got split into two focused skills:
|
|
67
|
-
|
|
68
|
-
- **`/docs`** — always-on, ~80-line skill, one starter HTML template. Maintains an HTML doc tree at `docs/` with section-bounded surgical updates.
|
|
69
|
-
- **`/decide`** — opt-in tier2, ~50-line skill, one rich tradeoff template. Each call writes a new dated file under `docs/decisions/`.
|
|
70
|
-
|
|
71
|
-
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.**
|
|
72
|
-
|
|
73
|
-
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.
|
|
74
|
-
|
|
75
|
-
## Commands
|
|
76
|
-
|
|
77
|
-
```
|
|
78
|
-
aikit interactive wizard
|
|
79
|
-
aikit sync regenerate from .aikitrc.json (idempotent)
|
|
80
|
-
aikit update pull latest templates, show diff, prompt
|
|
81
|
-
aikit diff show drift between current state and a fresh sync
|
|
82
|
-
aikit add <item> add a single skill, command, agent, or hook
|
|
83
|
-
aikit list show installed items + catalog availability
|
|
84
|
-
aikit doctor schema, triggers, broken-link checks
|
|
85
|
-
aikit doctor --rules rule observability buckets
|
|
86
|
-
aikit report Markdown adherence summary
|
|
87
|
-
aikit report --format=json same data, structured for CI
|
|
88
|
-
aikit learn --limit=30 propose rules from your PR review history
|
|
89
|
-
```
|
|
31
|
+
Run `npx haac-aikit` for the wizard, or `npx haac-aikit --yes --tools=claude --preset=standard` for headless / CI.
|
|
90
32
|
|
|
91
33
|
## How it compares
|
|
92
34
|
|
|
@@ -97,18 +39,28 @@ aikit learn --limit=30 propose rules from your PR review history
|
|
|
97
39
|
| Rule observability | yes | no | no | no |
|
|
98
40
|
| Dialect translation | yes | no | no | no |
|
|
99
41
|
| Learn from PR history | yes | no | no | no |
|
|
42
|
+
| Living HTML docs (`/docs`) + decision log (`/decide`) | yes | no | no | no |
|
|
100
43
|
| Idempotent BEGIN/END markers | yes | no | `.bak` backups | no |
|
|
101
44
|
|
|
102
|
-
##
|
|
103
|
-
|
|
104
|
-
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.
|
|
45
|
+
## Commands
|
|
105
46
|
|
|
106
|
-
|
|
47
|
+
```
|
|
48
|
+
aikit interactive wizard
|
|
49
|
+
aikit sync regenerate from .aikitrc.json
|
|
50
|
+
aikit update pull latest templates, show diff
|
|
51
|
+
aikit add <item> add a single skill / command / agent / hook
|
|
52
|
+
aikit list show installed items + catalog
|
|
53
|
+
aikit doctor [--rules] sanity / observability check
|
|
54
|
+
aikit report [--format=...] adherence summary (markdown or json)
|
|
55
|
+
aikit learn --limit=30 propose rules from your PR review history
|
|
56
|
+
```
|
|
107
57
|
|
|
108
|
-
##
|
|
58
|
+
## Status & links
|
|
109
59
|
|
|
110
|
-
|
|
60
|
+
**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.
|
|
111
61
|
|
|
112
|
-
|
|
62
|
+
- Site: <https://hamad-center.github.io/haac-aikit/>
|
|
63
|
+
- Discussion / try-it sign-up: [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1)
|
|
64
|
+
- 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.
|
|
113
65
|
|
|
114
66
|
MIT. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md).
|
|
@@ -1,6 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"version": 1,
|
|
3
3
|
"releases": [
|
|
4
|
+
{
|
|
5
|
+
"version": "0.11.1",
|
|
6
|
+
"date": "2026-05-13",
|
|
7
|
+
"headline": "Docs-only patch: punchier landing + trimmed README",
|
|
8
|
+
"highlights": [
|
|
9
|
+
"Landing: new hero \"Docs that update themselves\" + without/with comparison block",
|
|
10
|
+
"Landing: Thariq Shihipar's HTML article elevated to a pull-quote attribution",
|
|
11
|
+
"README: 114 → 66 lines, /docs + /decide pulled to top as headline feature",
|
|
12
|
+
"No code changes — same surface as 0.11.0"
|
|
13
|
+
],
|
|
14
|
+
"links": {
|
|
15
|
+
"changelog": "https://github.com/Hamad-Center/haac-aikit/blob/main/CHANGELOG.md#0111---2026-05-13"
|
|
16
|
+
}
|
|
17
|
+
},
|
|
4
18
|
{
|
|
5
19
|
"version": "0.11.0",
|
|
6
20
|
"date": "2026-05-13",
|
package/dist/cli.mjs
CHANGED
package/package.json
CHANGED