loadout-ai 0.1.2 → 0.2.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 (19) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/MASTER_PLAN.md +79 -0
  3. package/README.md +218 -330
  4. package/catalog/discovered.json +7925 -6183
  5. package/dist/src/cli.js +52 -27
  6. package/dist/src/core/access.js +42 -0
  7. package/dist/src/core/catalog-install.js +60 -12
  8. package/dist/src/core/health-score-evidence.js +8 -0
  9. package/dist/src/core/install.js +15 -12
  10. package/dist/src/core/mcp-recipes.js +37 -6
  11. package/dist/src/core/skills.js +20 -7
  12. package/dist/src/core/state.js +20 -4
  13. package/dist/src/core/update.js +111 -10
  14. package/dist/src/core/upgrade.js +1 -0
  15. package/dist/src/shared/schemas.js +8 -0
  16. package/docs/DISCOVERED.md +253 -253
  17. package/docs/FEATURE_TEST_MATRIX.md +8 -7
  18. package/docs/TESTING.md +44 -2
  19. package/package.json +2 -1
package/README.md CHANGED
@@ -1,450 +1,338 @@
1
1
  # Loadout
2
2
 
3
- **One safe CLI to discover, compare, install, update, and roll back capabilities across AI coding agents.**
3
+ **One CLI that finds, installs, updates, and rolls back useful extensions for AI coding agents.**
4
4
 
5
- Loadout turns the fragmented world of Agent Skills, MCP servers, plugins, and agent-specific directories into one screened workflow. It detects the agents on your computer, inventories what you already have, prepares capabilities from immutable Git commits, explains conflicts before writing, and snapshots every managed change.
5
+ Loadout works with Codex, Claude Code, Cursor, Gemini CLI, OpenCode, Hermes, Windsurf, Cline, GitHub Copilot, Roo Code, Kiro CLI, and Junie on macOS, Linux, and Windows.
6
6
 
7
- It supports Codex, Claude Code, Cursor, Gemini CLI, OpenCode, Hermes, Windsurf, Cline, GitHub Copilot, Roo Code, Kiro CLI, and Junie on macOS, Linux, and Windows.
7
+ It solves a simple problem: useful skills and MCP tools are scattered across hundreds of repositories. Loadout brings them into one place, checks what is actually inside, shows every change before making it, and keeps a snapshot so you can undo it.
8
8
 
9
- > Loadout is available as a public npm beta: `npm install --global loadout-ai`. The source repository remains private during hackathon testing, while the npm package includes the CLI, documentation, catalog, license, and upstream credit links.
9
+ ## Start here
10
10
 
11
- ## Why Loadout exists
12
-
13
- Useful agent extensions appear across dozens of repositories, social feeds, and incompatible marketplaces. A star count alone cannot tell you whether two collections overlap, whether a repository still works, what it will write, or how to undo the installation.
14
-
15
- Loadout gives you:
16
-
17
- - one inventory across supported agents;
18
- - a 50-repository technically screened catalog pinned to exact commits;
19
- - Stable, Power, Maximum, and Custom selection modes;
20
- - project-aware activation instead of exposing an enormous library to every prompt;
21
- - evidence-based comparison and replacement alerts;
22
- - daily read-only discovery and update checks;
23
- - explicit MCP configuration with native credential-store references;
24
- - transactional installs, integrity checks, snapshots, and rollback;
25
- - no execution of third-party repository install or lifecycle scripts.
26
-
27
- Loadout does not claim there is one universally “best” configuration. It makes the evidence, trade-offs, and exact filesystem plan visible so the user can decide.
28
-
29
- ## Install from npm
30
-
31
- Requirements: Git and Node.js 20 or newer. Pin `0.1.2` while testing the beta so every machine runs the same bytes.
32
-
33
- ```bash
34
- npm install --global loadout-ai@0.1.2
35
- loadout --help
36
- ```
37
-
38
- Start with the unified read-only preview:
11
+ You need Node.js 20 or newer and Git.
39
12
 
40
13
  ```bash
14
+ npm install --global loadout-ai@0.2.0
15
+ loadout --version
41
16
  loadout upgrade
42
17
  ```
43
18
 
44
- `upgrade` detects installed agents, inventories health, scores only evidence it can prove, scans the current project, recommends reviewed sources, fetches exact pinned commits, and prints every target and risk finding. Nothing changes until `--yes` is supplied.
19
+ `loadout upgrade` is a read-only preview. It detects your installed agents, checks what you already have, scans the current project, recommends useful additions, and shows the exact files it would change.
45
20
 
46
- ## The core journey
21
+ When the preview looks right:
47
22
 
48
23
  ```bash
49
- # 1. Preview the strongest low-risk Stable journey. Read-only.
50
- loadout upgrade --mode stable --project .
51
-
52
- # 2. Apply exactly the displayed transaction.
53
- loadout upgrade --mode stable --project . --yes
24
+ loadout upgrade --yes
25
+ ```
54
26
 
55
- # 3. Inspect and optimize the active set for this project.
56
- loadout library
57
- loadout optimize --project .
58
- loadout optimize --project . --yes
27
+ Every applied change creates a snapshot. Undo the latest change with:
59
28
 
60
- # 4. Explain health evidence, share a private aggregate card, or undo.
61
- loadout health --explain
62
- loadout card
29
+ ```bash
63
30
  loadout rollback
64
31
  ```
65
32
 
66
- `setup`, `scan`, `recommend`, and the other constituent commands remain available for advanced use. `upgrade --json` provides the same deterministic preview for automation.
33
+ ## Choose how much you want
67
34
 
68
- `--approve-risk` acknowledges findings that were already printed during preview; it does not disable safety validation. The applied operation is transactional and produces a snapshot identifier.
35
+ | Mode | Best for | What happens |
36
+ | ----------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
37
+ | **Stable** | Almost everyone | Installs 30 high-value everyday skills from four selected sources. This is the default. |
38
+ | **Power** | Users who want a larger active toolkit | Selects cross-project skills from eight major collections. The current preview prepares 50 skill directories and quarantines flagged individual skills. |
39
+ | **Maximum** | People who want the largest possible library | Downloads every usable skill in the 50-repository catalog into a disabled library. It does not flood every agent with 1,000+ active skills. |
40
+ | **Custom** | Users who know exactly what they want | Installs only the package IDs they choose. |
69
41
 
70
- For a real install-and-rollback exercise that cannot touch your profile:
42
+ Preview any mode first:
71
43
 
72
44
  ```bash
73
- loadout demo
45
+ loadout setup --mode stable
46
+ loadout setup --mode power
47
+ loadout setup --mode maximum
74
48
  ```
75
49
 
76
- The demo creates a temporary virtual Codex profile, fetches the pinned public Superpowers source, installs discovered skills, verifies managed state, rolls back, and deletes the temporary directory.
77
-
78
- ## Choose a loadout
79
-
80
- | Mode | Intended use | What it selects | Installation behavior |
81
- | ----------- | ----------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
82
- | **Stable** | Recommended daily driver | 30 selected skills from four pinned, SPDX-identified sources | Installs the selected skills into detected agents with no extra static-risk approval |
83
- | **Power** | Broad daily driver | A maintained skill-level allowlist from eight cross-project collections | Installs only the selected skills, not every skill in each collection |
84
- | **Maximum** | Exploration and maximum optionality | Every non-archived technically screened catalog record | Stores all discovered skill components in Loadout's disabled library; MCP-only records remain explicit setup steps |
85
- | **Custom** | Precise control | Only package IDs supplied by the user | Uses the same preview, safety, conflict, and transaction pipeline |
86
-
87
- Maximum is a library, not an instruction to activate everything. Use `optimize`, `activate`, `enable`, and `disable` to keep each agent's active set bounded and relevant to the current project. Loadout warns when an active set exceeds 30 skills per agent.
50
+ Apply the chosen plan only after reading it:
88
51
 
89
52
  ```bash
90
- loadout setup --mode maximum
53
+ loadout setup --mode stable --yes
54
+ loadout setup --mode power --yes --approve-risk
91
55
  loadout setup --mode maximum --yes --approve-risk
92
- loadout optimize --project . --limit 30
93
- loadout optimize --project . --limit 30 --yes
94
56
  ```
95
57
 
96
- ## Install a reviewed runtime tool: Graphify
58
+ Maximum currently finds 1,158 usable skill directories across 29 skill repositories and keeps them disabled until needed. Nineteen MCP-only repositories remain separate setup choices because MCP servers may need credentials, local software, or broader permissions.
97
59
 
98
- Graphify is not one of Stable's 30 portable skills. It is an executable codebase-intelligence tool, so Loadout gives it a separate, explicit recipe instead of silently running its repository installer. The recipe pins Graphify 0.9.17 to its reviewed Git commit and exact PyPI wheel SHA-256, isolates its Python runtime under Loadout state, strips provider credentials from installer subprocesses, snapshots every target, verifies the installed version, pins the generated runtime lookup, and supports removal.
60
+ ## How Loadout chooses repositories
99
61
 
100
- Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) first, then preview before applying:
62
+ Loadout does not install every repository above an arbitrary star count. Stars help discovery, but popularity alone cannot show whether a repository is maintained, duplicated, unsafe, incompatible, or even useful for your work.
101
63
 
102
- ```bash
103
- # See every reviewed executable recipe.
104
- loadout tool
64
+ The selection process is:
105
65
 
106
- # Preview the exact artifact, commands, permissions, and Codex target.
107
- loadout tool graphify --agents codex
108
-
109
- # Apply only after reviewing the preview.
110
- loadout tool graphify --agents codex --yes --approve-risk
66
+ 1. **Discover broadly.** Search GitHub, Hacker News, skills.sh, and the official MCP Registry.
67
+ 2. **Inspect the real contents.** Find skills, MCP declarations, plugins, commands, agents, and executable setup requirements.
68
+ 3. **Check trust evidence.** Record the exact Git commit, license status, source paths, maintenance signals, overlaps, and static safety findings.
69
+ 4. **Compare like with like.** A testing tool is compared with testing tools, not with an unrelated design skill.
70
+ 5. **Choose a tier.** Stable is the strongest bounded default; Power is broader; Maximum keeps the full reviewed library available.
71
+ 6. **Keep watching.** New candidates and changes are recorded every day, but nothing is silently promoted or installed.
111
72
 
112
- # Preview and then remove it, restoring the pre-install snapshot.
113
- loadout tool graphify --remove
114
- loadout tool graphify --remove --yes --approve-risk
115
- ```
73
+ The bundled catalog contains **50 credited public repositories** across 37 categories. Thirty-one contain skills and 19 are MCP-only. See every source, direct repository link, pinned commit, component type, and license status in **[Catalog and upstream credits](./docs/CATALOG.md)**.
116
74
 
117
- The same recipe has reviewed registration targets for Claude Code, Cursor, Gemini CLI, OpenCode, Hermes, GitHub Copilot, and Kiro CLI. Pass a comma-separated list such as `--agents codex,claude-code`; Loadout refuses requested agents it cannot detect.
75
+ Loadout does not claim there is one universally “best” configuration. “Recommended” means the strongest choice supported by the evidence and policy currently stored in Loadout, not a permanent verdict for every person or project.
118
76
 
119
- ## What Loadout manages
77
+ ## Get recommendations for the current project
120
78
 
121
- The bundled catalog currently contains **50 credited public repositories** across **37 categories**: **31 have skill components** and **19 are MCP-only**. All 50 are technically screened and pinned; four sources currently satisfy the stricter Stable recommendation policy. See every linked source, license status, component type, and pinned commit in **[Catalog and upstream credits](./docs/CATALOG.md)**.
79
+ Yes—Loadout can inspect a project and recommend what belongs in its working set.
122
80
 
123
81
  ```bash
124
- loadout catalog
125
- loadout catalog --coverage
126
- loadout catalog --history superpowers
127
- loadout search playwright
82
+ loadout recommend --project .
128
83
  ```
129
84
 
130
- Catalog admission is evidence-based. Every bundled record has an exact GitHub commit and repository-relative component evidence. Loadout reports separate trust stages—`discovered`, `inspected`, `human-reviewed`, `benchmarked`, and `recommended`—instead of calling every pinned record “best.” Stars are one bounded ranking input, not an installation threshold or a substitute for source review. Missing evidence receives no score, archived projects are not auto-selected, and unrelated categories are never presented as head-to-head alternatives.
85
+ This reads local project metadata such as `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, framework dependencies, and test configuration. It does not upload your code.
131
86
 
132
- `NOASSERTION` in the catalog means GitHub did not report an SPDX license identifier. It is a review flag—not a license grant and not an accusation. Upstream repositories and their current terms remain authoritative.
133
-
134
- ## Find what is new
135
-
136
- Discovery is deliberately separate from installation. It gathers leads and explains their evidence, but a newly popular repository cannot silently enter the trusted catalog or modify an agent.
137
-
138
- **[Today's generated discovery report](./docs/DISCOVERED.md)** lists the latest candidates with direct repository links and supporting signals. Automation refreshes that page and its machine-readable companion at `catalog/discovered.json`; the signed 50-repository release catalog remains separate.
139
-
140
- <!-- loadout:daily-discovery:start -->
141
-
142
- **Discovery snapshot (generated 2026-07-16):** [242 repositories observed](./docs/DISCOVERED.md), including 219 uncataloged review candidates and 23 repositories already in the reviewed catalog.
143
- <!-- loadout:daily-discovery:end -->
87
+ If you downloaded Maximum, use project-aware optimization to activate only the most relevant reviewed skills:
144
88
 
145
89
  ```bash
146
- # GitHub defaults to a rolling 180-day discovery window.
147
- loadout discover --source github
148
-
149
- # Public Hacker News API: current stories that link to GitHub.
150
- loadout discover --source hacker-news --min-score 20
151
- loadout discover --source hacker-news --query codex,mcp,agent
152
-
153
- # skills.sh install telemetry (requires its request-scoped VERCEL_OIDC_TOKEN,
154
- # or uses the last complete local cache).
155
- loadout discover --source skills-sh --limit 50
156
-
157
- # Official MCP Registry identity and distribution metadata.
158
- loadout discover --source mcp-registry --limit 50
159
-
160
- # Query all four sources independently and retain partial results.
161
- loadout discover --source all --queue --json
162
-
163
- # Inspect the deduplicated review queue.
164
- loadout review-queue
165
-
166
- # Triage today's generated feed with disclosed evidence.
167
- loadout candidate list --limit 20
168
-
169
- # Clone one lead, pin its commit, and statically inspect its real contents.
170
- loadout candidate inspect owner/repository --output ./candidate-dossier.json
90
+ loadout optimize --project . # preview
91
+ loadout optimize --project . --limit 30 # preview with a smaller cap
92
+ loadout optimize --project . --limit 30 --yes
171
93
  ```
172
94
 
173
- Install both daily read-only jobs with one command:
95
+ You can still override the result:
174
96
 
175
97
  ```bash
176
- loadout autopilot --time 09:00 # preview both jobs
177
- loadout autopilot --time 09:00 --yes # install both native schedules
178
- loadout autopilot --remove --yes # remove both schedules
98
+ loadout optimize --project . --pin package-id/skill-name
99
+ loadout enable package-id/skill-name --yes
100
+ loadout disable package-id/skill-name --yes
179
101
  ```
180
102
 
181
- Autopilot installs native schedules on macOS, Linux, and Windows using the pinned npm launcher for this Loadout version. It refreshes the local discovery/review queue and checks pinned package updates every day. It never installs a candidate, promotes a catalog record, or applies an update without a later explicit command and approval. Catalog membership changes only through a verified signed release.
103
+ ## Find new and better options every day
182
104
 
183
- Candidates stay in the review queue until a human decision. Shortlisting is not promotion, and promotion is not installation. Discovery state records observations over time so momentum can be measured without manufacturing a signal from a single snapshot.
105
+ Loadout has two separate daily checks:
184
106
 
185
- `candidate inspect` is the missing bridge between “this repository is moving” and “this belongs in the catalog.” It creates a path-portable dossier containing the immutable Git commit, installability (`portable-components`, `explicit-runtime-setup`, or `unsupported-source-shape`), discovered skills/rules/commands/agents/plugins/MCP declarations, static safety findings, license status, and possible overlap with catalog packages. Runtime tools such as Graphify are not mislabeled as portable skill bundles. Inspection never runs repository scripts, hooks, MCP servers, lifecycle commands, or models.
107
+ - **Discovery radar** finds new and fast-growing repositories and puts them in a review queue.
108
+ - **Update radar** checks installed Loadout packages for a newer reviewed commit, archive status, staleness, file drift, and permission changes.
186
109
 
187
- After a human reviews that dossier, Loadout can create a catalog-record proposal without editing the catalog:
110
+ Enable both at a local time of your choice:
188
111
 
189
112
  ```bash
190
- loadout candidate propose ./candidate-dossier.json \
191
- --id reviewed-id --category workflow \
192
- --platforms windows,macos,linux
193
-
194
- # Persist only after human review; this still does not mutate the catalog.
195
- loadout candidate propose ./candidate-dossier.json \
196
- --id reviewed-id --category workflow \
197
- --platforms windows,macos,linux \
198
- --approve --output ./reviewed-id.proposal.json
113
+ loadout autopilot --time 09:00 # preview
114
+ loadout autopilot --time 09:00 --yes # enable
115
+ loadout autopilot --remove --yes # remove
199
116
  ```
200
117
 
201
- See [Candidate intelligence and catalog trust](./docs/CANDIDATE_INTELLIGENCE.md) for the full admission and signed-release workflow.
118
+ Autopilot uses the native scheduler on macOS, Linux, or Windows. Scheduled jobs are read-only: they can discover and report, but they cannot install, promote, execute, or update anything.
202
119
 
203
- ## Know what is already installed
120
+ Check the results with:
204
121
 
205
122
  ```bash
206
- loadout status
207
- loadout versions
208
- loadout doctor
209
- loadout health --explain
210
- loadout capabilities
211
- loadout compare <skill-name>
212
- loadout adopt <skill-name> --agent codex
123
+ loadout review-queue
124
+ loadout candidate list --limit 20
125
+ loadout alerts --updates
126
+ loadout update
213
127
  ```
214
128
 
215
- `versions` invokes only bounded read-only `--version` commands with a sanitized environment. `health --explain` shows every scored dimension, cap, evidence item, uncertainty, and remediation; absent evidence receives zero rather than an invented neutral score.
129
+ The wording matters:
216
130
 
217
- `compare` uses fingerprints, embedded source evidence, names, capability relationships, and catalog evidence. A same-name result is a candidate match, never proof that two skills are identical. `adopt` takes Loadout ownership of one explicitly selected existing skill without changing its bytes.
131
+ - A **new lead** is interesting enough to inspect, not “must install.”
132
+ - An **available update** is a different reviewed commit, not automatically better.
133
+ - A **replacement alert** appears only when category-specific comparison evidence supports it.
218
134
 
219
- ## Project-aware activation
135
+ Loadout will never call a viral repository better just because its star count jumped. That protects users from hype, compromised repositories, and tools that solve a completely different problem.
220
136
 
221
- The cache, reviewed library, installed state, and active agent directories are separate states. Loadout can therefore retain a broad reviewed library while exposing only a small working set.
137
+ The repository also refreshes a public discovery report every day:
222
138
 
223
- ```bash
224
- loadout recommend --project .
225
- loadout activate --project . --limit 30
226
- loadout optimize --project .
227
- loadout optimize --project . --yes
228
- loadout disable <package-or-package/skill>
229
- loadout disable <package-or-package/skill> --yes
230
- loadout enable <package-or-package/skill>
231
- loadout enable <package-or-package/skill> --yes
232
- ```
233
-
234
- Dry-run is the default for mutations. Activation refuses unmanaged packages, drifted files, incomplete library copies, quarantined entries, and occupied targets.
139
+ <!-- loadout:daily-discovery:start -->
235
140
 
236
- ## MCP without hidden execution
141
+ **Discovery snapshot (generated 2026-07-17):** [242 repositories observed](./docs/DISCOVERED.md), including 219 uncataloged review candidates and 23 repositories already in the reviewed catalog.
142
+ <!-- loadout:daily-discovery:end -->
237
143
 
238
- Loadout separates four actions that other installers often blur together:
144
+ See **[today's generated discovery report](./docs/DISCOVERED.md)** for direct links, observed star velocity, age, license metadata, and the searches that found each repository. The GitHub README updates when the daily workflow commits new evidence; an already-installed npm package keeps its own versioned documentation until the next npm release.
239
145
 
240
- 1. inspect MCP evidence;
241
- 2. preview a configuration change;
242
- 3. apply that exact configuration with explicit risk approval;
243
- 4. optionally launch one exact reviewed artifact for a bounded JSON-RPC connection check.
146
+ Inspect a promising lead without running its code:
244
147
 
245
148
  ```bash
246
- loadout mcp --repository upstash/context7
247
- loadout mcp-recipe playwright --config ./mcp.json
248
- loadout mcp-recipe playwright --config ./mcp.json --verify
249
- loadout mcp-recipe playwright --connect --approve-risk
149
+ loadout discover --source all --queue
150
+ loadout review-queue
151
+ loadout candidate inspect owner/repository --output ./candidate-dossier.json
250
152
  ```
251
153
 
252
- Credential-bearing recipes can reference the native OS credential store. Secrets are accepted through stdin, never written into Loadout JSON state, and injected only into the approved child process:
253
-
254
- ```bash
255
- printf '%s' "$GITHUB_PERSONAL_ACCESS_TOKEN" \
256
- | loadout credentials set loadout.github --stdin
154
+ The dossier records what the repository contains, its exact commit, its license signal, possible overlaps, and static findings. Promotion into the catalog still requires review.
257
155
 
258
- loadout mcp-recipe github-readonly --connect --approve-risk \
259
- --credential GITHUB_PERSONAL_ACCESS_TOKEN=keychain:loadout.github
260
- ```
156
+ ## Chat subscriptions and API keys
261
157
 
262
- Native backends are macOS Keychain, Linux Secret Service, and Windows Credential Manager. `mcp-recipe --connect` is opt-in, time-bounded, signal-cleaned, and restricted to the recipe's exact reviewed pin. General repository setup never launches third-party processes.
158
+ A ChatGPT Plus/Pro or Claude Pro/Max subscription is not the same as separately billed API access. You do **not** need an OpenAI, Anthropic, or OpenRouter API key for Stable, Power, Maximum, discovery, project recommendations, updates, or rollback.
263
159
 
264
- ## Reproducible team loadouts
160
+ Tell non-interactive setup what separately billed API access is available without passing a secret:
265
161
 
266
162
  ```bash
267
- loadout init --name my-team
268
- loadout add superpowers
269
- loadout lock
270
- loadout sync --manifest loadout.json # preview
271
- loadout sync --manifest loadout.json --yes # apply transactionally
272
- loadout audit --manifest loadout.json --lock loadout.lock
273
- loadout export team.loadout.json --manifest loadout.json --lock loadout.lock
274
- loadout import team.loadout.json # preview
163
+ loadout setup --mode stable --api-access none
164
+ loadout setup --mode maximum --api-access openai,anthropic
275
165
  ```
276
166
 
277
- Manifests resolve catalog packages, Git repositories, local sources, and exact registry descriptors. Dependency cycles, incompatible versions, missing requirements, unsafe paths, and portable exports containing absolute local package paths are rejected. Imports do not silently replace files and snapshot destinations before an approved overwrite.
278
-
279
- ## Updates, evidence, and recovery
167
+ Loadout never treats API access as permission to install an MCP server. Credentialed MCP tools remain explicit setup steps, and configuration stores an environment-variable or OS-keychain reference rather than the secret value.
280
168
 
281
169
  ```bash
282
- loadout alerts
283
- loadout update
284
- loadout update --package <package-id> --apply
285
- loadout watch
286
- loadout rollback
287
- loadout audit --manifest loadout.json --lock loadout.lock
288
- ```
170
+ export LOADOUT_GITHUB_TOKEN="$GITHUB_PERSONAL_ACCESS_TOKEN"
289
171
 
290
- Updates are planned before they are applied. Loadout checks managed hashes, reviewed commits, archive status, staleness evidence, permission changes, and replacement evidence. It will not treat a newer commit or a faster-growing repository as automatically safer or better.
172
+ loadout mcp-recipe github-readonly --config ./mcp.json \
173
+ --credential GITHUB_PERSONAL_ACCESS_TOKEN=env:LOADOUT_GITHUB_TOKEN
291
174
 
292
- `rollback` restores the most recent snapshot by default, or a specific snapshot with `--snapshot <id>`. Removal and configuration changes preserve unrelated files and unrelated MCP keys.
293
-
294
- ## Reproducible evaluation and shareable evidence
295
-
296
- Loadout now includes the versioned [Evaluation Protocol v1](./docs/EVALUATION_PROTOCOL_V1.md). A campaign can be validated, deterministically scheduled, and worst-case priced without contacting a model provider:
297
-
298
- ```bash
299
- loadout benchmark plan ./campaign.json
300
- loadout benchmark plan ./campaign.json \
301
- --run-id first-run --output ./benchmark-run.json --json
175
+ loadout mcp-recipe github-readonly --config ./mcp.json \
176
+ --credential GITHUB_PERSONAL_ACCESS_TOKEN=env:LOADOUT_GITHUB_TOKEN \
177
+ --yes
302
178
  ```
303
179
 
304
- Planning rejects unbounded or edited metadata and writes a resumable, content-free run record. It does **not** make a model call. The isolated paid runner and real fixture evidence remain separate release gates; Loadout will not label a source benchmarked from a plan alone.
180
+ ## Graphify and other executable tools
305
181
 
306
- Generate or compare privacy-safe aggregate artifacts:
182
+ Graphify is included as a separate reviewed tool recipe, not disguised as a portable skill. Its setup uses a pinned version and artifact hash, an isolated runtime, an exact preview, and rollback.
307
183
 
308
184
  ```bash
309
- loadout report --json > before.json
310
- loadout card --output LOADOUT_CARD.md
311
- loadout report --json > after.json
312
- loadout compare-loadouts before.json after.json
185
+ loadout tool
186
+ loadout tool graphify --agents codex
187
+ loadout tool graphify --agents codex --yes --approve-risk
188
+ loadout tool graphify --remove
313
189
  ```
314
190
 
315
- The card excludes project paths and names, prompts, code, filenames, repository names, and credentials. Its Agent Health Score reports evidence coverage and explicitly does not claim universal quality or task improvement.
316
-
317
- ## Supported agents and platforms
318
-
319
- | Agent | Skill management | Additional native/adapted components |
320
- | -------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- |
321
- | Codex | Native | Agents and scoped root files are native; commands, MCP, and plugin contents are adapted |
322
- | Claude Code | Native | Commands, agents, and scoped root files are native; MCP and plugin contents are adapted |
323
- | Cursor | Native | Rules, commands, agents, and scoped root files are native; MCP and plugin contents are adapted |
324
- | Gemini CLI | Native | Commands and scoped root files are native; plugin contents are adapted |
325
- | OpenCode | Native, at `~/.config/opencode/skills` | Commands, agents, and scoped root files are native; plugin contents are adapted |
326
- | Hermes | Native | Skills are the currently claimed automatic install path |
327
- | Windsurf | Yes, at `~/.codeium/windsurf/skills` | Skills only |
328
- | Cline | Yes, at `~/.cline/skills` | Skills only |
329
- | GitHub Copilot | Yes, at `~/.copilot/skills` | Skills only |
330
- | Roo Code | Yes, at `~/.roo/skills` | Skills only |
331
- | Kiro CLI | Yes, at `~/.kiro/skills` | Skills only |
332
- | Junie | Yes, at `~/.junie/skills` | Skills only |
333
-
334
- Run `loadout capabilities` for the authoritative `native`, `adapted`, or `unsupported` matrix used by the planner itself. `loadout capabilities --gaps` turns every unsupported combination into an evidence-gated engineering backlog; unsupported components are skipped rather than falsely converted.
335
-
336
- macOS, Linux, and native Windows paths are supported. WSL is intentionally treated as Linux and uses its POSIX `$HOME`; Loadout never silently crosses into the Windows profile under `/mnt/c`. `LOADOUT_USER_HOME` and `LOADOUT_HOME` provide isolated roots for testing.
337
-
338
- ## Safety model
339
-
340
- - **Preview first:** mutating commands are dry-run by default.
341
- - **Immutable input:** screened sources are fetched at exact commits and verified.
342
- - **Narrow copying:** setup copies discovered component directories; it does not run repository installers.
343
- - **Transactional writes:** a failed multi-package operation restores prior state.
344
- - **Owned-file boundaries:** remove and rollback touch only recorded managed targets.
345
- - **Integrity checks:** drift blocks unsafe enable, update, and removal operations.
346
- - **Conflict handling:** exact target collisions are resolved deterministically and reported; evidenced hard conflicts block the operation.
347
- - **Secret boundaries:** credential values stay in the native OS store and out of manifests, lockfiles, reports, and logs.
348
- - **Honest adapters:** the installer and capability report share the same compatibility matrix.
349
- - **Explicit execution:** sandbox commands and real MCP connection checks require separate approval.
350
-
351
- Read [Compatibility policy](./docs/COMPATIBILITY_POLICY.md), [Active-set contract](./docs/ACTIVE_SET.md), [Provenance and comparison](./docs/PROVENANCE_AND_COMPARISON.md), and [Credential and update policy](./docs/CREDENTIAL_AND_UPDATE_POLICY.md) for the precise contracts.
352
-
353
- ## Command map
354
-
355
- | Goal | Commands |
356
- | ---------------------- | ------------------------------------------------------------------------------------ |
357
- | Onboard | `upgrade`, `setup`, `scan`, `status`, `versions`, `health`, `demo` |
358
- | Find and compare | `catalog`, `search`, `discover`, `candidate`, `review-queue`, `compare`, `recommend` |
359
- | Manage active skills | `library`, `activate`, `optimize`, `enable`, `disable`, `adopt` |
360
- | Maintain safely | `health`, `alerts`, `update`, `watch`, `remove`, `rollback`, `audit` |
361
- | Share desired state | `init`, `add`, `unadd`, `lock`, `sync`, `export`, `import` |
362
- | Configure MCP | `mcp`, `mcp-config`, `codex-mcp-config`, `mcp-recipe` |
363
- | Credentials and models | `credentials`, `models` |
364
- | Evaluate evidence | `benchmark`, `inspect`, `evaluate`, `head-to-head`, `canary`, `outcome` |
365
- | Share safe evidence | `report`, `share`, `card`, `compare-loadouts` |
366
- | Package and registry | `create`, `pack`, `publish`, `registry-serve` |
367
- | Operate | `completion`, `autopilot`, `schedule`, `unschedule`, `tool`, `dashboard`, `serve` |
368
-
369
- Use `loadout <command> --help` for exact options. Shell completion is available for Bash, Zsh, Fish, and PowerShell:
191
+ Executable tools and MCP servers receive separate treatment because they can run processes, use credentials, or open network connections. Broad setup never runs third-party repository installers.
192
+
193
+ ## Useful commands
194
+
195
+ | Goal | Command |
196
+ | ----------------------------------------- | --------------------------------------------- |
197
+ | See the guided upgrade | `loadout upgrade` |
198
+ | Install a loadout | `loadout setup --mode stable\|power\|maximum` |
199
+ | See detected agents and installed skills | `loadout status` |
200
+ | Inspect health and evidence | `loadout health --explain` |
201
+ | Browse the reviewed catalog | `loadout catalog` |
202
+ | Search by capability | `loadout search <words>` |
203
+ | Recommend for a project | `loadout recommend --project .` |
204
+ | Activate relevant library skills | `loadout optimize --project .` |
205
+ | Find new repositories | `loadout discover --source all --queue` |
206
+ | Read the discovery queue | `loadout review-queue` |
207
+ | Check installed changes | `loadout alerts --updates` |
208
+ | Preview updates | `loadout update` |
209
+ | Undo the latest applied change | `loadout rollback` |
210
+ | Test safely without touching your profile | `loadout demo` |
211
+ | See every command | `loadout --help` |
212
+
213
+ Shell completion is available for Bash, Zsh, Fish, and PowerShell:
370
214
 
371
215
  ```bash
372
216
  loadout completion zsh > ~/.zfunc/_loadout
373
217
  ```
374
218
 
375
- ## How it works
376
-
377
- ```mermaid
378
- flowchart LR
379
- A["Detect and scan agents"] --> B["Select screened sources"]
380
- B --> C["Fetch exact Git commits"]
381
- C --> D["Inspect skills and MCP evidence"]
382
- D --> E["Resolve overlaps and safety findings"]
383
- E --> F["Preview exact targets"]
384
- F --> G{"Explicit approval?"}
385
- G -->|No| H["No profile mutation"]
386
- G -->|Yes| I["Snapshot and transactional apply"]
387
- I --> J["Hash verification, health, rollback"]
388
- ```
219
+ ## What Loadout changes
389
220
 
390
- Loadout state lives outside the repository under `~/.loadout` by default. Agent content is written only to the detected agent's documented user directory. The optional dashboard is a loopback diagnostics surface; the full product journey remains available through the CLI.
221
+ Before any managed write, Loadout:
391
222
 
392
- ## Test everything before touching a real profile
223
+ 1. fetches the exact reviewed Git commit;
224
+ 2. inspects the selected contents;
225
+ 3. resolves duplicate target names;
226
+ 4. prints safety findings and every destination;
227
+ 5. waits for explicit approval;
228
+ 6. snapshots the old state;
229
+ 7. applies the change as one transaction;
230
+ 8. records hashes for later drift checks and rollback.
393
231
 
394
- The automated tests use disposable Loadout and user homes.
232
+ Loadout state lives under `~/.loadout` by default. It never executes arbitrary third-party install scripts during broad setup. Maximum stores additional skills in a disabled library, and invalid individual skills are quarantined without discarding their safe siblings.
395
233
 
396
- ```bash
397
- npm run verify
398
- ```
399
-
400
- `verify` runs formatting, lint, typechecking, catalog/discovery evidence checks, all
401
- unit and integration tests, the real CLI product flow, an installed npm-tarball smoke
402
- test, and the 1,000-skill performance gate. Use `npm run verify:full` to include the
403
- optional Playwright dashboard check.
404
-
405
- Then follow **[the complete feature test matrix](./docs/FEATURE_TEST_MATRIX.md)** to
406
- exercise every CLI command and authority boundary, or the shorter **[disposable
407
- end-to-end guide](./docs/TESTING.md)** for Power/Maximum, optimization, lifecycle, and
408
- rollback on virtual Codex and Claude Code profiles.
409
-
410
- ## Current limits
411
-
412
- - The npm package is prepared but not yet published.
413
- - The bundled catalog is technically screened and finite; only the stricter Stable subset is currently marked recommended, and discovery leads do not auto-promote themselves.
414
- - Public GitHub is the default source. Private GitHub discovery requires explicit authorization through an environment or native credential reference.
415
- - Skill components are the only components installed automatically by broad setup. MCP-only records require an explicit recipe or configuration target.
416
- - Executable tools are never smuggled into broad setup. Graphify has a separately previewed, pinned, credential-isolated, reversible runtime recipe; additional runtime tools still require the same reviewed-recipe treatment.
417
- - Six catalog records currently have `NOASSERTION` license status and need upstream-license review before a public release decision.
418
- - Additional component types are installed only where the adapter reports tested support. Loadout does not promise perfect conversion of arbitrary hooks, subagents, plugins, or proprietary formats.
419
- - The included registry server is for local development or self-hosting. No public Loadout registry service is deployed.
420
- - Ranking and evaluation explain bounded evidence; they do not scientifically prove that one configuration is best for every person or task.
421
- - Benchmark campaign planning is implemented, but no bundled source is called benchmarked until the isolated runner, real fixtures, and signed promotion evidence are complete.
234
+ ## Test the product
422
235
 
423
- ## Contributing
236
+ Run a real install-and-rollback flow in a temporary Codex profile:
424
237
 
425
- Catalog additions need more than popularity. A proposal should include an immutable commit, inspectable component evidence, license status, supported platforms, category/overlap analysis, and a reason it improves the existing catalog. Discovery candidates should pass review before promotion.
238
+ ```bash
239
+ loadout demo
240
+ ```
426
241
 
427
- Before opening a pull request:
242
+ For contributors:
428
243
 
429
244
  ```bash
245
+ npm ci
430
246
  npm run verify
431
247
  ```
432
248
 
433
- Useful references:
249
+ `verify` checks formatting, lint, types, catalog evidence, unit and integration tests, a real CLI product flow, an installed-package smoke test, and a 1,000-skill performance gate.
250
+
251
+ Use the **[product testing guide](./docs/TESTING.md)** for Power, Maximum, project optimization, credentials, and rollback. Use the **[complete feature matrix](./docs/FEATURE_TEST_MATRIX.md)** when you want to exercise every CLI feature and understand which commands read files, use the network, start processes, or write state.
252
+
253
+ No bundled source is called benchmarked until real isolated trials, signed evidence, and human approval exist.
254
+
255
+ ## Current beta limits
256
+
257
+ - Daily discovery creates leads; it does not automatically make them trusted catalog entries.
258
+ - Replacement alerts need real comparison evidence. Loadout does not invent a winner from stars or recency.
259
+ - MCP-only records need explicit configuration and may need external credentials or software.
260
+ - Graphify is the first fully reviewed executable recipe; other runtime tools need equivalent recipe work.
261
+ - Six catalog records currently have `NOASSERTION` license metadata and should be reviewed before relying on their license status.
262
+ - The local registry works for development and self-hosting; there is no hosted Loadout registry service yet.
263
+ - The optional dashboard exists for diagnostics, but the complete product is CLI-first.
264
+
265
+ ## More detail
266
+
267
+ <details>
268
+ <summary><strong>All 50 upstream projects credited by Loadout</strong></summary>
269
+
270
+ - [Superpowers](https://github.com/obra/superpowers)
271
+ - [Context7](https://github.com/upstash/context7)
272
+ - [Playwright MCP](https://github.com/microsoft/playwright-mcp)
273
+ - [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)
274
+ - [GitHub MCP Server](https://github.com/github/github-mcp-server)
275
+ - [OpenAI Skills Catalog](https://github.com/openai/skills)
276
+ - [Anthropic Skills](https://github.com/anthropics/skills)
277
+ - [Agent Skills Marketplace](https://github.com/wshobson/agents)
278
+ - [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)
279
+ - [Vercel Skills](https://github.com/vercel-labs/skills)
280
+ - [Cloudflare MCP Server](https://github.com/cloudflare/mcp-server-cloudflare)
281
+ - [Supabase MCP](https://github.com/supabase/mcp)
282
+ - [Sentry MCP](https://github.com/getsentry/sentry-mcp)
283
+ - [Exa MCP Server](https://github.com/exa-labs/exa-mcp-server)
284
+ - [Firecrawl MCP Server](https://github.com/firecrawl/firecrawl-mcp-server)
285
+ - [Azure DevOps MCP](https://github.com/microsoft/azure-devops-mcp)
286
+ - [Docker MCP Gateway](https://github.com/docker/mcp-gateway)
287
+ - [Hugging Face MCP Server](https://github.com/huggingface/hf-mcp-server)
288
+ - [Awesome Copilot](https://github.com/github/awesome-copilot)
289
+ - [OpenAI Codex Skills](https://github.com/openai/codex)
290
+ - [Ponytail](https://github.com/DietrichGebert/ponytail)
291
+ - [Addy Osmani Agent Skills](https://github.com/addyosmani/agent-skills)
292
+ - [Scientific Agent Skills](https://github.com/K-Dense-AI/scientific-agent-skills)
293
+ - [Planning with Files](https://github.com/OthmanAdi/planning-with-files)
294
+ - [PM Skills](https://github.com/phuryn/pm-skills)
295
+ - [Baoyu Skills](https://github.com/JimLiu/baoyu-skills)
296
+ - [Trail of Bits Skills](https://github.com/trailofbits/skills)
297
+ - [Antfu Skills](https://github.com/antfu/skills)
298
+ - [.NET Skills](https://github.com/dotnet/skills)
299
+ - [Microsoft Skills](https://github.com/microsoft/skills)
300
+ - [Web Quality Skills](https://github.com/addyosmani/web-quality-skills)
301
+ - [Softaworks Agent Toolkit](https://github.com/softaworks/agent-toolkit)
302
+ - [Draw.io Skill](https://github.com/Agents365-ai/drawio-skill)
303
+ - [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
304
+ - [Serena](https://github.com/oraios/serena)
305
+ - [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers)
306
+ - [AWS MCP Servers](https://github.com/awslabs/mcp)
307
+ - [DBHub](https://github.com/bytebase/dbhub)
308
+ - [FastAPI MCP](https://github.com/tadata-org/fastapi_mcp)
309
+ - [Browser MCP](https://github.com/BrowserMCP/mcp)
310
+ - [AntV Chart MCP](https://github.com/antvis/mcp-server-chart)
311
+ - [Excel MCP Server](https://github.com/haris-musa/excel-mcp-server)
312
+ - [arXiv MCP Server](https://github.com/blazickjp/arxiv-mcp-server)
313
+ - [Google Workspace MCP](https://github.com/taylorwilsdon/google_workspace_mcp)
314
+ - [MongoDB MCP Server](https://github.com/mongodb-js/mongodb-mcp-server)
315
+ - [Redis MCP Server](https://github.com/redis/mcp-redis)
316
+ - [Stripe AI](https://github.com/stripe/ai)
317
+ - [MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox)
318
+ - [Browserbase MCP Server](https://github.com/browserbase/mcp-server-browserbase)
319
+ - [Bright Data MCP](https://github.com/brightdata/brightdata-mcp)
320
+
321
+ Thank you to every maintainer and contributor. Inclusion is attribution and discovery metadata, not ownership, endorsement, or relicensing.
322
+
323
+ </details>
434
324
 
435
325
  - [Catalog and all upstream credits](./docs/CATALOG.md)
436
326
  - [Daily generated discovery report](./docs/DISCOVERED.md)
327
+ - [How candidates are inspected and promoted](./docs/CANDIDATE_INTELLIGENCE.md)
437
328
  - [Catalog ranking and conflict policy](./docs/CATALOG_POLICY.md)
329
+ - [Security policy](./SECURITY.md)
438
330
  - [Testing guide](./docs/TESTING.md)
439
331
  - [Complete CLI feature test matrix](./docs/FEATURE_TEST_MATRIX.md)
440
- - [Evaluation protocol](./docs/EVALUATION_PROTOCOL.md)
441
- - [Community discovery policy](./docs/COMMUNITY_DISCOVERY.md)
442
- - [Candidate intelligence and signed catalog trust](./docs/CANDIDATE_INTELLIGENCE.md)
443
- - [Security policy](./SECURITY.md)
444
- - [Canonical engineering plan](./MASTER_PLAN.md)
332
+ - [Engineering master plan](./MASTER_PLAN.md)
445
333
 
446
334
  ## License
447
335
 
448
- Loadout itself is licensed under the [MIT License](./LICENSE). Catalog entries remain governed by their respective upstream licenses and terms; inclusion is attribution and discovery metadata, not relicensing.
336
+ Loadout is licensed under the [MIT License](./LICENSE). Catalog entries keep their own upstream licenses and terms; Loadout links and credits them but does not relicense them.
449
337
 
450
338
  Built for the OpenAI Build Week **Developer Tools** category.