@softspark/ai-toolkit 4.14.1 → 4.15.0

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 (47) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +11 -10
  3. package/app/.claude-plugin/plugin.json +1 -1
  4. package/app/CLAUDE.md.template +3 -0
  5. package/app/hooks/_search-capability.sh +3 -2
  6. package/app/hooks/stop-search-check.sh +2 -1
  7. package/benchmarks/ecosystem-doctor-snapshot.json +73 -31
  8. package/kb/procedures/maintenance-sop.md +26 -13
  9. package/kb/procedures/release-verification-sop.md +41 -36
  10. package/kb/reference/architecture-overview.md +23 -7
  11. package/kb/reference/codex-cli-compatibility.md +96 -36
  12. package/kb/reference/extension-api.md +52 -9
  13. package/kb/reference/global-install-model.md +53 -21
  14. package/kb/reference/hooks-catalog.md +44 -8
  15. package/kb/reference/mcp-editor-compatibility.md +27 -6
  16. package/kb/reference/mcp-templates.md +12 -6
  17. package/kb/reference/opencode-compatibility.md +13 -7
  18. package/kb/reference/plugin-pack-conventions.md +7 -7
  19. package/kb/reference/skills-catalog.md +3 -3
  20. package/kb/reference/supported-tools-registry.md +19 -17
  21. package/kb/reference/windows-support.md +26 -3
  22. package/llms-full.txt +443 -180
  23. package/llms.txt +1 -1
  24. package/manifest.json +1 -1
  25. package/package.json +2 -2
  26. package/scripts/codex_skill_adapter.py +448 -198
  27. package/scripts/dir_rules_shared.py +2 -11
  28. package/scripts/ecosystem_tools.json +29 -8
  29. package/scripts/emission.py +5 -91
  30. package/scripts/generate_agents_md.py +4 -87
  31. package/scripts/generate_codex.py +5 -95
  32. package/scripts/generate_codex_agents.py +242 -0
  33. package/scripts/generate_codex_hooks.py +648 -55
  34. package/scripts/generate_codex_skills.py +15 -6
  35. package/scripts/generate_copilot.py +771 -74
  36. package/scripts/generate_copilot_hooks.py +606 -0
  37. package/scripts/generate_cursor_hooks.py +453 -121
  38. package/scripts/generate_opencode_commands.py +4 -6
  39. package/scripts/inject_hook_cli.py +770 -205
  40. package/scripts/injection.py +102 -23
  41. package/scripts/install_steps/ai_tools.py +123 -83
  42. package/scripts/instruction_core.py +95 -0
  43. package/scripts/mcp_editors.py +934 -80
  44. package/scripts/mcp_manager.py +46 -26
  45. package/scripts/plugin.py +291 -114
  46. package/scripts/secure_fs.py +538 -0
  47. package/scripts/uninstall.py +1279 -208
package/CHANGELOG.md CHANGED
@@ -7,6 +7,34 @@ Versioning follows [Semantic Versioning](https://semver.org/).
7
7
 
8
8
  ---
9
9
 
10
+ ## v4.15.0 — Native Codex and Copilot parity (2026-07-14)
11
+
12
+ Minor release. Rebuilds the Codex CLI and GitHub Copilot integrations around their current native instruction, agent, skill, hook, and MCP surfaces. It also hardens managed-file migration and multi-file configuration updates so toolkit refreshes preserve user-owned content and fail without leaving partial state. No source catalog count change (44 agents, 108 skills).
13
+
14
+ ### Added
15
+ - **Codex native custom agents** — `scripts/generate_codex_agents.py` materializes all 44 source agents as validated `.codex/agents/ai-toolkit-*.toml` files with native `name`, `description`, and `developer_instructions` fields. Logical-name collisions, unmanaged files, stale symlinks, and staging failures preserve user content.
16
+ - **Complete Codex skill delivery** — project installs expose all 108 skills under `.agents/skills/`: 51 portable skills link to their canonical source and 57 Claude-specific skills receive self-contained, signature-free Codex adaptations with required assets retained.
17
+ - **Self-contained Codex hooks** — project and user installs emit schema-validated `.codex/hooks.json` plus native runtime assets under `.codex/hooks/` or `$CODEX_HOME/ai-toolkit-hooks/`. Managed handlers merge idempotently with user hooks and keep Codex trust review explicit.
18
+ - **Copilot native customization bundle** — project installs now generate all 44 native `.agent.md` agents, all 108 materialized portable skills, 62 slash-command `.prompt.md` files, and scoped instruction files under `.github/`. User installs provide instructions, agents, and skills under `$COPILOT_HOME`; prompt files remain repository-scoped.
19
+ - **Copilot native lifecycle hooks** — `scripts/generate_copilot_hooks.py` writes GitHub version-1 hook configuration and a self-contained runtime with native camelCase events, event-specific decisions, destructive-command/path guards, quality gates, and a bounded stop-loop circuit breaker.
20
+ - **Codex project and user MCP** — MCP templates now render validated STDIO or Streamable HTTP `[mcp_servers.*]` tables into project `.codex/config.toml` and user `$CODEX_HOME/config.toml`, while preserving unrelated TOML text and comments.
21
+
22
+ ### Changed
23
+ - **One shared instruction and constitution core** — Codex and Copilot `AGENTS.md` output now comes from `scripts/instruction_core.py` and the canonical `app/constitution.md`. Agent and skill catalogs are discovered from native directories instead of being duplicated into always-on instructions.
24
+ - **Portable skill translation** — Codex, Copilot, and opencode adapters replace Claude-only tools, prompt placeholders, and skill-directory variables with runtime-neutral workflow intent instead of guessed client function signatures. opencode commands retain native `$ARGUMENTS` and positional argument behavior.
25
+ - **Profile-aware Copilot install model** — project `minimal` installs agents and skills; `standard`, `strict`, and `full` additionally install instructions, prompts, and native hooks. User installs always provide instructions, agents, and skills, with hooks enabled from `standard` upward. `COPILOT_HOME` replaces the default user root consistently.
26
+ - **Release workflow runtime** — pinned `softprops/action-gh-release` to the reviewed v3.0.2 commit for the Node 24 action runtime.
27
+
28
+ ### Fixed
29
+ - **Rules and constitution enforcement gaps** — current Codex and Copilot instruction files now receive the same always-on policy derived from the canonical constitution, eliminating stale or unread duplicated rule catalogs.
30
+ - **Managed marker migration** — instruction injection handles nested, crossed, orphaned, empty legacy, and Unicode section markers without consuming adjacent user-authored content.
31
+ - **Transactional MCP updates** — canonical `.mcp.json` and all requested native editor configs are preflighted and applied as one atomic transaction. Invalid JSON/TOML, symlinked destinations, concurrent changes, or a late replace failure leave prior files byte-identical or trigger an explicit rollback failure.
32
+ - **Managed output safety** — native generators stage and validate replacements, reject symlinked roots, preserve reserved user collisions and unmanaged files, and remove only files carrying ai-toolkit ownership markers.
33
+
34
+ ### Ecosystem
35
+ - **Class B/F — Codex CLI**: adopted native custom-agent TOML, current skill discovery, the documented hook schema and trust model, project/user configuration layers, `$CODEX_HOME`, and project-scoped MCP from the current OpenAI documentation.
36
+ - **Class B/F — GitHub Copilot**: adopted repository and user custom agents, prompt files, instruction files, portable skills, version-1 hooks, `$COPILOT_HOME`, and `.github/mcp.json` from the current GitHub documentation.
37
+
10
38
  ## v4.14.1 — Keep fact-checker on Sonnet (2026-07-14)
11
39
 
12
40
  Patch release. Reverts one of the two agent model reassignments from v4.14.0: `fact-checker` goes back to `model: sonnet`. Claim verification is accuracy-sensitive and Haiku's recall on subtle claims did not justify the cost saving. `explorer-agent` (pure read/search) stays on `model: haiku`. No count change (44 agents, 108 skills, 1216 tests).
package/README.md CHANGED
@@ -6,16 +6,17 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
7
  [![Skills](https://img.shields.io/badge/skills-108-brightgreen)](app/skills/)
8
8
  [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
9
- [![Tests](https://img.shields.io/badge/tests-1216%20passing-success)](tests/)
9
+ [![Tests](https://img.shields.io/badge/tests-1367%20passing-success)](tests/)
10
10
 
11
- ## What's New in v4.14.1
11
+ ## What's New in v4.15.0
12
12
 
13
- v4.14.1 refreshes Claude model IDs to the current generation, makes model routing effort-aware, and tunes agent model tiers.
13
+ v4.15.0 brings the Codex CLI and GitHub Copilot integrations onto their current native customization surfaces and closes the gaps that caused rules, agents, skills, or hooks to be ignored.
14
14
 
15
- - **Current model IDs**: `scripts/_common.py` now resolves `opus → claude-opus-4-8` and `sonnet claude-sonnet-5` (the single source of truth generators emit); stale `claude-opus-4-7` samples across skills refreshed.
16
- - **Effort-aware routing**: `model-routing-patterns` gains an Effort section tuning `output_config.effort` is the cheaper lever before swapping models, and it does not invalidate the prompt cache the way a mid-session model swap does.
17
- - **Fable 5 tier documented**: added to the routing table with pricing and a "not the default best model" caveat for "strongest model", the target stays `claude-opus-4-8`.
18
- - **Agent tiers tuned**: `explorer-agent` (pure read/search) runs on `model: haiku`; `fact-checker` stays on `model: sonnet` accuracy over cost for claim verification.
15
+ - **Native Codex bundle**: emits the shared constitution-backed `AGENTS.md`, 44 custom-agent TOML files, all 108 skills, self-contained lifecycle hooks, and project/user MCP configuration.
16
+ - **Native Copilot bundle**: project installs emit 44 `.agent.md` agents, all 108 portable skills, 62 `.prompt.md` commands, scoped instructions, version-1 hooks, and MCP configuration; personal instructions, agents, skills, hooks, and MCP live below `$COPILOT_HOME` (default `~/.copilot`).
17
+ - **One policy source**: Codex and Copilot instructions now derive from `app/constitution.md`; agent and skill catalogs stay in native discovery directories instead of bloating always-on context.
18
+ - **Safer managed updates**: user-owned collisions and symlinks are preserved or rejected, while canonical `.mcp.json` and editor configs use preflighted multi-file updates with rollback on late failures.
19
+ - **Native config roots**: Codex hooks and MCP honor `$CODEX_HOME`; Copilot user instructions, agents, skills, and hooks consistently honor `$COPILOT_HOME`. Symlinked configuration roots are rejected.
19
20
 
20
21
  See [CHANGELOG.md](CHANGELOG.md) for full history.
21
22
 
@@ -120,13 +121,13 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
120
121
  | Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | ✅ | project (`~/.cursor/mcp.json` for MCP only) |
121
122
  | Windsurf (Devin Desktop) | `~/.config/devin/AGENTS.md` + `.devin/rules/*.md` + `.devin/hooks.v1.json` + `.windsurf/skills/*` | ✅ | global + project |
122
123
  | Gemini CLI | `~/.gemini/GEMINI.md` | ✅ | global |
123
- | GitHub Copilot | `.github/copilot-instructions.md` + `.github/instructions/*` + `.github/prompts/*` + `AGENTS.md` | | project |
124
+ | GitHub Copilot | Project: `AGENTS.md` + `.github/copilot-instructions.md` + `.github/{instructions,prompts,agents,skills,hooks}/` + `.github/mcp.json`; user: `$COPILOT_HOME/copilot-instructions.md` + `$COPILOT_HOME/{instructions,agents,skills,hooks}/` + `$COPILOT_HOME/mcp-config.json` | | project + user |
124
125
  | Cline | `~/Documents/Cline/Rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | — | global + project |
125
126
  | Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | — | global rules + project |
126
127
  | Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | — | global + project |
127
128
  | Augment | `~/.augment/rules/*.md` + `.augment/rules/ai-toolkit-*.md` | ✅ | global + project |
128
129
  | Google Antigravity | `.agents/rules/*.md` + `.agents/workflows/*.md` + skill pointer in `.agent/skills/*` (IDE) and `.agents/skills/*` (CLI) | — | project |
129
- | Codex CLI | `AGENTS.md` (coding rules inlined) + `.agents/skills/*` + `.codex/hooks.json` | ✅ | project + global plugin |
130
+ | Codex CLI | Project: `AGENTS.md` + `.agents/skills/*` + `.codex/{agents,hooks}/` + `.codex/{hooks.json,config.toml}`; user: `$CODEX_HOME/{AGENTS.md,agents,hooks.json,config.toml}` + `$HOME/.agents/skills/*` | ✅ | project + user |
130
131
  | opencode | `AGENTS.md` + `.opencode/{agents,commands,plugins}/*` + `opencode.json` | ✅ | project + global (`~/.config/opencode/`) |
131
132
 
132
133
  > Claude Code is always installed (primary platform). Other editors are selected with `--editors`; the Claude app uses the separate `claude-app export` flow because its customization store is UI/plugin-managed. The **Hooks** column marks platforms with lifecycle enforcement. Platforms marked — receive guidance without blocking hooks.
@@ -165,7 +166,7 @@ ai-toolkit/
165
166
  │ └── ARCHITECTURE.md # Full system design
166
167
  ├── kb/ # Reference docs, procedures, plans
167
168
  ├── scripts/ # Validation, install, evaluation scripts
168
- ├── tests/ # Bats test suite (1216 tests)
169
+ ├── tests/ # Bats test suite (1367 tests)
169
170
  └── CHANGELOG.md
170
171
  ```
171
172
 
@@ -3,7 +3,7 @@
3
3
  "name": "ai-toolkit",
4
4
  "displayName": "AI Toolkit",
5
5
  "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
6
- "version": "4.14.1",
6
+ "version": "4.15.0",
7
7
  "author": {
8
8
  "name": "SoftSpark",
9
9
  "url": "https://github.com/softspark"
@@ -19,5 +19,8 @@
19
19
  ## Key Conventions
20
20
  <!-- Only non-obvious rules that can't be inferred from code -->
21
21
 
22
+ ## Project Constitution
23
+ @.claude/constitution.md
24
+
22
25
  ## MCP Servers
23
26
  <!-- Which servers are configured and one-line when to use each -->
@@ -10,8 +10,9 @@ ai_toolkit_search_first_mode() {
10
10
  }
11
11
 
12
12
  ai_toolkit_has_search_provider() {
13
- local mode
13
+ local mode codex_home
14
14
  mode="$(ai_toolkit_search_first_mode)"
15
+ codex_home="${CODEX_HOME:-$HOME/.codex}"
15
16
  case "$mode" in
16
17
  off|false|0|disabled|none)
17
18
  return 1
@@ -46,7 +47,7 @@ ai_toolkit_has_search_provider() {
46
47
  done
47
48
 
48
49
  local toml_candidates=(
49
- "$HOME/.codex/config.toml"
50
+ "$codex_home/config.toml"
50
51
  )
51
52
  for path in "${toml_candidates[@]}"; do
52
53
  [ -f "$path" ] || continue
@@ -33,7 +33,8 @@ fi
33
33
 
34
34
  ai_toolkit_codex_log_has_search_since() {
35
35
  local flag="$1"
36
- local log="$HOME/.codex/log/codex-tui.log"
36
+ local codex_home="${CODEX_HOME:-$HOME/.codex}"
37
+ local log="$codex_home/log/codex-tui.log"
37
38
  [ -f "$log" ] || return 1
38
39
 
39
40
  python3 - "$flag" "$log" <<'PY' 2>/dev/null
@@ -1,5 +1,5 @@
1
1
  {
2
- "last_run": "2026-07-10T06:43:18Z",
2
+ "last_run": "2026-07-15T05:28:09Z",
3
3
  "schema_version": 1,
4
4
  "tools": {
5
5
  "aider": {
@@ -24,7 +24,7 @@
24
24
  }
25
25
  },
26
26
  "augment": {
27
- "docs_hash": "880db45231fef284",
27
+ "docs_hash": "480f89501d47f5ec",
28
28
  "headings": [
29
29
  "Admin",
30
30
  "Auggie CLI",
@@ -66,10 +66,11 @@
66
66
  }
67
67
  },
68
68
  "claude-app": {
69
- "docs_hash": "bd1483491a8a64e2",
69
+ "docs_hash": "01981c240e67db02",
70
70
  "headings": [
71
71
  "Add global and folder instructions",
72
72
  "Availability",
73
+ "Choose how Claude checks with you",
73
74
  "Claude Cowork plugins",
74
75
  "Claude stopped working on my task",
75
76
  "Current limitations",
@@ -87,8 +88,6 @@
87
88
  "I&#x27;m hitting usage limits quickly",
88
89
  "I&#x27;m seeing &quot;Setting up Claude&#x27;s workspace&quot; when I start Cowork; what does this mean?",
89
90
  "Key capabilities",
90
- "Permission modes",
91
- "Permissions",
92
91
  "Permissions and security",
93
92
  "Requirements",
94
93
  "Research and analysis",
@@ -108,7 +107,7 @@
108
107
  }
109
108
  },
110
109
  "claude-code": {
111
- "docs_hash": "50b46c4f57d16b9e",
110
+ "docs_hash": "517ae09f5f1feba9",
112
111
  "headings": [
113
112
  "Core concepts",
114
113
  "Documentation Index",
@@ -164,10 +163,10 @@
164
163
  "slash command": true,
165
164
  "sub-agent": true
166
165
  },
167
- "version": "2.1.206 (Claude Code)"
166
+ "version": "2.1.210 (Claude Code)"
168
167
  },
169
168
  "cline": {
170
- "docs_hash": "1726cf1ff3f402b6",
169
+ "docs_hash": "9a024e9356105f48",
171
170
  "headings": [
172
171
  "API Reference",
173
172
  "Best Practices",
@@ -214,80 +213,120 @@
214
213
  }
215
214
  },
216
215
  "codex-cli": {
217
- "docs_hash": "46073353f24772e6",
216
+ "docs_hash": "cc18a01c239497e8",
218
217
  "headings": [
219
218
  "API",
220
219
  "API Reference",
221
220
  "Advertiser API",
222
221
  "Agent configuration",
223
222
  "Agents SDK",
223
+ "Audio",
224
224
  "Available on",
225
225
  "Blog",
226
+ "Bring visual context into the prompt",
226
227
  "Build",
228
+ "Build a terminal workflow around Codex",
229
+ "Build tool workflows",
227
230
  "Build with Codex",
228
231
  "Capabilities",
229
232
  "Categories",
230
- "Chats",
231
- "Choose the right GPT-5.6 model",
233
+ "ChatGPT web",
234
+ "ChatKit",
235
+ "Choose a model",
232
236
  "Codex Security",
237
+ "Codex cloud",
233
238
  "Community",
239
+ "Compose with scripts and CI",
240
+ "Computer and code",
234
241
  "Config file",
235
- "Continue a task on another host",
242
+ "Connect external tools with MCP",
243
+ "Connect tools and data",
244
+ "Connection methods",
236
245
  "Contribute",
237
246
  "Conversion apps",
238
247
  "Core Concepts",
239
248
  "Core concepts",
249
+ "Cost and throughput",
240
250
  "Customization",
241
251
  "Deploy",
242
252
  "Deployment and model providers",
253
+ "Desktop app",
243
254
  "Development workflows",
244
255
  "Docs agent",
245
256
  "Environments",
246
- "Evaluation",
247
257
  "Events",
248
258
  "Explore",
249
259
  "Extend ChatGPT and Codex",
250
260
  "Extend and automate",
251
261
  "File Upload",
262
+ "Fit Codex to your terminal",
252
263
  "Foundations",
253
264
  "Get started",
265
+ "Get started with Codex CLI",
254
266
  "Getting started",
255
- "Going live",
267
+ "Go live",
256
268
  "Guides",
269
+ "IDE extension",
257
270
  "Identity and authentication",
271
+ "Images and video",
272
+ "Infrastructure and access",
273
+ "Inspect, edit, and run code from your terminal",
274
+ "Install Codex",
275
+ "Keep the coding loop in your terminal",
258
276
  "Legacy APIs",
259
277
  "Measurement",
260
- "Overview",
278
+ "Media",
279
+ "Move work to Codex cloud",
280
+ "Operations",
281
+ "Other ChatGPT and Codex surfaces",
282
+ "Performance and quality",
261
283
  "Permissions",
262
284
  "Plan",
263
285
  "Plugin and connector controls",
264
286
  "Programs",
265
- "Projects",
287
+ "Prompting",
266
288
  "Realtime and audio",
289
+ "Reasoning",
267
290
  "Recent",
268
291
  "Reference",
269
292
  "Releases",
270
293
  "Resources",
271
- "Run and scale",
294
+ "Return to a saved session",
295
+ "Review changes before they ship",
296
+ "Run Codex and sign in",
297
+ "SDKs and CLI",
272
298
  "Safety",
299
+ "Safety and governance",
300
+ "Search and retrieval",
301
+ "Search for current context",
273
302
  "Search the docs",
303
+ "See what Codex CLI can do",
304
+ "Sessions and operations",
305
+ "Set the boundaries for each run",
274
306
  "Spaces",
275
307
  "Specialized models",
308
+ "Split up a larger investigation",
309
+ "Start your first task",
310
+ "Stay in control",
276
311
  "Suggested",
277
- "Take on ambitious work with ChatGPT Work",
312
+ "Text and code",
278
313
  "Third-party integrations",
279
- "Tools",
280
314
  "Topics",
281
- "Turn demonstrated workflows into reusable skills",
282
315
  "Usage, governance, and compliance",
283
- "What should we get done?",
284
- "What\u2019s new",
316
+ "Use Codex CLI when\u2026",
317
+ "Use skills and plugins",
285
318
  "Windows",
319
+ "Work against your local repository",
286
320
  "Workflows",
287
- "Workspace access, policy, and models"
321
+ "Workspace access, policy, and models",
322
+ "You need scripting or CI",
323
+ "You want a local code review",
324
+ "You want to hand work to the cloud",
325
+ "You work from the terminal"
288
326
  ],
289
327
  "markers": {
290
328
  ".agents/skills": false,
329
+ ".codex/agents": false,
291
330
  "AGENTS.md": true,
292
331
  "config.toml": false,
293
332
  "hook event: PermissionRequest": false,
@@ -307,10 +346,10 @@
307
346
  "mcp_servers": false,
308
347
  "sandbox": true
309
348
  },
310
- "version": "codex-cli 0.144.1"
349
+ "version": "codex-cli 0.144.4"
311
350
  },
312
351
  "cursor": {
313
- "docs_hash": "63246f9f6c354976",
352
+ "docs_hash": "34efb96589c7f123",
314
353
  "headings": [],
315
354
  "markers": {
316
355
  ".cursor/rules": false,
@@ -326,7 +365,7 @@
326
365
  }
327
366
  },
328
367
  "gemini-cli": {
329
- "docs_hash": "7a28426194187480",
368
+ "docs_hash": "c24d346e0c5a1bb9",
330
369
  "headings": [
331
370
  "Breadcrumbs",
332
371
  "Directory actions",
@@ -369,7 +408,7 @@
369
408
  }
370
409
  },
371
410
  "github-copilot": {
372
- "docs_hash": "788efbd31f39bd11",
411
+ "docs_hash": "58d9980c29b7edb8",
373
412
  "headings": [
374
413
  "About Copilot auto model selection",
375
414
  "About Copilot automations",
@@ -391,6 +430,7 @@
391
430
  ],
392
431
  "markers": {
393
432
  "AGENTS.md": false,
433
+ "CLI hooks": false,
394
434
  "Copilot Chat": true,
395
435
  "Copilot Workspace": false,
396
436
  "Copilot cloud agent": true,
@@ -399,11 +439,13 @@
399
439
  "copilot-instructions.md": false,
400
440
  "custom agents": true,
401
441
  "instructions.md": false,
402
- "prompt files": true
442
+ "prompt files": true,
443
+ "skills": true,
444
+ "~/.copilot/": false
403
445
  }
404
446
  },
405
447
  "google-antigravity": {
406
- "docs_hash": "e484097e498581f4",
448
+ "docs_hash": "9c9b420a22b35ae6",
407
449
  "headings": [],
408
450
  "markers": {
409
451
  "AGENTS.md": false,
@@ -419,7 +461,7 @@
419
461
  }
420
462
  },
421
463
  "opencode": {
422
- "docs_hash": "8713591669c1683f",
464
+ "docs_hash": "505b9771a6c768e6",
423
465
  "headings": [
424
466
  "Add features",
425
467
  "Ask questions",
@@ -479,7 +521,7 @@
479
521
  }
480
522
  },
481
523
  "windsurf": {
482
- "docs_hash": "93e7f46747f42e11",
524
+ "docs_hash": "2d4eb599c906bf2c",
483
525
  "headings": [
484
526
  "Accounts",
485
527
  "Advanced",
@@ -1,15 +1,15 @@
1
1
  ---
2
- title: "SOP: Claude Toolkit Maintenance"
2
+ title: "SOP: AI Toolkit Maintenance"
3
3
  category: procedures
4
4
  service: ai-toolkit
5
5
  tags: [sop, maintenance, agents, skills, install]
6
- version: "3.2.0"
6
+ version: "3.3.0"
7
7
  created: "2026-03-23"
8
- last_updated: "2026-07-10"
8
+ last_updated: "2026-07-14"
9
9
  description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
10
10
  ---
11
11
 
12
- # SOP: Claude Toolkit Maintenance
12
+ # SOP: AI Toolkit Maintenance
13
13
 
14
14
  ## Init Repository (New Project)
15
15
 
@@ -45,7 +45,11 @@ ai-toolkit install --local --lang python --editors all # language rules propaga
45
45
 
46
46
  When `--editors` is combined with `--lang` (or auto-detected languages), language rules are propagated to all configured editors as `ai-toolkit-lang-<lang>` files — not just Claude's `CLAUDE.md`. Similarly, registered custom rules (`~/.softspark/ai-toolkit/rules/`) are propagated to directory-based editor configs as `ai-toolkit-custom-<name>` files.
47
47
 
48
- **Note:** Hooks are global-only merged into `~/.claude/settings.json` by `ai-toolkit install`. Project-local `--local` does not install hooks; any legacy `.claude/hooks.json` is removed automatically.
48
+ **Note:** Claude Code hooks are global-only and merge into
49
+ `~/.claude/settings.json`; any legacy `.claude/hooks.json` is removed. Editors
50
+ with documented repository hook surfaces may receive local native files. Codex
51
+ uses `.codex/hooks.json` plus `.codex/hooks/*`; Copilot profile `standard` and
52
+ above uses `.github/hooks/ai-toolkit.json` plus its adjacent runtime.
49
53
 
50
54
  **Input validation (v1.4.2):** `--only`, `--skip`, `--editors`, and `--lang` are validated on input; an invalid value exits with a clear error before any changes are made.
51
55
 
@@ -112,14 +116,16 @@ updates. Skills work in Chat and Cowork. Hooks and sub-agents run only in Cowork
112
116
 
113
117
  ### Install Profiles (v3.0.0)
114
118
 
115
- | Profile | Claude Code core | Editor rules | Gemini hooks | Copilot dir layout | Per-editor hooks / sub-agents / commands | Git hooks |
116
- |---------|:---------------:|:------------:|:------------:|:------------------:|:---------------------------------------:|:---------:|
117
- | `minimal` | yes | pointer only | no | no | no | no |
118
- | `standard` (default) | yes | yes | **yes** (new in v3) | **yes** (new in v3) | no | no |
119
- | `strict` | yes | yes | yes | yes | no | yes |
120
- | `full` | yes | yes | yes | yes | **yes, all editors** | optional |
119
+ | Profile | Claude Code core | Copilot | Codex | Other editor-native surfaces | Git hooks |
120
+ |---------|:---------------:|---------|-------|------------------------------|:---------:|
121
+ | `minimal` | yes | root instructions + agents + skills | instructions + agents + skills + hooks | pointer-only where required | no |
122
+ | `standard` (default) | yes | minimal + scoped instructions + prompts + hooks | same native bundle | Gemini hooks + editor rules | no |
123
+ | `strict` | yes | same as standard | same native bundle | same as standard | yes |
124
+ | `full` | yes | same as standard | same native bundle | all supported hooks, agents, commands, and skill pointers | optional |
121
125
 
122
- `--codex-skills` is orthogonal to `--profile` and materializes the full skill catalog under `.agents/skills/` for Codex. See `kb/reference/global-install-model.md` for the full semantic breakdown.
126
+ Codex materializes the full skill catalog under `.agents/skills/` in every
127
+ profile. `--codex-skills` remains only as an explicit refresh compatibility
128
+ flag. See `kb/reference/global-install-model.md` for the full breakdown.
123
129
 
124
130
  ---
125
131
 
@@ -293,7 +299,14 @@ ai-toolkit plugin remove --editor codex <name> # remove from one runtime only
293
299
  ai-toolkit plugin status --editor all # show installed packs with runtime details
294
300
  ```
295
301
 
296
- Install copies hooks/scripts, verifies agents+skills are linked, merges hooks into the selected runtime config, and runs init scripts. For Codex, the selected runtime is the global `HOME` layer (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`). Update removes and reinstalls from current source while preserving plugin data. Clean prunes old plugin data. Remove reverses install for the selected runtime but leaves plugin data intact. Core agents/skills are never removed.
302
+ Install copies runtime-owned hooks/scripts, ensures the required base skills are
303
+ available, merges native hook configuration, and runs init scripts. Codex uses
304
+ `$CODEX_HOME/AGENTS.md`, `$CODEX_HOME/hooks.json`, self-contained
305
+ `$CODEX_HOME/ai-toolkit-hooks/*`, and shared `$HOME/.agents/skills/*`; it never
306
+ uses `~/AGENTS.md` or `$HOME/.agents/rules/` as user configuration. Update
307
+ removes and reinstalls the selected pack while preserving plugin data. Remove
308
+ strips only exact pack-owned handlers, assets, and marker sections. Core
309
+ agents/skills and user handlers remain untouched.
297
310
 
298
311
  Memory-pack auto-prunes observations older than 90 days on every session end (configurable via `MEMORY_RETENTION_DAYS`).
299
312