@softspark/ai-toolkit 3.0.0 → 3.0.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/CHANGELOG.md +12 -0
- package/README.md +10 -3
- package/app/.claude-plugin/plugin.json +1 -1
- package/kb/procedures/release-preparation-sop.md +14 -5
- package/kb/procedures/release-verification-sop.md +112 -8
- package/kb/reference/supported-tools-registry.md +7 -7
- package/llms-full.txt +133 -20
- package/manifest.json +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,18 @@ Versioning follows [Semantic Versioning](https://semver.org/).
|
|
|
7
7
|
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
+
## v3.0.1 — Release SOP Deep-Coverage Checks (2026-04-24)
|
|
11
|
+
|
|
12
|
+
Doc-only patch. No code, generators, or runtime behavior changed.
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
|
|
16
|
+
- **`kb/procedures/release-verification-sop.md` 1.3.0 -> 1.4.0** — added Phase 9 (six new checks for v3.0.0 native surfaces: `--profile full` emission, `--codex-skills` orthogonality, breaking-change surfaces at `standard`, install idempotence, live JSON parse, registry/generator drift). Refreshed stale thresholds (`Tests >= 350` -> `Tests >= 900`, `e.g., 669` -> `e.g., 945`). Editor list updated from 8 to 11 (+codex, +gemini, +opencode). Added HOME-scoped write safety warning.
|
|
17
|
+
- **`kb/procedures/release-preparation-sop.md` 1.9.0 -> 1.10.0** — added the registry-vs-generators drift check to Phase 5 so a bad registry can never escape into a release.
|
|
18
|
+
- **`kb/reference/supported-tools-registry.md` 1.1.0 -> 1.2.0** — enumerated the 11 new v3.0.0 generators (cursor_hooks/agents, windsurf_hooks, gemini_hooks/commands/skills, augment_hooks/agents/commands/skills, codex_skills) with profile and opt-in annotations.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
10
22
|
## v3.0.0 — Deep Coverage: Full Native Surface Utilization (2026-04-23)
|
|
11
23
|
|
|
12
24
|
Skips `2.13.0`. Upgrade path is `2.12.x` -> `3.0.0`.
|
package/README.md
CHANGED
|
@@ -10,15 +10,22 @@
|
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
## What's New in v3.0.
|
|
13
|
+
## What's New in v3.0.1
|
|
14
|
+
|
|
15
|
+
**3.0.1 is a doc-only patch** that tightens the release SOPs. No code or generator changes. The v3.0.0 feature set below is still what you get when you upgrade from 2.x.
|
|
16
|
+
|
|
17
|
+
- Release Verification SOP gains **Phase 9: Deep-Coverage Checks** — six automated assertions for the v3.0.0 native surfaces (`--profile full` emission, `--codex-skills` orthogonality, breaking-change surfaces on `standard`, install idempotence, live JSON parse, registry/generator drift) plus refreshed thresholds and a HOME-scoped-write safety warning.
|
|
18
|
+
- Release Preparation SOP now runs the registry-vs-generators drift check in Phase 5 so a misaligned `supported-tools-registry.md` can't escape into a release.
|
|
19
|
+
|
|
20
|
+
### Carried from v3.0.0 (feature release)
|
|
14
21
|
|
|
15
22
|
- **Deep coverage: every editor at 100% of its native surface.** New generators emit hooks, sub-agents, custom commands, and skill pointers per editor: `generate_cursor_agents.py`, `generate_cursor_hooks.py`, `generate_windsurf_hooks.py`, `generate_gemini_commands.py`, `generate_gemini_hooks.py`, `generate_gemini_skills.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`, `generate_augment_skills.py`, `generate_codex_skills.py`.
|
|
16
23
|
- **`--profile full`** turns on every native surface across all supported editors in one flag. `minimal` / `standard` / `strict` retain prior semantics but `standard` now also wires Gemini hooks and the Copilot directory layout (see Breaking Changes).
|
|
17
24
|
- **Opt-in Codex skill mirroring** via `--codex-skills`. Codex gets the full skill catalog materialized under `.agents/skills/`; other editors stay on pointer-skill or compat-read.
|
|
18
|
-
- **58 new bats tests** covering native surface generators
|
|
25
|
+
- **58 new bats tests** covering native surface generators plus per-editor suites for aider, antigravity, augment, claude-code, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf.
|
|
19
26
|
- **Skill quality pass** (folded in from the 2.12 work that is now skipped): 62 skills upgraded to 4-5 / 5 on the meta-architect audit; `add_gotcha` added as a fifth mutation strategy.
|
|
20
27
|
|
|
21
|
-
### Breaking changes
|
|
28
|
+
### Breaking changes (from 3.0.0)
|
|
22
29
|
|
|
23
30
|
- `--profile standard` now installs **Gemini hooks** automatically. To opt out, use `--profile minimal` or pass `--skip gemini-hooks`.
|
|
24
31
|
- Copilot now uses the **directory layout** (`.github/copilot/`) instead of a single monolithic file. Existing single-file installs are preserved but new installs emit the directory form.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ai-toolkit",
|
|
3
3
|
"description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
|
|
4
|
-
"version": "3.0.
|
|
4
|
+
"version": "3.0.1",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "SoftSpark",
|
|
7
7
|
"url": "https://github.com/softspark"
|
|
@@ -3,10 +3,10 @@ title: "SOP: Release Preparation"
|
|
|
3
3
|
category: procedures
|
|
4
4
|
service: ai-toolkit
|
|
5
5
|
tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem]
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.10.0"
|
|
7
7
|
created: "2026-04-10"
|
|
8
|
-
last_updated: "2026-04-
|
|
9
|
-
description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0,
|
|
8
|
+
last_updated: "2026-04-24"
|
|
9
|
+
description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, and the registry-vs-generators drift gate added in v1.10.0."
|
|
10
10
|
---
|
|
11
11
|
|
|
12
12
|
# SOP: Release Preparation
|
|
@@ -278,7 +278,15 @@ python3 scripts/audit_skills.py --ci
|
|
|
278
278
|
python3 scripts/audit_skills.py --sarif > audit.sarif # MANDATORY — GHAS ingest
|
|
279
279
|
python3 scripts/audit_skills.py --permissions # review Bash/Write/Edit footprint
|
|
280
280
|
|
|
281
|
-
#
|
|
281
|
+
# Registry / generator drift (added in 1.10.0). Meta-generators excluded.
|
|
282
|
+
META="generate_agents_md.py|generate_llms_txt.py"
|
|
283
|
+
diff \
|
|
284
|
+
<(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
|
|
285
|
+
<(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
|
|
286
|
+
&& echo "OK: registry matches filesystem" \
|
|
287
|
+
|| { echo "DRIFT: update supported-tools-registry.md before tagging"; exit 1; }
|
|
288
|
+
|
|
289
|
+
# Run npm test ONCE, cache output, parse from file. The suite is 900+ bats
|
|
282
290
|
# cases — rerunning it per check wastes minutes. Do not pipe npm test into
|
|
283
291
|
# tail/grep multiple times in the same session.
|
|
284
292
|
npm test > /tmp/npm-test.log 2>&1
|
|
@@ -291,11 +299,12 @@ echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp
|
|
|
291
299
|
- `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
|
|
292
300
|
- `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
|
|
293
301
|
- `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
|
|
302
|
+
- Registry drift: `OK: registry matches filesystem`. If `DRIFT:` appears, add the missing `scripts/generate_*.py` rows to `kb/reference/supported-tools-registry.md` before tagging.
|
|
294
303
|
- `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
|
|
295
304
|
|
|
296
305
|
**One-liner:**
|
|
297
306
|
```bash
|
|
298
|
-
python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && npm test
|
|
307
|
+
python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py' | sort -u) && npm test
|
|
299
308
|
```
|
|
300
309
|
|
|
301
310
|
**If tests fail:** Fix the issue, do NOT skip. Common failures:
|
|
@@ -3,10 +3,10 @@ title: "SOP: Release Verification"
|
|
|
3
3
|
category: procedures
|
|
4
4
|
service: ai-toolkit
|
|
5
5
|
tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.4.0"
|
|
7
7
|
created: "2026-04-08"
|
|
8
|
-
last_updated: "2026-04-
|
|
9
|
-
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0
|
|
8
|
+
last_updated: "2026-04-24"
|
|
9
|
+
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds."
|
|
10
10
|
---
|
|
11
11
|
|
|
12
12
|
# SOP: Release Verification
|
|
@@ -52,6 +52,10 @@ python3 scripts/audit_skills.py --ci # 10. Security audit
|
|
|
52
52
|
python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')" # 11. SARIF 2.1.0 well-formed?
|
|
53
53
|
python3 scripts/audit_skills.py --permissions | head -30 # 12. Broad-access skills reviewed?
|
|
54
54
|
npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')" # 13. Provenance attested on npm?
|
|
55
|
+
|
|
56
|
+
# Deep-coverage verification (Phase 9, v3.0.0+)
|
|
57
|
+
META="generate_agents_md.py|generate_llms_txt.py"
|
|
58
|
+
diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches" # 14. Registry <-> generators drift?
|
|
55
59
|
```
|
|
56
60
|
|
|
57
61
|
---
|
|
@@ -117,8 +121,8 @@ ai-toolkit status
|
|
|
117
121
|
```
|
|
118
122
|
|
|
119
123
|
**Verify `--dry-run`:**
|
|
120
|
-
- [ ] Agents >=
|
|
121
|
-
- [ ] Skills >=
|
|
124
|
+
- [ ] Agents >= 44
|
|
125
|
+
- [ ] Skills >= 99
|
|
122
126
|
- [ ] Hooks merged into settings.json
|
|
123
127
|
- [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
|
|
124
128
|
|
|
@@ -168,7 +172,7 @@ cd - && rm -rf /tmp/ai-toolkit-verify
|
|
|
168
172
|
- [ ] Would create: CLAUDE.md
|
|
169
173
|
- [ ] Would create: .claude/settings.local.json
|
|
170
174
|
- [ ] Would inject: .claude/constitution.md
|
|
171
|
-
- [ ] Editors: all
|
|
175
|
+
- [ ] Editors: all 11 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity, codex, gemini, opencode)
|
|
172
176
|
- [ ] Would generate configs for each editor (legacy + directory-based)
|
|
173
177
|
- [ ] Would install: .git/hooks/pre-commit
|
|
174
178
|
- [ ] Would inject language rules (auto-detected)
|
|
@@ -189,7 +193,7 @@ python3 scripts/audit_skills.py --ci
|
|
|
189
193
|
```
|
|
190
194
|
|
|
191
195
|
**Verify validate.py:**
|
|
192
|
-
- [ ] Agents >=
|
|
196
|
+
- [ ] Agents >= 44, Skills >= 99, Tests >= 900
|
|
193
197
|
- [ ] Hook events: 12, Hook scripts: >= 20
|
|
194
198
|
- [ ] Plugin packs >= 10, KB documents >= 20
|
|
195
199
|
- [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
|
|
@@ -217,7 +221,7 @@ echo "exit: $exit"
|
|
|
217
221
|
|
|
218
222
|
**Verify:**
|
|
219
223
|
- [ ] `exit == 0`
|
|
220
|
-
- [ ] `ok == expected test count` (e.g.,
|
|
224
|
+
- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
|
|
221
225
|
- [ ] `not ok == 0`
|
|
222
226
|
- [ ] Bats runs tests in parallel (4 jobs)
|
|
223
227
|
- [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
|
|
@@ -322,6 +326,101 @@ AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
|
|
|
322
326
|
|
|
323
327
|
---
|
|
324
328
|
|
|
329
|
+
## Phase 9: Deep-Coverage Checks (v3.0.0+)
|
|
330
|
+
|
|
331
|
+
These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.
|
|
332
|
+
|
|
333
|
+
> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.
|
|
334
|
+
|
|
335
|
+
### 9.1 `--profile full` emits every native surface
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
339
|
+
ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
|
|
340
|
+
--profile full --codex-skills --dry-run 2>&1 \
|
|
341
|
+
| grep -E "\\.cursor/(hooks\\.json|agents)|\\.windsurf/hooks\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/skills"
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
**Verify** — at least the following lines appear:
|
|
345
|
+
- [ ] `.cursor/hooks.json` and `.cursor/agents/`
|
|
346
|
+
- [ ] `.windsurf/hooks.json`
|
|
347
|
+
- [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
|
|
348
|
+
- [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
|
|
349
|
+
- [ ] `.codex/skills/` (opt-in via `--codex-skills`)
|
|
350
|
+
|
|
351
|
+
### 9.2 `--codex-skills` is orthogonal to `--profile`
|
|
352
|
+
|
|
353
|
+
```bash
|
|
354
|
+
D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
355
|
+
ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
|
|
356
|
+
| grep -q "Would generate: .codex/skills" && echo "OK: --codex-skills works without --profile full"
|
|
357
|
+
ai-toolkit install --local --editors codex --profile full --dry-run 2>&1 \
|
|
358
|
+
| grep -q "Would generate: .codex/skills" && echo "FAIL: --profile full should NOT auto-emit .codex/skills" \
|
|
359
|
+
|| echo "OK: --profile full alone does not auto-emit .codex/skills (correct — opt-in only)"
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
**Verify:**
|
|
363
|
+
- [ ] `--codex-skills` emits `.codex/skills/` at any profile
|
|
364
|
+
- [ ] `--profile full` alone does NOT emit `.codex/skills/` (must be opt-in)
|
|
365
|
+
|
|
366
|
+
### 9.3 Breaking-change surfaces land on `--profile standard`
|
|
367
|
+
|
|
368
|
+
v3.0.0 moved two surfaces from opt-in to default:
|
|
369
|
+
- Copilot directory layout (`.github/instructions/`, `.github/prompts/`)
|
|
370
|
+
- Gemini hooks (`.gemini/settings.json`)
|
|
371
|
+
|
|
372
|
+
```bash
|
|
373
|
+
D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
374
|
+
ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
|
|
375
|
+
| tee /tmp/aitk-breaking.log
|
|
376
|
+
grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
|
|
377
|
+
grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
**Verify both lines print `OK:`**. If either is missing, a regression has unwound the v3.0.0 breaking change.
|
|
381
|
+
|
|
382
|
+
### 9.4 Install is idempotent
|
|
383
|
+
|
|
384
|
+
```bash
|
|
385
|
+
D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
386
|
+
ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
|
|
387
|
+
SHA1=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
|
|
388
|
+
ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
|
|
389
|
+
SHA2=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
|
|
390
|
+
[ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
**Verify:** prints `OK: idempotent`. A second run must produce byte-identical files in every managed path.
|
|
394
|
+
|
|
395
|
+
### 9.5 Live-install JSON outputs parse
|
|
396
|
+
|
|
397
|
+
The bats suite validates JSON shape at generation time. This re-checks that what actually landed on disk after a live install parses without errors.
|
|
398
|
+
|
|
399
|
+
```bash
|
|
400
|
+
D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
401
|
+
ai-toolkit install --local --editors cursor,windsurf,gemini,augment --profile full >/dev/null 2>&1
|
|
402
|
+
for f in .cursor/hooks.json .windsurf/hooks.json .gemini/settings.json $HOME/.augment/settings.json; do
|
|
403
|
+
[ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
|
|
404
|
+
done
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
**Verify:** each emitted file prints `OK: <path>`. Any `json.decoder.JSONDecodeError` means the merge logic corrupted the output.
|
|
408
|
+
|
|
409
|
+
### 9.6 Registry / generator drift check
|
|
410
|
+
|
|
411
|
+
`kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.
|
|
412
|
+
|
|
413
|
+
```bash
|
|
414
|
+
META="generate_agents_md.py|generate_llms_txt.py"
|
|
415
|
+
REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
|
|
416
|
+
FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
|
|
417
|
+
diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
**Verify:** prints `OK: registry matches filesystem`. If not, add the missing rows to the registry before tagging the next release.
|
|
421
|
+
|
|
422
|
+
---
|
|
423
|
+
|
|
325
424
|
## Troubleshooting
|
|
326
425
|
|
|
327
426
|
### `ai-toolkit: command not found`
|
|
@@ -376,3 +475,8 @@ ai-toolkit eject /tmp/test # retry
|
|
|
376
475
|
| Tests | `npm test`: N/N passed, 0 failures |
|
|
377
476
|
| Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
|
|
378
477
|
| Guards | Destructive commands blocked |
|
|
478
|
+
| Deep coverage | `--profile full` emits all 9 v3.0.0 native surfaces; `--codex-skills` works orthogonally |
|
|
479
|
+
| Breaking changes | Copilot directory layout + Gemini hooks emit at `--profile standard` (v3.0.0 contract) |
|
|
480
|
+
| Idempotence | Second `install` run produces byte-identical output in every managed path |
|
|
481
|
+
| Live JSON | Every generated `.json` file on disk parses as valid JSON |
|
|
482
|
+
| Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |
|
|
@@ -3,9 +3,9 @@ title: "Supported Tools Registry"
|
|
|
3
3
|
category: reference
|
|
4
4
|
service: ai-toolkit
|
|
5
5
|
tags: [editors, platforms, generators, integration, ecosystem]
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.2.0"
|
|
7
7
|
created: "2026-04-23"
|
|
8
|
-
last_updated: "2026-04-
|
|
8
|
+
last_updated: "2026-04-24"
|
|
9
9
|
description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
|
|
10
10
|
---
|
|
11
11
|
|
|
@@ -49,7 +49,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
49
49
|
| Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
|
|
50
50
|
| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json`, `~/.cursor/hooks.json` |
|
|
51
51
|
| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.codex/skills/`, `.codex/agents/` (Cursor cross-reads these so ai-toolkit's Claude install works automatically) |
|
|
52
|
-
| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py` |
|
|
52
|
+
| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full), `scripts/generate_cursor_agents.py` (profile=full) |
|
|
53
53
|
| Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
|
|
54
54
|
|
|
55
55
|
### Windsurf
|
|
@@ -62,7 +62,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
62
62
|
| Stable docs mirror | https://docs.windsurf.com/llms.txt + per-page .md twins |
|
|
63
63
|
| Config paths | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/mcp_config.json` |
|
|
64
64
|
| Compat read paths | `.agents/skills/`, `~/.agents/skills/`, (with Claude Code config-reading) `.claude/skills/`, `~/.claude/skills/` |
|
|
65
|
-
| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py` |
|
|
65
|
+
| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full) |
|
|
66
66
|
| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, MCP, memories, hooks |
|
|
67
67
|
| Activation modes emitted | always_on (agents/security/quality), glob (testing + language rules), model_decision (code-style/workflow) |
|
|
68
68
|
|
|
@@ -86,7 +86,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
86
86
|
| Docs | https://github.com/google-gemini/gemini-cli/tree/main/docs |
|
|
87
87
|
| Release notes | https://github.com/google-gemini/gemini-cli/releases |
|
|
88
88
|
| Config paths | `GEMINI.md`, `.gemini/settings.json`, `~/.gemini/settings.json`, `.gemini/commands/*.toml`, `.gemini/skills/*/SKILL.md`, `.agents/skills/*/SKILL.md`, `.gemini/extensions/gemini-extension.json` |
|
|
89
|
-
| Our generators | `scripts/generate_gemini.py` |
|
|
89
|
+
| Our generators | `scripts/generate_gemini.py`, `scripts/generate_gemini_hooks.py` (profile>=standard), `scripts/generate_gemini_commands.py` (profile=full), `scripts/generate_gemini_skills.py` (profile=full) |
|
|
90
90
|
| Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `SessionStart`, `SessionEnd`, `Stop`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` |
|
|
91
91
|
| Version probe | `gemini --version` |
|
|
92
92
|
| Latest upstream | v0.39.0 (2026-04-23) |
|
|
@@ -136,7 +136,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
136
136
|
| Docs | https://docs.augmentcode.com |
|
|
137
137
|
| Changelog | https://www.augmentcode.com/changelog |
|
|
138
138
|
| Config paths | `.augment/rules/*.md`, `.augment/guidelines.md` (legacy), `.augment/agents/*.md`, `.augment/commands/*.md`, `.augment/skills/*/SKILL.md`, `~/.augment/rules/*.md`, `~/.augment/settings.json`, `/etc/augment/settings.json` |
|
|
139
|
-
| Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py` |
|
|
139
|
+
| Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py`, `scripts/generate_augment_agents.py` (profile=full), `scripts/generate_augment_commands.py` (profile=full), `scripts/generate_augment_hooks.py` (profile=full, HOME-scoped), `scripts/generate_augment_skills.py` (profile=full) |
|
|
140
140
|
| Tracked capabilities | `.augment`, Agent mode, Next Edit, MCP, context engine, Auggie CLI, `always_apply`, `agent_requested`, subagents, custom commands, `SKILL.md`, `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `Stop`, ACP Mode |
|
|
141
141
|
| SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
|
|
142
142
|
|
|
@@ -160,7 +160,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
160
160
|
| Docs | https://github.com/openai/codex (redirects from developers.openai.com/codex) |
|
|
161
161
|
| Release notes | https://github.com/openai/codex/releases |
|
|
162
162
|
| Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.codex/hooks.json`, `.codex/skills/*/SKILL.md`, `~/.codex/config.toml` |
|
|
163
|
-
| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py` |
|
|
163
|
+
| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
|
|
164
164
|
| Tracked hook events | `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`, `PermissionRequest` (6 events supported upstream in `config.toml`) |
|
|
165
165
|
| Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
|
|
166
166
|
| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.codex/skills/*/SKILL.md` (native discovery, not auto-emitted by ai-toolkit yet) |
|
package/llms-full.txt
CHANGED
|
@@ -4242,10 +4242,10 @@ title: "SOP: Release Preparation"
|
|
|
4242
4242
|
category: procedures
|
|
4243
4243
|
service: ai-toolkit
|
|
4244
4244
|
tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem]
|
|
4245
|
-
version: "1.
|
|
4245
|
+
version: "1.10.0"
|
|
4246
4246
|
created: "2026-04-10"
|
|
4247
|
-
last_updated: "2026-04-
|
|
4248
|
-
description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0,
|
|
4247
|
+
last_updated: "2026-04-24"
|
|
4248
|
+
description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, and the registry-vs-generators drift gate added in v1.10.0."
|
|
4249
4249
|
---
|
|
4250
4250
|
|
|
4251
4251
|
# SOP: Release Preparation
|
|
@@ -4517,7 +4517,15 @@ python3 scripts/audit_skills.py --ci
|
|
|
4517
4517
|
python3 scripts/audit_skills.py --sarif > audit.sarif # MANDATORY — GHAS ingest
|
|
4518
4518
|
python3 scripts/audit_skills.py --permissions # review Bash/Write/Edit footprint
|
|
4519
4519
|
|
|
4520
|
-
#
|
|
4520
|
+
# Registry / generator drift (added in 1.10.0). Meta-generators excluded.
|
|
4521
|
+
META="generate_agents_md.py|generate_llms_txt.py"
|
|
4522
|
+
diff \
|
|
4523
|
+
<(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
|
|
4524
|
+
<(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
|
|
4525
|
+
&& echo "OK: registry matches filesystem" \
|
|
4526
|
+
|| { echo "DRIFT: update supported-tools-registry.md before tagging"; exit 1; }
|
|
4527
|
+
|
|
4528
|
+
# Run npm test ONCE, cache output, parse from file. The suite is 900+ bats
|
|
4521
4529
|
# cases — rerunning it per check wastes minutes. Do not pipe npm test into
|
|
4522
4530
|
# tail/grep multiple times in the same session.
|
|
4523
4531
|
npm test > /tmp/npm-test.log 2>&1
|
|
@@ -4530,11 +4538,12 @@ echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp
|
|
|
4530
4538
|
- `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
|
|
4531
4539
|
- `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
|
|
4532
4540
|
- `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
|
|
4541
|
+
- Registry drift: `OK: registry matches filesystem`. If `DRIFT:` appears, add the missing `scripts/generate_*.py` rows to `kb/reference/supported-tools-registry.md` before tagging.
|
|
4533
4542
|
- `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
|
|
4534
4543
|
|
|
4535
4544
|
**One-liner:**
|
|
4536
4545
|
```bash
|
|
4537
|
-
python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && npm test
|
|
4546
|
+
python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py' | sort -u) && npm test
|
|
4538
4547
|
```
|
|
4539
4548
|
|
|
4540
4549
|
**If tests fail:** Fix the issue, do NOT skip. Common failures:
|
|
@@ -4678,10 +4687,10 @@ title: "SOP: Release Verification"
|
|
|
4678
4687
|
category: procedures
|
|
4679
4688
|
service: ai-toolkit
|
|
4680
4689
|
tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
|
|
4681
|
-
version: "1.
|
|
4690
|
+
version: "1.4.0"
|
|
4682
4691
|
created: "2026-04-08"
|
|
4683
|
-
last_updated: "2026-04-
|
|
4684
|
-
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0
|
|
4692
|
+
last_updated: "2026-04-24"
|
|
4693
|
+
description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds."
|
|
4685
4694
|
---
|
|
4686
4695
|
|
|
4687
4696
|
# SOP: Release Verification
|
|
@@ -4727,6 +4736,10 @@ python3 scripts/audit_skills.py --ci # 10. Security audit
|
|
|
4727
4736
|
python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')" # 11. SARIF 2.1.0 well-formed?
|
|
4728
4737
|
python3 scripts/audit_skills.py --permissions | head -30 # 12. Broad-access skills reviewed?
|
|
4729
4738
|
npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')" # 13. Provenance attested on npm?
|
|
4739
|
+
|
|
4740
|
+
# Deep-coverage verification (Phase 9, v3.0.0+)
|
|
4741
|
+
META="generate_agents_md.py|generate_llms_txt.py"
|
|
4742
|
+
diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches" # 14. Registry <-> generators drift?
|
|
4730
4743
|
```
|
|
4731
4744
|
|
|
4732
4745
|
---
|
|
@@ -4792,8 +4805,8 @@ ai-toolkit status
|
|
|
4792
4805
|
```
|
|
4793
4806
|
|
|
4794
4807
|
**Verify `--dry-run`:**
|
|
4795
|
-
- [ ] Agents >=
|
|
4796
|
-
- [ ] Skills >=
|
|
4808
|
+
- [ ] Agents >= 44
|
|
4809
|
+
- [ ] Skills >= 99
|
|
4797
4810
|
- [ ] Hooks merged into settings.json
|
|
4798
4811
|
- [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
|
|
4799
4812
|
|
|
@@ -4843,7 +4856,7 @@ cd - && rm -rf /tmp/ai-toolkit-verify
|
|
|
4843
4856
|
- [ ] Would create: CLAUDE.md
|
|
4844
4857
|
- [ ] Would create: .claude/settings.local.json
|
|
4845
4858
|
- [ ] Would inject: .claude/constitution.md
|
|
4846
|
-
- [ ] Editors: all
|
|
4859
|
+
- [ ] Editors: all 11 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity, codex, gemini, opencode)
|
|
4847
4860
|
- [ ] Would generate configs for each editor (legacy + directory-based)
|
|
4848
4861
|
- [ ] Would install: .git/hooks/pre-commit
|
|
4849
4862
|
- [ ] Would inject language rules (auto-detected)
|
|
@@ -4864,7 +4877,7 @@ python3 scripts/audit_skills.py --ci
|
|
|
4864
4877
|
```
|
|
4865
4878
|
|
|
4866
4879
|
**Verify validate.py:**
|
|
4867
|
-
- [ ] Agents >=
|
|
4880
|
+
- [ ] Agents >= 44, Skills >= 99, Tests >= 900
|
|
4868
4881
|
- [ ] Hook events: 12, Hook scripts: >= 20
|
|
4869
4882
|
- [ ] Plugin packs >= 10, KB documents >= 20
|
|
4870
4883
|
- [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
|
|
@@ -4892,7 +4905,7 @@ echo "exit: $exit"
|
|
|
4892
4905
|
|
|
4893
4906
|
**Verify:**
|
|
4894
4907
|
- [ ] `exit == 0`
|
|
4895
|
-
- [ ] `ok == expected test count` (e.g.,
|
|
4908
|
+
- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
|
|
4896
4909
|
- [ ] `not ok == 0`
|
|
4897
4910
|
- [ ] Bats runs tests in parallel (4 jobs)
|
|
4898
4911
|
- [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
|
|
@@ -4997,6 +5010,101 @@ AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
|
|
|
4997
5010
|
|
|
4998
5011
|
---
|
|
4999
5012
|
|
|
5013
|
+
## Phase 9: Deep-Coverage Checks (v3.0.0+)
|
|
5014
|
+
|
|
5015
|
+
These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.
|
|
5016
|
+
|
|
5017
|
+
> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.
|
|
5018
|
+
|
|
5019
|
+
### 9.1 `--profile full` emits every native surface
|
|
5020
|
+
|
|
5021
|
+
```bash
|
|
5022
|
+
D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
5023
|
+
ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
|
|
5024
|
+
--profile full --codex-skills --dry-run 2>&1 \
|
|
5025
|
+
| grep -E "\\.cursor/(hooks\\.json|agents)|\\.windsurf/hooks\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/skills"
|
|
5026
|
+
```
|
|
5027
|
+
|
|
5028
|
+
**Verify** — at least the following lines appear:
|
|
5029
|
+
- [ ] `.cursor/hooks.json` and `.cursor/agents/`
|
|
5030
|
+
- [ ] `.windsurf/hooks.json`
|
|
5031
|
+
- [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
|
|
5032
|
+
- [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
|
|
5033
|
+
- [ ] `.codex/skills/` (opt-in via `--codex-skills`)
|
|
5034
|
+
|
|
5035
|
+
### 9.2 `--codex-skills` is orthogonal to `--profile`
|
|
5036
|
+
|
|
5037
|
+
```bash
|
|
5038
|
+
D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
5039
|
+
ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
|
|
5040
|
+
| grep -q "Would generate: .codex/skills" && echo "OK: --codex-skills works without --profile full"
|
|
5041
|
+
ai-toolkit install --local --editors codex --profile full --dry-run 2>&1 \
|
|
5042
|
+
| grep -q "Would generate: .codex/skills" && echo "FAIL: --profile full should NOT auto-emit .codex/skills" \
|
|
5043
|
+
|| echo "OK: --profile full alone does not auto-emit .codex/skills (correct — opt-in only)"
|
|
5044
|
+
```
|
|
5045
|
+
|
|
5046
|
+
**Verify:**
|
|
5047
|
+
- [ ] `--codex-skills` emits `.codex/skills/` at any profile
|
|
5048
|
+
- [ ] `--profile full` alone does NOT emit `.codex/skills/` (must be opt-in)
|
|
5049
|
+
|
|
5050
|
+
### 9.3 Breaking-change surfaces land on `--profile standard`
|
|
5051
|
+
|
|
5052
|
+
v3.0.0 moved two surfaces from opt-in to default:
|
|
5053
|
+
- Copilot directory layout (`.github/instructions/`, `.github/prompts/`)
|
|
5054
|
+
- Gemini hooks (`.gemini/settings.json`)
|
|
5055
|
+
|
|
5056
|
+
```bash
|
|
5057
|
+
D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
5058
|
+
ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
|
|
5059
|
+
| tee /tmp/aitk-breaking.log
|
|
5060
|
+
grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
|
|
5061
|
+
grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
|
|
5062
|
+
```
|
|
5063
|
+
|
|
5064
|
+
**Verify both lines print `OK:`**. If either is missing, a regression has unwound the v3.0.0 breaking change.
|
|
5065
|
+
|
|
5066
|
+
### 9.4 Install is idempotent
|
|
5067
|
+
|
|
5068
|
+
```bash
|
|
5069
|
+
D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
5070
|
+
ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
|
|
5071
|
+
SHA1=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
|
|
5072
|
+
ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
|
|
5073
|
+
SHA2=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
|
|
5074
|
+
[ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
|
|
5075
|
+
```
|
|
5076
|
+
|
|
5077
|
+
**Verify:** prints `OK: idempotent`. A second run must produce byte-identical files in every managed path.
|
|
5078
|
+
|
|
5079
|
+
### 9.5 Live-install JSON outputs parse
|
|
5080
|
+
|
|
5081
|
+
The bats suite validates JSON shape at generation time. This re-checks that what actually landed on disk after a live install parses without errors.
|
|
5082
|
+
|
|
5083
|
+
```bash
|
|
5084
|
+
D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
|
|
5085
|
+
ai-toolkit install --local --editors cursor,windsurf,gemini,augment --profile full >/dev/null 2>&1
|
|
5086
|
+
for f in .cursor/hooks.json .windsurf/hooks.json .gemini/settings.json $HOME/.augment/settings.json; do
|
|
5087
|
+
[ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
|
|
5088
|
+
done
|
|
5089
|
+
```
|
|
5090
|
+
|
|
5091
|
+
**Verify:** each emitted file prints `OK: <path>`. Any `json.decoder.JSONDecodeError` means the merge logic corrupted the output.
|
|
5092
|
+
|
|
5093
|
+
### 9.6 Registry / generator drift check
|
|
5094
|
+
|
|
5095
|
+
`kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.
|
|
5096
|
+
|
|
5097
|
+
```bash
|
|
5098
|
+
META="generate_agents_md.py|generate_llms_txt.py"
|
|
5099
|
+
REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
|
|
5100
|
+
FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
|
|
5101
|
+
diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"
|
|
5102
|
+
```
|
|
5103
|
+
|
|
5104
|
+
**Verify:** prints `OK: registry matches filesystem`. If not, add the missing rows to the registry before tagging the next release.
|
|
5105
|
+
|
|
5106
|
+
---
|
|
5107
|
+
|
|
5000
5108
|
## Troubleshooting
|
|
5001
5109
|
|
|
5002
5110
|
### `ai-toolkit: command not found`
|
|
@@ -5051,6 +5159,11 @@ ai-toolkit eject /tmp/test # retry
|
|
|
5051
5159
|
| Tests | `npm test`: N/N passed, 0 failures |
|
|
5052
5160
|
| Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
|
|
5053
5161
|
| Guards | Destructive commands blocked |
|
|
5162
|
+
| Deep coverage | `--profile full` emits all 9 v3.0.0 native surfaces; `--codex-skills` works orthogonally |
|
|
5163
|
+
| Breaking changes | Copilot directory layout + Gemini hooks emit at `--profile standard` (v3.0.0 contract) |
|
|
5164
|
+
| Idempotence | Second `install` run produces byte-identical output in every managed path |
|
|
5165
|
+
| Live JSON | Every generated `.json` file on disk parses as valid JSON |
|
|
5166
|
+
| Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |
|
|
5054
5167
|
|
|
5055
5168
|
---
|
|
5056
5169
|
|
|
@@ -10687,9 +10800,9 @@ title: "Supported Tools Registry"
|
|
|
10687
10800
|
category: reference
|
|
10688
10801
|
service: ai-toolkit
|
|
10689
10802
|
tags: [editors, platforms, generators, integration, ecosystem]
|
|
10690
|
-
version: "1.
|
|
10803
|
+
version: "1.2.0"
|
|
10691
10804
|
created: "2026-04-23"
|
|
10692
|
-
last_updated: "2026-04-
|
|
10805
|
+
last_updated: "2026-04-24"
|
|
10693
10806
|
description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
|
|
10694
10807
|
---
|
|
10695
10808
|
|
|
@@ -10733,7 +10846,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
10733
10846
|
| Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
|
|
10734
10847
|
| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json`, `~/.cursor/hooks.json` |
|
|
10735
10848
|
| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.codex/skills/`, `.codex/agents/` (Cursor cross-reads these so ai-toolkit's Claude install works automatically) |
|
|
10736
|
-
| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py` |
|
|
10849
|
+
| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full), `scripts/generate_cursor_agents.py` (profile=full) |
|
|
10737
10850
|
| Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
|
|
10738
10851
|
|
|
10739
10852
|
### Windsurf
|
|
@@ -10746,7 +10859,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
10746
10859
|
| Stable docs mirror | https://docs.windsurf.com/llms.txt + per-page .md twins |
|
|
10747
10860
|
| Config paths | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/mcp_config.json` |
|
|
10748
10861
|
| Compat read paths | `.agents/skills/`, `~/.agents/skills/`, (with Claude Code config-reading) `.claude/skills/`, `~/.claude/skills/` |
|
|
10749
|
-
| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py` |
|
|
10862
|
+
| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full) |
|
|
10750
10863
|
| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, MCP, memories, hooks |
|
|
10751
10864
|
| Activation modes emitted | always_on (agents/security/quality), glob (testing + language rules), model_decision (code-style/workflow) |
|
|
10752
10865
|
|
|
@@ -10770,7 +10883,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
10770
10883
|
| Docs | https://github.com/google-gemini/gemini-cli/tree/main/docs |
|
|
10771
10884
|
| Release notes | https://github.com/google-gemini/gemini-cli/releases |
|
|
10772
10885
|
| Config paths | `GEMINI.md`, `.gemini/settings.json`, `~/.gemini/settings.json`, `.gemini/commands/*.toml`, `.gemini/skills/*/SKILL.md`, `.agents/skills/*/SKILL.md`, `.gemini/extensions/gemini-extension.json` |
|
|
10773
|
-
| Our generators | `scripts/generate_gemini.py` |
|
|
10886
|
+
| Our generators | `scripts/generate_gemini.py`, `scripts/generate_gemini_hooks.py` (profile>=standard), `scripts/generate_gemini_commands.py` (profile=full), `scripts/generate_gemini_skills.py` (profile=full) |
|
|
10774
10887
|
| Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `SessionStart`, `SessionEnd`, `Stop`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` |
|
|
10775
10888
|
| Version probe | `gemini --version` |
|
|
10776
10889
|
| Latest upstream | v0.39.0 (2026-04-23) |
|
|
@@ -10820,7 +10933,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
10820
10933
|
| Docs | https://docs.augmentcode.com |
|
|
10821
10934
|
| Changelog | https://www.augmentcode.com/changelog |
|
|
10822
10935
|
| Config paths | `.augment/rules/*.md`, `.augment/guidelines.md` (legacy), `.augment/agents/*.md`, `.augment/commands/*.md`, `.augment/skills/*/SKILL.md`, `~/.augment/rules/*.md`, `~/.augment/settings.json`, `/etc/augment/settings.json` |
|
|
10823
|
-
| Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py` |
|
|
10936
|
+
| Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py`, `scripts/generate_augment_agents.py` (profile=full), `scripts/generate_augment_commands.py` (profile=full), `scripts/generate_augment_hooks.py` (profile=full, HOME-scoped), `scripts/generate_augment_skills.py` (profile=full) |
|
|
10824
10937
|
| Tracked capabilities | `.augment`, Agent mode, Next Edit, MCP, context engine, Auggie CLI, `always_apply`, `agent_requested`, subagents, custom commands, `SKILL.md`, `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `Stop`, ACP Mode |
|
|
10825
10938
|
| SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
|
|
10826
10939
|
|
|
@@ -10844,7 +10957,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
|
|
|
10844
10957
|
| Docs | https://github.com/openai/codex (redirects from developers.openai.com/codex) |
|
|
10845
10958
|
| Release notes | https://github.com/openai/codex/releases |
|
|
10846
10959
|
| Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.codex/hooks.json`, `.codex/skills/*/SKILL.md`, `~/.codex/config.toml` |
|
|
10847
|
-
| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py` |
|
|
10960
|
+
| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
|
|
10848
10961
|
| Tracked hook events | `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`, `PermissionRequest` (6 events supported upstream in `config.toml`) |
|
|
10849
10962
|
| Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
|
|
10850
10963
|
| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.codex/skills/*/SKILL.md` (native discovery, not auto-emitted by ai-toolkit yet) |
|
package/manifest.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@softspark/ai-toolkit",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.1",
|
|
4
4
|
"description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|