@ranimontagna/agent-toolkit 0.2.0 → 0.2.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.
Files changed (5) hide show
  1. package/CHANGELOG.md +257 -71
  2. package/CONTRIBUTING.md +14 -0
  3. package/README.md +66 -706
  4. package/SECURITY.md +62 -8
  5. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,102 +1,288 @@
1
1
  # Changelog
2
2
 
3
- ## 0.1.30
3
+ Agent Toolkit has evolved from a hardened installer foundation into a catalog-driven release with pinned external skills, multi-runtime support, and safer release operations.
4
4
 
5
- - onboard-repo: fixed the runtime-selection guidance — bare runtime flags
6
- are mutually exclusive, so the skill now instructs
7
- `--all-runtimes --no-gemini --no-antigravity` for multi-runtime installs.
5
+ | Milestone | Versions | Meaningful evolution |
6
+ |---|---|---|
7
+ | Foundation | `0.1.0`–`0.1.16` | Hardened installer foundation, interactive selection, bundled language/workflow skills, granular skill selection, Graphify workflow, and Antigravity runtime. |
8
+ | Toolkit expansion | `0.1.17`–`0.1.22` | Improve, GSAP, toolkit operations, strict review, revenue/design workflows, and official GSD integration. |
9
+ | Lifecycle hardening | `0.1.23`–`0.1.26` | React Doctor, safer uninstall/repair, pinned-source enforcement, Windows support, redirect checks, provenance, and Graphify 0.9.11. |
10
+ | Onboarding and catalog growth | `0.1.27`–`0.1.31` | Planning skills, Web Design Guidelines, repository onboarding, multi-runtime guidance, Agent Browser, and Remotion skills. |
11
+ | Catalog-driven release | `0.2.0` | Normalized agent-skill catalog plus bounded HTTP, release, Antigravity, manifest, and publication hardening. |
12
+ | Documentation overhaul | `0.2.1` | Rebuilt onboarding and operational documentation, reconstructed release history, and clarified architecture, configuration, testing, deployment, contribution, and security boundaries. |
8
13
 
9
- ## 0.1.29
14
+ The release entries below are based on Git tag ranges and npm publication metadata. Publication uses Git tags plus GitHub Actions, not GitHub Release objects.
10
15
 
11
- - Added the bundled `onboard-repo` skill (`core` package): detects a
12
- repository's stack, installs the matching toolkit skills, and organizes the
13
- agent docs (canonical `AGENTS.md`, pointer `CLAUDE.md`, optional MCP
14
- config), ending with a report of what was installed and skipped.
16
+ ## [0.2.1] - 2026-07-14
15
17
 
16
- ## 0.1.28
18
+ Published to npm
17
19
 
18
- - Frontend Skills: replaced Taste Skill with Vercel's Web Design Guidelines
19
- (`vercel-labs/agent-skills`, skill `web-design-guidelines`) — an objective
20
- UI-code auditor that complements Impeccable (design direction) instead of
21
- overlapping with it. Taste Skill v2 is marked experimental upstream and
22
- competes with Impeccable for the same role.
20
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.2.0...v0.2.1)
23
21
 
24
- ## 0.1.27
22
+ - Rebuilt the public documentation into a concise README plus focused onboarding, architecture, configuration, development, testing, deployment, contribution, and security guides.
23
+ - Reconstructed the complete Git and npm release history with per-version differences, publication status, dates, and compare links.
24
+ - Added adversarial documentation verification for source-backed claims, CLI flags, package scripts, local links, release invariants, packaging, and public-safety checks.
25
25
 
26
- - Added the `planning-skills` tool: installs Matt Pocock's grilling skills
27
- (`grill-me`, `grilling`, `grill-with-docs`, `domain-modeling`) from
28
- `mattpocock/skills` at a pinned commit through the Agent Skills CLI.
29
- New flags: `--planning-skills-only` and `--no-planning-skills`.
26
+ ## [0.2.0] - 2026-07-14
30
27
 
31
- ## 0.1.26
28
+ Published to npm
32
29
 
33
- - Bumped the pinned Graphify version from `graphifyy==0.8.51` to `graphifyy==0.9.11`.
30
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.31...v0.2.0)
34
31
 
35
- ## 0.1.25
32
+ - Added catalog-driven agent-skill metadata and installer, containment of skill roots, bounded HTTP requests, and hardened release state, publish retries, Antigravity environment handling, and manifest uninstall paths.
36
33
 
37
- - Environment overrides that change a source's identity (different npm package,
38
- GitHub repository, PyPI package or RTK release repository than the lock) now
39
- require `--allow-mutable-sources`, closing a silent redirection vector.
40
- - `TOOLS_LOCK_PATH` now requires `--allow-mutable-sources`, since an alternate
41
- lock bypasses every pinned checksum and ref.
42
- - `ANTIGRAVITY_INSTALL_SCRIPT` must be HTTPS (always) and any non-default URL
43
- requires the explicit override flag — the script is piped to bash.
44
- - Fixed Windows support: npm/npx `.cmd` shims are now routed through `cmd.exe`
45
- with cross-spawn-style escaping (Node >= 18.20 refuses to spawn them
46
- directly), and RTK post-install verification runs the real `rtk.exe` instead
47
- of the bash shim.
48
- - Added integration coverage for the full RTK download pipeline (release
49
- metadata, asset download, sha256 verification, install) against a local HTTP
50
- server, including checksum-mismatch rejection.
34
+ ## [0.1.31] - 2026-07-12
51
35
 
52
- ## 0.1.24
36
+ Published to npm
53
37
 
54
- - Fixed `--uninstall --dry-run` deleting files instead of previewing the removal plan.
55
- - Fixed runtime CLI version pinning matching by substring (`2.0.1` matched `2.0.10`).
56
- - Runtime CLI install failures now propagate to the exit code instead of being swallowed.
57
- - Verified that git-cloned pinned skills (Improve, frontend skills) match the pinned commit SHA after checkout.
58
- - Refused HTTPS-to-HTTP downgrades when following download redirects.
59
- - Published to npm with `--provenance` attestation.
60
- - `--repair` now force-reinstalls RTK and Graphify instead of skipping them as "already installed".
61
- - Listed Frontend Skills in the selected-tools output.
62
- - Removed 31 unreferenced media assets (~33 MB), shrinking the npm package by roughly 80%.
63
- - Declared the supported Node.js range in `package.json` (`engines`).
38
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.30...v0.1.31)
64
39
 
65
- ## 0.1.23
40
+ - Added Agent Browser and Remotion skills, stabilized custom-skill fixtures, and ignored local worktrees.
66
41
 
67
- - Corrected RTK hook wiring (`rtk init --global --auto-patch`), guided EACCES npm failures, and warned on silently overridden flags.
68
- - Installed and reported the React Doctor frontend skill.
69
- - Generalized the frontend skills installer copy and stabilized related verification.
42
+ ## [0.1.30] - 2026-07-11
70
43
 
71
- ## 0.1.22
44
+ Published to npm
72
45
 
73
- - Switched GSD to the official `@opengsd/gsd-core` package (old package deprecated).
74
- - Fixed the integration test suite on macOS (BSD `sed`).
75
- - Failed clearly when a skills target path exists as a file.
46
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.29...v0.1.30)
76
47
 
77
- ## 0.1.21
48
+ - Corrected multi-runtime flag guidance for `onboard-repo`.
78
49
 
79
- - Added the design-to-code skill (generation, verification, interaction/responsive rules) hardened through dogfood rounds.
80
- - Adopted taste-skill analysis and anti-drift heuristics in design-to-code.
50
+ ## [0.1.29] - 2026-07-11
81
51
 
82
- ## 0.1.20
52
+ Published to npm
53
+
54
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.28...v0.1.29)
55
+
56
+ - Added the bundled `onboard-repo` skill for stack detection, matching skill installation, and agent-doc organization.
57
+
58
+ ## [0.1.28] - 2026-07-11
59
+
60
+ Published to npm
61
+
62
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.27...v0.1.28)
63
+
64
+ - Replaced Taste Skill with Vercel Web Design Guidelines to complement Impeccable.
65
+
66
+ ## [0.1.27] - 2026-07-11
67
+
68
+ Published to npm
69
+
70
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.26...v0.1.27)
71
+
72
+ - Added pinned planning skills from Matt Pocock: grilling variants and domain modeling.
73
+
74
+ ## [0.1.26] - 2026-07-09
75
+
76
+ Published to npm
77
+
78
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.25...v0.1.26)
79
+
80
+ - Updated Graphify from `0.8.51` to `0.9.11`.
81
+
82
+ ## [0.1.25] - 2026-07-09
83
+
84
+ Published to npm
85
+
86
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.24...v0.1.25)
87
+
88
+ - Required explicit permission for source-identity overrides and alternate locks, enforced HTTPS for Antigravity override scripts, restored Windows npm/RTK execution, and added RTK download/checksum integration coverage.
89
+
90
+ ## [0.1.24] - 2026-07-09
91
+
92
+ Published to npm
93
+
94
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.23...v0.1.24)
95
+
96
+ - Made uninstall dry-run non-destructive, fixed exact runtime-version matching and failure propagation, verified pinned checkouts and redirect safety, added npm provenance, strengthened repair behavior, reduced package size, and declared Node engines.
97
+
98
+ ## [0.1.23] - 2026-07-09
99
+
100
+ Published to npm
101
+
102
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.22...v0.1.23)
103
+
104
+ - Added pinned React Doctor integration, generalized frontend-skill installation, corrected RTK hook wiring, improved EACCES and flag-override guidance, and stabilized tests.
105
+
106
+ ## [0.1.22] - 2026-07-08
107
+
108
+ Published to npm
109
+
110
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.21...v0.1.22)
111
+
112
+ - Switched to official `@opengsd/gsd-core`, fixed macOS integration tests, and rejected target paths that are files.
113
+
114
+ ## [0.1.21] - 2026-07-04
115
+
116
+ Published to npm
117
+
118
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.20...v0.1.21)
119
+
120
+ - Added the complete design-to-code lifecycle, hardened it through dogfood, and added interaction, responsive, multi-screen, consolidation, and anti-drift guidance.
121
+
122
+ ## [0.1.20] - 2026-07-02
123
+
124
+ Published to npm
125
+
126
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.19...v0.1.20)
83
127
 
84
128
  - Added the revenue-centric design skill.
85
129
 
86
- ## 0.1.19
130
+ ## [0.1.19] - 2026-06-28
131
+
132
+ Published to npm
133
+
134
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.18...v0.1.19)
135
+
136
+ - Refreshed toolkit pins and bundled skills.
137
+
138
+ ## [0.1.18] - 2026-06-19
139
+
140
+ Published to npm
141
+
142
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.17...v0.1.18)
143
+
144
+ - Added toolkit operation commands and the thermonuclear code-quality review skill.
145
+
146
+ ## [0.1.17] - 2026-06-18
147
+
148
+ Published to npm
149
+
150
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.16...v0.1.17)
151
+
152
+ - Added pinned Improve installation and GSAP skills, refreshed source/runtime pins, and published through the trusted npm release flow.
153
+
154
+ ## [0.1.16] - 2026-06-07
155
+
156
+ Published to npm
157
+
158
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.15...v0.1.16)
159
+
160
+ - Added Antigravity as a supported runtime.
161
+
162
+ ## [0.1.15] - 2026-06-04
163
+
164
+ Published to npm
165
+
166
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.14...v0.1.15)
167
+
168
+ - Documented the Graphify workflow and handled macOS install drift.
169
+
170
+ ## [0.1.14] - 2026-06-04
171
+
172
+ Published to npm
173
+
174
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.13...v0.1.14)
175
+
176
+ - Consolidated the custom-skill refinement prompt.
177
+
178
+ ## [0.1.13] - 2026-06-04
179
+
180
+ Published to npm
181
+
182
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.12...v0.1.13)
183
+
184
+ - Streamlined custom-skill prompts.
185
+
186
+ ## [0.1.12] - 2026-06-04
187
+
188
+ Published to npm
189
+
190
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.11...v0.1.12)
191
+
192
+ - Removed a secret-scan false positive from the API skill.
193
+
194
+ ## [0.1.11] - 2026-06-04
195
+
196
+ Published to npm
197
+
198
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.10...v0.1.11)
199
+
200
+ - Added API-design and Astro skills.
201
+
202
+ ## [0.1.10] - 2026-06-04
203
+
204
+ Published to npm
205
+
206
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.9...v0.1.10)
207
+
208
+ - Added package, scope, and exact-path skill selection.
209
+
210
+ ## [0.1.9] - 2026-06-04
211
+
212
+ Published to npm
213
+
214
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.8...v0.1.9)
215
+
216
+ - Added Python and Kotlin skill packages.
217
+
218
+ ## [0.1.8] - 2026-06-04
219
+
220
+ Git tag only — not published to npm
221
+
222
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.7...v0.1.8)
223
+
224
+ - Added bundled workflow skills.
225
+
226
+ ## [0.1.7] - 2026-06-04
227
+
228
+ Published to npm
229
+
230
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.6...v0.1.7)
231
+
232
+ - Added Java and Go skill packages.
233
+
234
+ ## [0.1.6] - 2026-06-04
235
+
236
+ Published to npm
237
+
238
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.5...v0.1.6)
239
+
240
+ - Added React frontend skill packages.
241
+
242
+ ## [0.1.5] - 2026-06-04
243
+
244
+ Published to npm
245
+
246
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.4...v0.1.5)
247
+
248
+ - Improved onboarding, migrated to pnpm, and added Fastify skills.
249
+
250
+ ## [0.1.4] - 2026-06-04
251
+
252
+ Published to npm
253
+
254
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.3...v0.1.4)
255
+
256
+ - Added bundled-skill package selection and npm trusted publishing.
257
+
258
+ ## [0.1.3] - 2026-06-04
259
+
260
+ Published to npm
261
+
262
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.2...v0.1.3)
263
+
264
+ - Displayed installer status before installation.
265
+
266
+ ## [0.1.2] - 2026-06-04
267
+
268
+ Published to npm
269
+
270
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.1...v0.1.2)
271
+
272
+ - Added the visual installer menu.
273
+
274
+ ## [0.1.1] - 2026-06-04
275
+
276
+ Published to npm
87
277
 
88
- - Updated toolkit pins and bundled skills.
278
+ [Compare](https://github.com/raniellimontagna/agent-toolkit/compare/v0.1.0...v0.1.1)
89
279
 
90
- ## 0.1.18
280
+ - Corrected the npm account scope.
91
281
 
92
- - Added the thermonuclear review skill and toolkit operations commands.
282
+ ## [0.1.0] - 2026-06-04
93
283
 
94
- ## 0.1.17
284
+ Git tag only — not published to npm
95
285
 
96
- - Added shadcn Improve installation from a pinned source.
97
- - Added GSAP skills under the bundled frontend package.
98
- - Updated external tool and runtime pins.
99
- - Published through the trusted npm release workflow.
286
+ [Tag](https://github.com/raniellimontagna/agent-toolkit/tree/v0.1.0)
100
287
 
101
- Earlier versions were developed before this changelog existed. Use Git history
102
- and npm release metadata for older details.
288
+ - Established the installer, project rules, CI/security gates, immutable provenance, frontend-skill installer, and npm release workflow.
package/CONTRIBUTING.md CHANGED
@@ -32,3 +32,17 @@ test: cover installer dry run
32
32
  Keep `tools.lock.json` as the source of truth for external tools. New third-party
33
33
  skills must use immutable public sources, include license/notice files when
34
34
  vendored, and pass `pnpm run check`.
35
+
36
+ ## Documentation Changes
37
+
38
+ For documentation-only changes, verify behavior against the implementation and
39
+ verify release claims against Git tags and npm publication metadata.
40
+
41
+ ## Contributor Guides
42
+
43
+ - [Development](docs/DEVELOPMENT.md) covers local setup and the change workflow.
44
+ - [Testing](docs/TESTING.md) explains focused checks and the full release gate.
45
+ - [Deployment and Releases](docs/DEPLOYMENT.md) documents release mechanics.
46
+ - [Configuration](docs/CONFIGURATION.md) defines supported settings and source
47
+ overrides.
48
+ - [Security](SECURITY.md) explains vulnerability reporting and trust controls.
package/README.md CHANGED
@@ -1,747 +1,107 @@
1
1
  # Agent Toolkit
2
2
 
3
- One command to set up an AI coding-agent workspace across Claude Code, Codex
4
- CLI, OpenCode, Gemini CLI and Antigravity.
3
+ Agent Toolkit is a Node.js CLI for installing a pinned, reusable set of coding-agent tools and skills across Claude Code, Codex CLI, OpenCode, Gemini CLI, and Antigravity.
5
4
 
6
- ```bash
7
- npx -y @ranimontagna/agent-toolkit
8
- ```
9
-
10
- Agent Toolkit installs the tools and skills I use to run agentic coding
11
- workflows: RTK, Caveman, Superpowers, Graphify, GSD, shadcn Improve,
12
- third-party frontend skills installed through Agent Skills CLI and bundled
13
- Custom Skills.
14
-
15
- The installer is a TypeScript CLI published to npm. The Bash script is only a
16
- compatibility wrapper for users who already run `setup-agent-toolkit.sh`.
17
-
18
- ## Install Flow
19
-
20
- Interactive terminals use a Clack menu. The installer first shows what it can
21
- detect locally, then asks what to install, then shows a final plan before doing
22
- any work.
23
-
24
- ![Detected status terminal screen](docs/assets/install-status.svg)
25
-
26
- Custom Skills are selected in three levels: package, optional scope and exact
27
- individual skills. Today this repository ships `core`, `backend`, `frontend`,
28
- `general` and `devops`; future packages can be added under
29
- `skills/<package>/...` and they will appear automatically in the menu.
30
-
31
- ![Custom Skill granular selection terminal screen](docs/assets/install-skill-packages.svg)
32
-
33
- The final plan shows selected tools, runtimes, skill packages, scopes, exact
34
- skills and already present destinations before installation starts.
35
-
36
- ![Install plan terminal screen](docs/assets/install-plan.svg)
37
-
38
- ## What It Installs
39
-
40
- | Area | What it adds |
41
- |---|---|
42
- | RTK | Token-aware shell proxy for coding-agent sessions |
43
- | Caveman | Terse response mode and optional agent integrations |
44
- | Superpowers | Planning, TDD, debugging, review and delivery workflows |
45
- | Graphify | Queryable knowledge graphs for codebases, docs and project context |
46
- | GSD | Phase-based planning, execution, verification and project control |
47
- | Agent Browser | Optional pinned browser automation CLI and Chrome for Testing |
48
- | Agent Skills | Catalog-driven third-party bundles: Improve, Agent Browser, Frontend Skills and Planning Skills |
49
- | Custom Skills | Bundled skills from this repository, selected by package, scope and exact skill |
50
-
51
- ## Supported Runtimes
52
-
53
- | Runtime | Support |
54
- |---|---|
55
- | Claude Code | Plugins and skills |
56
- | Codex CLI | Plugins, skills and local automation |
57
- | OpenCode | Skills plus package-driven tools |
58
- | Gemini CLI | Extensions and native Agent Skills install |
59
- | Antigravity | Custom Skills, third-party frontend skills and official `agy` install |
60
-
61
- Superpowers is installed automatically for Claude Code, Codex CLI and Gemini
62
- CLI. OpenCode Superpowers support is not automated yet because the upstream
63
- install flow is not a stable single command. Antigravity Superpowers support is
64
- not automated yet because there is not a pinned supported plugin package in this
65
- toolkit.
66
-
67
- Caveman, GSD, Improve, Frontend Skills, Planning Skills and Custom Skills can
68
- target Claude Code, Codex CLI, OpenCode and Gemini CLI. Improve, Frontend
69
- Skills, Planning Skills and Custom Skills can also target Antigravity. Graphify is installed through the official
70
- `graphifyy` package and registers itself for selected runtimes that Graphify
71
- supports.
72
-
73
- When `--install-missing-clis` is enabled, Antigravity is installed through the
74
- official `agy` installer instead of npm. Global Antigravity Custom Skills are
75
- copied to the official `~/.gemini/antigravity-cli/skills/` path and mirrored to
76
- `~/.agents/skills/` for compatibility with the Agent Skills CLI.
77
-
78
- ## Quick Commands
5
+ ## Quick Start
79
6
 
80
- Run the interactive installer:
81
-
82
- ```bash
83
- npx -y @ranimontagna/agent-toolkit
84
- ```
85
-
86
- Install the full kit for Codex CLI:
7
+ 1. Install [Node.js 24 or newer](https://nodejs.org/) so `npm` and `npx` are available.
8
+ 2. Install the default tool set for Codex CLI:
87
9
 
88
10
  ```bash
89
11
  npx -y @ranimontagna/agent-toolkit --all --codex
90
12
  ```
91
13
 
92
- Install the full kit for every supported runtime:
93
-
94
- ```bash
95
- npx -y @ranimontagna/agent-toolkit --all --all-runtimes
96
- ```
97
-
98
- Install only Graphify for Codex CLI:
99
-
100
- ```bash
101
- npx -y @ranimontagna/agent-toolkit --graphify-only --codex
102
- ```
103
-
104
- Install only shadcn Improve for Codex CLI:
105
-
106
- ```bash
107
- npx -y @ranimontagna/agent-toolkit --improve-only --codex
108
- ```
109
-
110
- Install Agent Browser for Codex CLI:
111
-
112
- ```bash
113
- npx -y @ranimontagna/agent-toolkit --agent-browser-only --codex
114
- ```
115
-
116
- Agent Browser is deliberately excluded from `--all`: it installs a browser
117
- automation executable, downloads Chrome for Testing and copies its pinned skill.
118
- The toolkit never runs `agent-browser install --with-deps`, configures plugins,
119
- cloud browsers or credentials. Run `agent-browser doctor` directly when you
120
- want to validate its local Chrome setup.
121
-
122
- Install only third-party frontend design skills for Codex CLI:
123
-
124
- ```bash
125
- npx -y @ranimontagna/agent-toolkit --frontend-skills-only --codex
126
- ```
127
-
128
- Install the Planning Skills bundle (grilling interviews, domain modeling and
129
- architecture reviews) for Claude Code:
130
-
131
- ```bash
132
- npx -y @ranimontagna/agent-toolkit --planning-skills-only --claude
133
- ```
134
-
135
- Install only bundled Custom Skills into the current project:
136
-
137
- ```bash
138
- npx -y @ranimontagna/agent-toolkit --skills-only --codex --local
139
- ```
140
-
141
- Preview an install plan without changing files:
142
-
143
- ```bash
144
- npx -y @ranimontagna/agent-toolkit --all --codex --dry-run
145
- ```
146
-
147
- Inspect selected tools and runtimes as JSON:
148
-
149
- ```bash
150
- npx -y @ranimontagna/agent-toolkit --doctor --json --codex
151
- ```
152
-
153
- Audit bundled Custom Skills metadata and local links:
154
-
155
- ```bash
156
- npx -y @ranimontagna/agent-toolkit --skills-audit
157
- ```
158
-
159
- Report newer candidates for pinned external tools:
160
-
161
- ```bash
162
- npx -y @ranimontagna/agent-toolkit --update-lock
163
- ```
164
-
165
- Install only the `core` Custom Skills package:
166
-
167
- ```bash
168
- npx -y @ranimontagna/agent-toolkit --skills-only --codex --skills-package core
169
- ```
170
-
171
- List bundled Custom Skills and their repository scope paths:
14
+ `--all` installs the default tool set. Agent Browser remains a separate opt-in because it also provisions Chrome for Testing. See [Getting Started](docs/GETTING-STARTED.md) for interactive setup, project-local installs, and selective skill examples.
172
15
 
173
- ```bash
174
- npx -y @ranimontagna/agent-toolkit --skills-list
175
- ```
176
-
177
- Install missing selected runtime CLIs before configuring them:
178
-
179
- ```bash
180
- npx -y @ranimontagna/agent-toolkit --all --gemini --install-missing-clis
181
- ```
182
-
183
- ## Custom Skills
184
-
185
- Bundled skills live under `skills/`.
186
-
187
- ```text
188
- skills/
189
- core/
190
- agent-toolkit-maintainer/
191
- SKILL.md
192
- onboard-repo/
193
- SKILL.md
194
- backend/
195
- api/
196
- api-design/
197
- SKILL.md
198
- database/
199
- postgres-patterns/
200
- SKILL.md
201
- fastify-best-practices/
202
- SKILL.md
203
- rules/
204
- go/
205
- golang-patterns/
206
- SKILL.md
207
- golang-testing/
208
- SKILL.md
209
- java/
210
- java-coding-standards/
211
- SKILL.md
212
- java-junit/
213
- SKILL.md
214
- kotlin/
215
- kotlin-patterns/
216
- SKILL.md
217
- kotlin-testing/
218
- SKILL.md
219
- python/
220
- python-patterns/
221
- SKILL.md
222
- python-testing/
223
- SKILL.md
224
- frontend/
225
- accessibility/
226
- SKILL.md
227
- astro/
228
- astro-developer/
229
- SKILL.md
230
- architecture.md
231
- constraints.md
232
- debugging.md
233
- testing.md
234
- design/
235
- revenue-centric-design/
236
- SKILL.md
237
- assets/
238
- references/
239
- ui-ux-pro-max/
240
- SKILL.md
241
- data/
242
- scripts/
243
- gsap/
244
- gsap-core/
245
- SKILL.md
246
- gsap-frameworks/
247
- SKILL.md
248
- gsap-performance/
249
- SKILL.md
250
- gsap-plugins/
251
- SKILL.md
252
- gsap-react/
253
- SKILL.md
254
- gsap-scrolltrigger/
255
- SKILL.md
256
- gsap-timeline/
257
- SKILL.md
258
- gsap-utils/
259
- SKILL.md
260
- react-native/
261
- react-native-expert/
262
- SKILL.md
263
- react-native-unistyles-v3/
264
- SKILL.md
265
- react/
266
- react-patterns/
267
- SKILL.md
268
- rules/
269
- react-performance/
270
- SKILL.md
271
- rules/
272
- react-testing/
273
- SKILL.md
274
- rules/
275
- general/
276
- code-reviewer/
277
- SKILL.md
278
- rules/
279
- thermo-nuclear-code-quality-review/
280
- SKILL.md
281
- devops/
282
- docker-patterns/
283
- SKILL.md
284
- ```
16
+ ## Choose Tools and Runtimes
285
17
 
286
- The first path segment is a selectable package:
287
-
288
- ```text
289
- skills/<package>/<optional-scope>/<skill-name>/SKILL.md
290
- ```
291
-
292
- Runtime installs are flat even when repository paths are nested. For example,
293
- `skills/backend/java/java-junit/SKILL.md` installs as:
294
-
295
- ```text
296
- ~/.codex/skills/java-junit/
297
- ```
298
-
299
- Use `--skills-package` to select first-level packages:
300
-
301
- ```bash
302
- npx -y @ranimontagna/agent-toolkit --skills-only --codex --skills-package core
303
- ```
304
-
305
- Use `--skills-scope` to select a narrower path:
306
-
307
- ```bash
308
- npx -y @ranimontagna/agent-toolkit --skills-only --codex --skills-scope backend/java
309
- ```
310
-
311
- Use `--skills-path` to select exact individual skills:
312
-
313
- ```bash
314
- npx -y @ranimontagna/agent-toolkit \
315
- --skills-only \
316
- --codex \
317
- --skills-package backend \
318
- --skills-scope backend/python \
319
- --skills-path backend/python/python-testing
320
- ```
321
-
322
- Install only Python skills:
323
-
324
- ```bash
325
- npx -y @ranimontagna/agent-toolkit --skills-only --codex --skills-scope backend/python
326
- ```
327
-
328
- Install only Kotlin skills:
329
-
330
- ```bash
331
- npx -y @ranimontagna/agent-toolkit --skills-only --codex --skills-scope backend/kotlin
332
- ```
333
-
334
- Install only React Native skills:
335
-
336
- ```bash
337
- npx -y @ranimontagna/agent-toolkit --skills-only --codex --skills-scope frontend/react-native
338
- ```
339
-
340
- All filters can be combined. The selected package filter runs first, the scope
341
- filter narrows the result, and the path filter selects exact skills from that
342
- final list.
343
-
344
- ```bash
345
- npx -y @ranimontagna/agent-toolkit \
346
- --skills-only \
347
- --codex \
348
- --skills-package backend \
349
- --skills-scope backend/java \
350
- --skills-path backend/java/java-junit
351
- ```
352
-
353
- Each skill must be a directory containing `SKILL.md` with frontmatter:
354
-
355
- ```markdown
356
- ---
357
- name: my-skill
358
- description: Use when doing a specific kind of task.
359
- ---
360
-
361
- # My Skill
362
-
363
- Follow these steps...
364
- ```
365
-
366
- ### Included Skill Packages
367
-
368
- | Package | Skill | Source |
18
+ | Selection | CLI form | What it targets |
369
19
  |---|---|---|
370
- | `core` | `agent-toolkit-maintainer` | Maintained in this repository |
371
- | `core` | `onboard-repo` | Maintained in this repository |
372
- | `backend` | `api-design` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/api-design) under the MIT license |
373
- | `backend` | `postgres-patterns` | Adapted from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/postgres-patterns) and [`sickn33/antigravity-awesome-skills`](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/postgresql), both under the MIT license |
374
- | `backend` | `fastify-best-practices` | Copied from Matteo Collina's [`mcollina/skills`](https://github.com/mcollina/skills/tree/main/skills/fastify) under the MIT license |
375
- | `backend` | `golang-patterns` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/golang-patterns) under the MIT license |
376
- | `backend` | `golang-testing` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/golang-testing) under the MIT license |
377
- | `backend` | `java-coding-standards` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/java-coding-standards) under the MIT license |
378
- | `backend` | `java-junit` | Copied from GitHub's [`awesome-copilot`](https://github.com/github/awesome-copilot/tree/main/skills/java-junit) under the MIT license |
379
- | `backend` | `kotlin-patterns` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/kotlin-patterns) under the MIT license |
380
- | `backend` | `kotlin-testing` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/kotlin-testing) under the MIT license |
381
- | `backend` | `python-patterns` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/python-patterns) under the MIT license |
382
- | `backend` | `python-testing` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/python-testing) under the MIT license |
383
- | `devops` | `docker-patterns` | Adapted from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/docker-patterns) and [`sickn33/antigravity-awesome-skills`](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/docker-expert), both under the MIT license |
384
- | `frontend` | `accessibility` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/accessibility) under the MIT license |
385
- | `frontend` | `astro-developer` | Copied from the official [`withastro/astro`](https://github.com/withastro/astro/tree/main/.agents/skills/astro-developer) repository under the MIT license |
386
- | `frontend` | `revenue-centric-design` | Copied from Helio Costa's [`revenue-centric-design`](https://github.com/heliocosta-dev/revenue-centric-design) under source-available custom terms requiring attribution and excluding gambling/betting/casino use |
387
- | `frontend` | `ui-ux-pro-max` | Copied from Next Level Builder's [`ui-ux-pro-max-skill`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/main/.claude/skills/ui-ux-pro-max) under the MIT license |
388
- | `frontend` | `gsap-core` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-core) under the MIT license |
389
- | `frontend` | `gsap-frameworks` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-frameworks) under the MIT license |
390
- | `frontend` | `gsap-performance` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-performance) under the MIT license |
391
- | `frontend` | `gsap-plugins` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-plugins) under the MIT license |
392
- | `frontend` | `gsap-react` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-react) under the MIT license |
393
- | `frontend` | `gsap-scrolltrigger` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-scrolltrigger) under the MIT license |
394
- | `frontend` | `gsap-timeline` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-timeline) under the MIT license |
395
- | `frontend` | `gsap-utils` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-utils) under the MIT license |
396
- | `frontend` | `react-native-expert` | Copied from Jeffallan's [`claude-skills`](https://github.com/Jeffallan/claude-skills/tree/main/skills/react-native-expert) under the MIT license |
397
- | `frontend` | `react-native-unistyles-v3` | Copied from Jacek Pudysz's [`react-native-unistyles`](https://github.com/jpudysz/react-native-unistyles/tree/main/skills/react-native-unistyles-v3), declared MIT upstream |
398
- | `frontend` | `react-patterns` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/react-patterns) under the MIT license |
399
- | `frontend` | `react-performance` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/react-performance) under the MIT license |
400
- | `frontend` | `react-testing` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/react-testing) under the MIT license |
401
- | `general` | `code-reviewer` | Copied from Shubhamsaboo's [`awesome-llm-apps`](https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/awesome_agent_skills/code-reviewer) under the repository Apache-2.0 license |
402
- | `general` | `thermo-nuclear-code-quality-review` | Copied from Cursor's [`plugins`](https://github.com/cursor/plugins/tree/main/cursor-team-kit/skills/thermo-nuclear-code-quality-review) repository under the MIT license |
403
-
404
- Each React skill carries its own ECC `rules/react` references so Markdown links
405
- still resolve after the installer copies skills into flat runtime directories.
406
-
407
- The installer validates:
20
+ | Default tool set | `--all` | RTK, Caveman, Superpowers, Graphify, GSD, Improve, Frontend Skills, Planning Skills, and bundled Custom Skills |
21
+ | Agent Browser | `--agent-browser-only` | The pinned browser automation CLI, Chrome for Testing, and its matching agent skill; intentionally excluded from `--all` |
22
+ | Claude Code | `--claude` | Claude Code plugins and skills |
23
+ | Codex CLI | `--codex` | Codex plugins, skills, and local automation |
24
+ | OpenCode | `--opencode` | OpenCode skills and package-driven tools |
25
+ | Gemini CLI | `--gemini` | Gemini extensions and native skill installs |
26
+ | Antigravity | `--antigravity` | Antigravity skills and supported integrations |
408
27
 
409
- - `SKILL.md` exists;
410
- - frontmatter starts and closes with `---`;
411
- - `name` and `description` are present;
412
- - `name` uses lowercase letters, numbers and hyphens;
413
- - `description` is non-empty and under 1024 characters.
28
+ Use the interactive installer to mix individual tools. For multiple runtimes, start with `--all-runtimes` and subtract targets with `--no-<runtime>`; bare runtime selectors target only one runtime.
414
29
 
415
- Other third-party frontend skills such as Impeccable, Web Design Guidelines, React
416
- Doctor and Remotion Best Practices are not vendored as bundled Custom Skills. The
417
- `frontend-skills` tool installs them externally through the Agent Skills CLI from
418
- pinned public sources. React Doctor is installed as an agent skill integration, not automatic CI setup.
30
+ ## Safe Lifecycle Operations
419
31
 
420
- ## CLI Reference
32
+ Preview and inspect before changing an environment, then use the manifest-backed lifecycle commands when an installation needs maintenance.
421
33
 
422
- ```text
423
- Tools:
424
- --all Install every tool without the menu
425
- --rtk-only Install only RTK
426
- --caveman-only Install only Caveman
427
- --superpowers-only Install only Superpowers
428
- --graphify-only Install only Graphify
429
- --gsd-only Install only GSD
430
- --improve-only Install only shadcn Improve
431
- --agent-browser-only Install only Agent Browser
432
- --frontend-skills-only Install only third-party frontend skills
433
- --planning-skills-only Install only third-party planning skills
434
- --skills-only Install only Custom Skills
435
- --no-rtk Skip RTK
436
- --no-caveman Skip Caveman
437
- --no-superpowers Skip Superpowers
438
- --no-graphify Skip Graphify
439
- --no-gsd Skip GSD
440
- --no-improve Skip shadcn Improve
441
- --no-agent-browser Skip Agent Browser
442
- --no-frontend-skills Skip third-party frontend skills
443
- --no-planning-skills Skip third-party planning skills
444
- --no-skills Skip Custom Skills
445
-
446
- Runtimes:
447
- --all-runtimes Target Claude Code, Codex CLI, OpenCode, Gemini CLI and Antigravity
448
- --claude Target only Claude Code
449
- --codex Target only Codex CLI
450
- --opencode Target only OpenCode
451
- --gemini Target only Gemini CLI
452
- --antigravity Target only Antigravity
453
- --no-claude Skip Claude Code
454
- --no-codex Skip Codex CLI
455
- --no-opencode Skip OpenCode
456
- --no-gemini Skip Gemini CLI
457
- --no-antigravity Skip Antigravity
458
-
459
- Install scope:
460
- --global Install runtime assets into user config directories
461
- --local Install runtime assets into the current project
462
- --skills-dir DIR Use another source directory for Custom Skills
463
- --skills-package NAME Install Custom Skills from a first-level package
464
- --skills-scope SCOPE Install skills under a relative scope path
465
- --skills-path PATH Install an exact Custom Skill path
466
- --skills-list List discovered Custom Skills and exit
467
-
468
- Operations:
469
- --dry-run Print the selected install plan without changing files
470
- --plan-only Alias for --dry-run
471
- --doctor, --status Inspect selected tools and runtimes without installing
472
- --json Emit machine-readable output for supported operations
473
- --uninstall Remove files recorded in the Agent Toolkit manifest
474
- --repair Re-run selected installs and refresh the manifest
475
- --update-lock Report newer versions for pinned external sources
476
- --skills-audit Validate bundled Custom Skills metadata and links
477
-
478
- Other:
479
- --install-missing-clis Install or update selected runtime CLIs
480
- --allow-mutable-sources Allow explicit mutable package sources like @latest
481
- --help, -h Show help
482
- ```
483
-
484
- Repeat `--skills-package`, `--skills-scope` or `--skills-path` to select more
485
- than one filter.
486
-
487
- ## Configuration
488
-
489
- ```text
490
- RTK_INSTALL_DIR RTK binary install directory
491
- CAVEMAN_PACKAGE Caveman package source
492
- CAVEMAN_MODE minimal or all
493
- GRAPHIFY_PACKAGE Python package used to install Graphify
494
- GRAPHIFY_INSTALLER uv or pipx
495
- GSD_PACKAGE GSD package source
496
- SKILLS_CLI_PACKAGE npm package used for third-party skill installs
497
- GSD_SCOPE global or local
498
- TOOLS_LOCK_PATH External tool provenance lock path
499
- ALLOW_MUTABLE_SOURCES Set to 1 to allow mutable source overrides
500
- AGENT_TOOLKIT_MENU Set to plain to force the line-based interactive menu
501
- AGENT_BROWSER_PACKAGE npm package used to install Agent Browser
502
- CUSTOM_SKILLS_DIR Source directory for Custom Skills
503
- SKILLS_PACKAGE Comma-separated first-level skill package filters
504
- SKILLS_SCOPE Comma-separated skill scope filters
505
- SKILLS_PATH Comma-separated exact skill path filters
506
- ANTIGRAVITY_INSTALL_SCRIPT Official Antigravity CLI install script URL
507
- ANTIGRAVITY_SKILLS_DIR Global Antigravity skills directory
508
- ANTIGRAVITY_LEGACY_SKILLS_DIR Legacy Antigravity skills mirror directory
509
- CLAUDE_CLI_PACKAGE npm package used to install Claude Code CLI
510
- CODEX_CLI_PACKAGE npm package used to install Codex CLI
511
- OPENCODE_CLI_PACKAGE npm package used to install OpenCode CLI
512
- GEMINI_CLI_PACKAGE npm package used to install Gemini CLI
513
- ```
514
-
515
- Defaults come from `tools.lock.json`:
516
-
517
- ```text
518
- CAVEMAN_PACKAGE=github:JuliusBrussee/caveman#25d22f864ad68cc447a4cb93aefde918aa4aec9f
519
- GRAPHIFY_PACKAGE=graphifyy==0.9.11
520
- GRAPHIFY_INSTALLER=uv
521
- GSD_PACKAGE=@opengsd/gsd-core@1.6.1
522
- AGENT_BROWSER_PACKAGE=agent-browser@0.31.1
523
- SKILLS_CLI_PACKAGE=skills@1.5.13
524
- ANTIGRAVITY_INSTALL_SCRIPT=https://antigravity.google/cli/install.sh
525
- CLAUDE_CLI_PACKAGE=@anthropic-ai/claude-code@2.1.204
526
- CODEX_CLI_PACKAGE=@openai/codex@0.143.0
527
- OPENCODE_CLI_PACKAGE=opencode-ai@1.17.15
528
- GEMINI_CLI_PACKAGE=@google/gemini-cli@0.49.0
529
- ```
530
-
531
- Mutable overrides like `@latest`, unpinned npm packages or GitHub package
532
- sources without a full commit SHA are blocked unless you pass
533
- `--allow-mutable-sources` or set `ALLOW_MUTABLE_SOURCES=1`.
534
-
535
- The same explicit flag is required when an override changes the *identity* of
536
- a source (a different npm package name, GitHub repository, PyPI package or RTK
537
- release repository than the one pinned in `tools.lock.json`), and when
538
- `TOOLS_LOCK_PATH` points at an alternate lock file. `ANTIGRAVITY_INSTALL_SCRIPT`
539
- must always be an HTTPS URL — the script is piped to bash, so plain HTTP is
540
- rejected even with the flag.
541
-
542
- ## Security Model
543
-
544
- This project has two supply-chain boundaries:
34
+ | Operation | Example |
35
+ |---|---|
36
+ | Preview the selected plan without mutations | `npx -y @ranimontagna/agent-toolkit --all --codex --dry-run` |
37
+ | Inspect status for a selected runtime | `npx -y @ranimontagna/agent-toolkit --doctor --codex` |
38
+ | Emit the Doctor report as JSON | `npx -y @ranimontagna/agent-toolkit --doctor --json --codex` |
39
+ | Use the `--status` alias | `npx -y @ranimontagna/agent-toolkit --status --codex` |
40
+ | Re-run selected installs and refresh skill records | `npx -y @ranimontagna/agent-toolkit --repair --all --codex` |
41
+ | Preview manifest-backed skill removal | `npx -y @ranimontagna/agent-toolkit --uninstall --skills-only --codex --dry-run` |
42
+ | Remove recorded, validated skill paths | `npx -y @ranimontagna/agent-toolkit --uninstall --skills-only --codex` |
43
+ | Report newer candidates for pinned sources | `npx -y @ranimontagna/agent-toolkit --update-lock` |
44
+ | Audit bundled Custom Skill metadata and links | `npx -y @ranimontagna/agent-toolkit --skills-audit` |
545
45
 
546
- - repository dependencies, controlled by `pnpm-lock.yaml`, CI, `pnpm audit`,
547
- pnpm supply-chain policies and npm release provenance;
548
- - external tools installed by the runtime installer, controlled by
549
- `tools.lock.json` and runtime provenance validation.
46
+ The installer rejects mutable or re-identified external sources by default. Keep the pins in `tools.lock.json`; use `--allow-mutable-sources` only for an intentional, reviewed override.
550
47
 
551
- Repository installs are configured in `pnpm-workspace.yaml` to delay newly
552
- published package versions for 24 hours, enforce that delay strictly, reject
553
- missing registry publish timestamps, block transitive exotic package sources and
554
- fail trust downgrades for packages that previously had stronger publish
555
- evidence.
48
+ ## Current External Sources
556
49
 
557
50
  Current external sources:
558
51
 
559
- | Tool | Locked source | Runtime verification |
560
- |---|---|---|
561
- | RTK | GitHub release `rtk-ai/rtk@v0.43.0` | Verifies the selected asset SHA-256 before extraction |
562
- | Caveman | `JuliusBrussee/caveman` at commit `25d22f864ad68cc447a4cb93aefde918aa4aec9f` | Immutable GitHub npm spec |
563
- | Graphify | `graphifyy==0.9.11` | Blocks unpinned package overrides |
564
- | GSD | `@opengsd/gsd-core@1.6.1` | Blocks `@latest` unless explicitly allowed |
565
- | Agent Browser | `agent-browser@0.31.1` | Installs Chrome for Testing without automatic system dependencies |
566
- | Agent Skills | `skills@1.5.13`; `shadcn/improve@03369ee6d7cafbfcecc4346539b05b3dc0a603bb`; `vercel-labs/agent-browser@afae698a51242166170b6fe4809dd57fe9f75798`; `pbakaus/impeccable@3590bf9e37c84ecbc92f9c205ce1aebf2185a971`; `vercel-labs/agent-skills@f8a72b9603728bb92a217a879b7e62e43ad76c81`; `millionco/react-doctor@aa519e5f5505105ef8c00e1b1972c98514f7577a`; `remotion-dev/skills@8b1d51ade295b2d9bd22a8f07047d13c0740f275`; `mattpocock/skills@391a2701dd948f94f56a39f7533f8eea9a859c87`; bundles: `improve`, `agent-browser`, `frontend-skills`, `planning-skills`; skills: `improve`, `agent-browser`, `impeccable`, `web-design-guidelines`, `react-doctor`, `remotion-best-practices`, `grill-me`, `grilling`, `grill-with-docs`, `domain-modeling`, `codebase-design`, `improve-codebase-architecture` | Verifies pins before use, clones each repository once per selected bundle and continues independent skills after individual failures |
567
- | Runtime CLIs | Exact npm versions for Claude, Codex, OpenCode and Gemini | Installed or updated only when `--install-missing-clis` is enabled; Antigravity uses the official `agy` installer instead of npm |
568
-
569
- Bundled third-party skills preserve upstream attribution and license files:
570
-
571
- | Skill | Source commit | License |
572
- |---|---|---|
573
- | `api-design` | `affaan-m/ECC@2bc924faf2f8e893bfe0af86b1931283693c30ae` | MIT |
574
- | `fastify-best-practices` | `mcollina/skills@5b2a81354b6d10325da0db9decc9ce5ecc714138` | MIT |
575
- | `astro-developer` | `withastro/astro@e37dfe2a7623acd364d7e3556ecc9b31e3e45520` | MIT |
576
- | `gsap-*` | `greensock/gsap-skills@aed9cfd3277740755f6bfc1155c7aa645403b760` | MIT |
577
- | `react-native-expert` | `Jeffallan/claude-skills@e8be415bc94d8d6ebddc2fb50e5d03c6e27d4319` | MIT |
578
- | `react-native-unistyles-v3` | `jpudysz/react-native-unistyles@8b5e9fd281a81bdfd87d4fe9e6a0b042c84c5c83` | MIT |
579
- | `react-patterns` | `affaan-m/ECC@2bc924faf2f8e893bfe0af86b1931283693c30ae` | MIT |
580
- | `react-performance` | `affaan-m/ECC@2bc924faf2f8e893bfe0af86b1931283693c30ae` | MIT |
581
- | `react-testing` | `affaan-m/ECC@2bc924faf2f8e893bfe0af86b1931283693c30ae` | MIT |
582
- | `python-patterns` | `affaan-m/ECC@0f84c0e2796703fbda87d577b2636351418c7442` | MIT |
583
- | `python-testing` | `affaan-m/ECC@0f84c0e2796703fbda87d577b2636351418c7442` | MIT |
584
- | `kotlin-patterns` | `affaan-m/ECC@2bc924faf2f8e893bfe0af86b1931283693c30ae` | MIT |
585
- | `kotlin-testing` | `affaan-m/ECC@2bc924faf2f8e893bfe0af86b1931283693c30ae` | MIT |
586
-
587
- React Doctor is installed externally from `millionco/react-doctor` at a pinned
588
- commit and is documented upstream under a Modified MIT License; it is not
589
- copied into this repository.
590
-
591
- Remotion Best Practices is installed externally from `remotion-dev/skills` at a
592
- pinned commit; it is not copied into this repository.
593
-
594
- Releases use npm trusted publishing through GitHub Actions OIDC. The npm
595
- package is published without a long-lived npm token, and npm automatically
596
- generates provenance for public packages published through trusted publishing.
597
-
598
- ## Repository Layout
599
-
600
- ```text
601
- bin/
602
- agent-toolkit.ts Thin TypeScript entrypoint
603
- .github/
604
- workflows/
605
- ci.yml Quality and security gates
606
- release.yml Trusted publishing release workflow
607
- src/
608
- main.ts Installer orchestration
609
- args.ts CLI flag parsing
610
- menu.ts Interactive selection
611
- status.ts Local install status detection
612
- runtimes.ts Runtime CLI checks
613
- skills.ts Recursive skill discovery and installation
614
- installers/ Tool-specific installers
615
- dist/
616
- bin/
617
- agent-toolkit.js Compiled CLI used by npm and the wrapper
618
- docs/
619
- assets/ README terminal screenshots
620
- skills/
621
- core/
622
- agent-toolkit-maintainer/
623
- SKILL.md
624
- onboard-repo/
625
- SKILL.md
626
- backend/
627
- fastify-best-practices/
628
- SKILL.md
629
- rules/
630
- frontend/
631
- react-native/
632
- react/
633
- tests/
634
- unit/
635
- test-agent-toolkit.sh
636
- AGENTS.md Shared project rules for coding agents
637
- CLAUDE.md Pointer to AGENTS.md for Claude Code
638
- pnpm-lock.yaml Repository dependency lockfile
639
- pnpm-workspace.yaml pnpm workspace and supply-chain policy settings
640
- setup-agent-toolkit.sh Bash compatibility wrapper
641
- tools.lock.json Pinned external tool sources and RTK checksums
642
- ```
52
+ | Tool | Locked source |
53
+ |---|---|
54
+ | RTK | `rtk-ai/rtk@v0.43.0`, with a SHA-256 pin for every supported archive |
55
+ | Caveman | `JuliusBrussee/caveman@25d22f864ad68cc447a4cb93aefde918aa4aec9f` |
56
+ | Graphify | `graphifyy==0.9.11` |
57
+ | GSD | `@opengsd/gsd-core@1.6.1` |
58
+ | Agent Browser | `agent-browser@0.31.1` |
59
+ | Agent Skills CLI | `skills@1.5.13`, with each source repository pinned to a full commit |
60
+ | Runtime CLIs | `@anthropic-ai/claude-code@2.1.204`, `@openai/codex@0.143.0`, `opencode-ai@1.17.15`, and `@google/gemini-cli@0.49.0` |
643
61
 
644
- ## Development
62
+ The Agent Skills catalog exposes these locked bundle IDs and skill names:
645
63
 
646
- Prerequisites:
64
+ - `improve`: `improve`
65
+ - `agent-browser`: `agent-browser`
66
+ - `frontend-skills`: `impeccable`, `web-design-guidelines`, `react-doctor`, `remotion-best-practices`
67
+ - `planning-skills`: `grill-me`, `grilling`, `grill-with-docs`, `domain-modeling`, `codebase-design`, `improve-codebase-architecture`
647
68
 
648
- - Node.js 24+ for the full toolkit;
649
- - `npx` for Caveman, GSD, Improve and third-party frontend skills;
650
- - `git` for pinned third-party Agent Skills sources;
651
- - `pnpm` 11.x for repository development;
652
- - `npm` when using `--install-missing-clis` for npm-managed runtimes or
653
- publishing through npm trusted publishing;
654
- - `curl` and `bash` when installing Antigravity CLI through
655
- `--install-missing-clis`;
656
- - `uv` for Graphify, or `pipx` when `GRAPHIFY_INSTALLER=pipx`;
657
- - `tar` or `unzip` only when RTK needs to be downloaded;
658
- - runtime CLIs you want to target: `claude`, `codex`, `opencode`, `gemini`,
659
- `agy`.
69
+ React Doctor is installed from [`millionco/react-doctor`](https://github.com/millionco/react-doctor) at a pinned commit and is documented upstream under a Modified MIT License. It is an agent skill integration, not automatic CI setup. Remotion Best Practices is installed from [`remotion-dev/skills`](https://github.com/remotion-dev/skills) at a pinned commit.
660
70
 
661
- Install dependencies and build from a clone:
71
+ Bundled third-party skills preserve upstream attribution and license files in their skill directories. The repository catalog and immutable source pins in [`tools.lock.json`](tools.lock.json) are the source of truth.
662
72
 
663
- ```bash
664
- pnpm install
665
- pnpm run build
666
- bash setup-agent-toolkit.sh
667
- ```
73
+ ## Documentation
668
74
 
669
- Run the local Node CLI directly:
75
+ - [Getting Started](docs/GETTING-STARTED.md) — first install, tool and runtime selection, lifecycle safety, and troubleshooting
76
+ - [Architecture](docs/ARCHITECTURE.md) — CLI components, data flow, and trust boundaries
77
+ - [Configuration](docs/CONFIGURATION.md) — environment variables, defaults, and source overrides
78
+ - [Development](docs/DEVELOPMENT.md) — local setup, code style, and contribution workflow
79
+ - [Testing](docs/TESTING.md) — unit, integration, and release-gate verification
80
+ - [Deployment and Releases](docs/DEPLOYMENT.md) — tag-driven npm publishing and release recovery
81
+ - [Changelog](CHANGELOG.md) — complete version history
82
+ - [Contributing](CONTRIBUTING.md) — contribution requirements
83
+ - [Security](SECURITY.md) — vulnerability reporting and supply-chain policy
670
84
 
671
- ```bash
672
- node dist/bin/agent-toolkit.js
673
- ```
85
+ ## Development and Releases
674
86
 
675
- Quality scripts:
87
+ Install the pinned development dependencies and run the complete local gate:
676
88
 
677
89
  ```bash
678
- pnpm run build
679
- pnpm run typecheck
680
- pnpm run lint
681
- pnpm run lint:fix
682
- pnpm run format
683
- pnpm run release:patch
684
- pnpm run release:minor
685
- pnpm run release:major
686
- pnpm run security
687
- pnpm run test:unit
688
- pnpm run test:integration
689
- pnpm test
690
- pnpm run check
90
+ corepack prepare pnpm@11.8.0 --activate
91
+ pnpm install --frozen-lockfile
92
+ rtk pnpm run check
691
93
  ```
692
94
 
693
- `pnpm run check` is the release gate. It runs lint, typecheck, unit tests, build,
694
- compiled JavaScript syntax checks, Bash syntax checks and the shell integration
695
- test.
696
-
697
- The shell integration test validates the wrapper, flags, fake runtime CLIs,
698
- installer command wiring, skill discovery and public-safe reference checks.
699
-
700
- ## CI And Release
701
-
702
- GitHub Actions runs:
703
-
704
- - `Check`: lint, typecheck, unit tests, build and integration tests;
705
- - `Secret scan`: Gitleaks over full Git history;
706
- - `Dependency audit`: `pnpm install --frozen-lockfile --ignore-scripts` and
707
- `pnpm audit`;
708
- - `Dependency review`: blocks PRs that add moderate-or-higher vulnerable
709
- dependencies.
95
+ If RTK is not installed yet, run `pnpm run check` directly. The detailed workflows live in [Development](docs/DEVELOPMENT.md), [Testing](docs/TESTING.md), and [Deployment and Releases](docs/DEPLOYMENT.md); see the [Changelog](CHANGELOG.md) for the published history.
710
96
 
711
- For a manual release, update `package.json`, push the change to `main`, then
712
- push a matching tag:
713
-
714
- ```bash
715
- git tag v0.2.0
716
- git push origin v0.2.0
717
- ```
718
-
719
- For normal releases, prefer the scripted flow. It bumps `package.json`, updates
720
- the README release tag example, runs `pnpm run check`, commits with a
721
- Conventional Commit message and creates the tag. With `--push`, the helper runs
722
- the remote preflight before changing files, then atomically pushes `main` and
723
- the new tag after the checks, commit and tag succeed:
97
+ For normal releases, run the scripted patch flow:
724
98
 
725
99
  ```bash
726
100
  pnpm run release:patch -- --push
727
101
  ```
728
102
 
729
- The `Release` workflow runs the full check and publishes the scoped package to
730
- npm through trusted publishing. Dependency install and checks use pnpm, but the
731
- final publish step intentionally stays on `npm publish` because npm trusted
732
- publishing OIDC is handled by the npm CLI. Configure the npm package trusted
733
- publisher for GitHub Actions with workflow filename `release.yml` before
734
- pushing a release tag.
735
-
736
- ## Maintenance Rules
103
+ `--push` performs the remote preflight before changing files, then runs the release checks and atomically pushes `main` and the new tag.
737
104
 
738
- Keep this repository public-safe:
105
+ The `Release` workflow runs from matching version tags in GitHub Actions and publishes the package to npm through trusted publishing. See [Deployment and Releases](docs/DEPLOYMENT.md) for the complete release and recovery procedures.
739
106
 
740
- - do not add company-specific URLs, tokens, secrets or internal project names;
741
- - keep third-party skills on pinned public sources, and only vendor them when
742
- the license permits copying and the repository preserves attribution;
743
- - keep the installer idempotent;
744
- - keep `tools.lock.json` as the source of truth for external tool versions;
745
- - cover pure module behavior with Vitest;
746
- - keep the shell integration test around behavior that can regress;
747
- - document what is automatic and what still depends on each runtime CLI.
107
+ Agent Toolkit is available under the [MIT License](LICENSE).
package/SECURITY.md CHANGED
@@ -5,7 +5,9 @@ supply-chain changes need careful review.
5
5
 
6
6
  ## Reporting
7
7
 
8
- Open a GitHub security advisory or a private issue with:
8
+ Email the maintainer at
9
+ [raniellimontagna@hotmail.com](mailto:raniellimontagna@hotmail.com) instead of
10
+ opening a public issue. Include:
9
11
 
10
12
  - affected version or commit;
11
13
  - exact command used;
@@ -13,12 +15,64 @@ Open a GitHub security advisory or a private issue with:
13
15
  - relevant logs with secrets removed.
14
16
 
15
17
  Do not paste tokens, private repository URLs or internal project names into
16
- public issues.
18
+ public issues. The project does not define a response-time or remediation SLA.
17
19
 
18
- ## Project Controls
20
+ ## Dependency Integrity
19
21
 
20
- - repository dependencies are locked by `pnpm-lock.yaml`;
21
- - external installer sources are pinned in `tools.lock.json`;
22
- - mutable sources are blocked unless `--allow-mutable-sources` is explicit;
23
- - CI runs lint, typecheck, tests, build, Gitleaks and dependency audit;
24
- - npm releases use trusted publishing through GitHub Actions OIDC.
22
+ Repository dependencies resolve through `pnpm-lock.yaml`, and CI installs them
23
+ with `--frozen-lockfile`. Dependency-audit jobs install with lifecycle scripts
24
+ disabled before running the moderate-or-higher audit. See
25
+ [Architecture](docs/ARCHITECTURE.md) for the CI boundary.
26
+
27
+ ## External-Source Provenance
28
+
29
+ `tools.lock.json` is the source of truth for the external sources represented in
30
+ the lock. Package sources use exact versions, Git sources use full commits, and
31
+ RTK archives are checked against locked SHA-256 values. The RTK metadata URL may
32
+ select another non-latest tagged release in the locked repository, but the
33
+ downloaded archive must still pass the locked checksum.
34
+
35
+ Two installer paths are not content-pinned by the lock: Superpowers delegates to
36
+ runtime-native plugin or extension identifiers, and the official Antigravity
37
+ installer is identity-gated to an HTTPS URL but is not pinned by checksum or
38
+ commit. Source-identity changes, mutable versions, alternate lock files, and a
39
+ different Antigravity URL require the explicit `--allow-mutable-sources` opt-in;
40
+ that permission accepts the reviewed exception for one invocation rather than
41
+ making it immutable. See [Architecture](docs/ARCHITECTURE.md) and
42
+ [Configuration](docs/CONFIGURATION.md) for the complete boundaries.
43
+
44
+ ## Network Bounds
45
+
46
+ Toolkit-owned HTTP fetch and download helpers share a 30-second total deadline,
47
+ allow at most five redirects, reject HTTPS downgrades, and enforce response-size
48
+ limits. Downloads use an exclusive partial file and become visible at the target
49
+ path only after a complete response. External package managers, Git, and
50
+ runtime-native plugin commands retain their own network behavior. See
51
+ [Architecture](docs/ARCHITECTURE.md#transport-and-filesystem-security).
52
+
53
+ ## Filesystem Containment
54
+
55
+ Agent Skills checkouts verify the fetched commit and contain requested skill
56
+ roots inside the checkout. Toolkit-managed Custom Skill copies are staged before
57
+ replacement. Manifest-backed uninstall removes only recorded direct children of
58
+ recognized runtime roots after canonical-path and filesystem-identity checks;
59
+ containment failures preserve the manifest for review or retry. See
60
+ [Architecture](docs/ARCHITECTURE.md#manifest-and-lifecycle-boundary).
61
+
62
+ ## CI Security Gates
63
+
64
+ CI runs the full lint, typecheck, unit, build, syntax, and integration gate on
65
+ Node.js 24. Separate jobs scan full Git history with Gitleaks, audit dependencies
66
+ without lifecycle scripts, and review pull-request dependency changes at
67
+ moderate severity or higher. Contributor commands and suite ownership are in
68
+ [Testing](docs/TESTING.md).
69
+
70
+ ## npm Provenance
71
+
72
+ Tag-driven publication reruns the full gate, checks version and `main` ancestry,
73
+ and grants only read-only repository contents plus `id-token: write`. The publish
74
+ helper uses `npm publish --provenance --access public` and bounded registry
75
+ verification retries; the workflow does not use a long-lived npm token. npm-side
76
+ trusted-publisher setup and release recovery are documented in
77
+ [Deployment and Releases](docs/DEPLOYMENT.md). Released project history remains
78
+ available in the public [changelog](CHANGELOG.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ranimontagna/agent-toolkit",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Personal AI agent toolkit installer for Claude Code, Codex CLI, OpenCode, Gemini CLI, Antigravity and graph-aware workflows.",
5
5
  "type": "module",
6
6
  "engines": {