loadout-ai 0.5.9 → 0.7.0

package/README.md

@@ -8,7 +8,8 @@
 
 <p align="center">
   <strong>The package manager for your AI coding setup.</strong><br>
-  Discover broadly. Activate the right tools for each project. Stay current without starting over.
+  Install skills across 12 agents. Route each task to the right model.<br>
+  Hand work between Claude Code and Codex. Undo any of it.
 </p>
 
 <p align="center">
@@ -21,20 +22,53 @@
 </p>
 
 <p align="center">
+  <a href="#what-it-looks-like">See it</a> ·
   <a href="#install">Install</a> ·
-  <a href="#why-loadout">Why Loadout</a> ·
-  <a href="#profiles">Profiles</a> ·
-  <a href="#catalog-and-discovery">Discover</a> ·
+  <a href="#use-it-from-inside-your-agent">Use it in your agent</a> ·
+  <a href="#working-across-two-agents">Two agents</a> ·
+  <a href="#why-loadout">Why</a> ·
   <a href="#trust-and-limits">Trust</a> ·
   <a href="#command-reference">Commands</a>
 </p>
 
+## What it looks like
+
+```console
+$ loadout status
+Loadout — grade A: Healthy and up to date
+
+✓ Claude Code
+  ~/.claude/skills
+  582 items | supports: skill, command, agent, mcp, plugin, root
+✓ Codex
+  ~/.agents/skills
+  83 items | supports: skill, command, agent, mcp, plugin, root
+
+$ loadout route implement the payment webhook handler
+Phase:    implement
+Tier:     Standard (balanced)
+Models:   Claude Sonnet 5 ($3/$15)
+          GPT-5.6 Terra ($2/$12)
+Agents:   claude-code, codex
+Why:      Implementation is high-volume; standard models score within 5% of frontier
+
+Conserve: drop to fast tier (GPT-5.6 Luna at $0.2/$1.2)
+          May need more iterations on complex logic; fine for CRUD and boilerplate
+
+Hand off:
+  loadout handoff send codex 'implement the payment webhook handler'
+```
+
+Three things most agent tools do not do: it knows which agents you actually have,
+it prices the tradeoff before you spend the tokens, and every mutating command
+previews first and snapshots before it writes.
+
 ## Install
 
 You need Node.js 20 or newer and Git.
 
 ```bash
-npm install --global loadout-ai@0.5.9
+npm install --global loadout-ai
 loadout setup --mode stable
 ```
 
@@ -42,6 +76,46 @@ The second command detects your agents and previews the 30-skill Stable loadout.
 Nothing changes until you approve it. If anything goes wrong, start with the
 [user test guide](./docs/USER_TEST_GUIDE.md).
 
+For a reproducible install, pin the release: `npm install --global loadout-ai@0.7.0`.
+
+## Use it from inside your agent
+
+A CLI you have to leave your agent to run is a context switch. Loadout ships its
+own skill so you do not have to:
+
+```bash
+loadout skills install loadout-router --yes
+```
+
+Start a new agent session and just ask, in the conversation you are already in:
+
+> _"Which model should I use to refactor this auth module?"_
+> _"I'm running low on usage — what should I switch to?"_
+> _"Hand the test writing to Codex."_
+
+The skill teaches your agent to call `loadout route` and `loadout handoff` and act
+on the results. It wraps the CLI rather than embedding a copy of the model table,
+so pricing and model coverage update when Loadout updates instead of going stale
+in a markdown file.
+
+`loadout skills list` shows what ships with Loadout and what is already installed.
+
+## Working across two agents
+
+If you pay for both Claude and a ChatGPT plan, the two agents cannot see each
+other. Loadout gives them a shared, append-only task log:
+
+```bash
+loadout handoff init
+loadout handoff send codex "write unit tests for auth" --context "see src/auth.ts"
+loadout handoff pickup --yes
+```
+
+`pickup` writes a small managed block into `CLAUDE.md` and `AGENTS.md` telling each
+agent to check `loadout handoff inbox <agent>` at the start of a session. Only the
+text between the `loadout:handoff` markers is managed; the rest of your file is left
+alone, and re-running replaces that block instead of duplicating it.
+
 ## How it works
 
 **Choose -> Inspect -> Preview -> Apply -> Undo**
@@ -54,23 +128,37 @@ Nothing changes until you approve it. If anything goes wrong, start with the
 
 ### Abridged terminal transcript
 
-This is an explicitly abridged transcript from a disposable, single-Codex Stable run. A literal `…` marks omitted fetch output; `<snapshot-id>` is a variable placeholder because snapshot IDs vary.
+This is an explicitly abridged transcript from a disposable Stable run. A literal `…` marks omitted fetch output; `<snapshot-id>` is a variable placeholder because snapshot IDs vary. Loadout auto-detects installed agents; `--agents` narrows the selection when needed.
 
 ```console
-$ loadout setup --mode stable --agents codex
+$ loadout setup --mode stable
 …
-Loadout: Stable Boost
-Detected agents: Codex
+Loadout: Stable
+Detected agents: Claude Code, Cursor, Codex
 Catalog selection: 4 repositories
 Ready to install: 4 skill repositories (30 agent skill directories)
 Preview complete; nothing was changed. Re-run with --yes to install this exact screened plan.
 
-$ loadout setup --mode stable --agents codex --yes
+$ loadout setup --mode stable --yes
 …
-Loadout installed 4 repositories for 1 agent(s). Snapshot: <snapshot-id>
+Loadout installed 4 repositories for 3 agent(s). Snapshot: <snapshot-id>
 
 $ loadout rollback
 Restored snapshot <snapshot-id>
+
+$ loadout route design the authentication system
+Phase:    plan
+Tier:     Frontier (deep reasoning)
+Models:   Claude Opus 5 ($5/$25)
+          GPT-5.6 Sol ($5/$30)
+Agents:   claude-code
+Why:      Architecture and decomposition need deep reasoning to avoid costly rework
+
+$ loadout doctor
+loadout doctor — HEALTHY
+Platform:   darwin
+State:      ~/.loadout ✓ writable
+Agents:     3 detected, 9 available
 ```
 
 The final preview sentence above is captured CLI wording. A later `--yes` invocation recomputes the plan from pinned sources and current agent and filesystem state; it does not persist or prove identity with the earlier preview.
@@ -92,6 +180,12 @@ coding agents without making you rebuild the setup for every agent and every pro
 Most extension tools begin with a repo you already know. Loadout begins one step
 earlier: **what is actually worth knowing?** It stays with you after installation.
 
+Everything on this page is enforced. `docs/evidence/readme-claims.json` records
+each material claim with the code or command that proves it, and CI fails the
+build when the README and the implementation disagree — including the pinned
+version in the install line above. A README that cannot drift is a strange thing
+to build, and it is the reason the rest of this page is worth believing.
+
 Loadout watches a much wider catalog than it activates. You can keep thousands of
 technically screened skill copies in the disabled Maximum library, discover new projects as
 they appear, and let each codebase pull a focused active set instead of dumping
@@ -106,9 +200,9 @@ everything into every prompt.
 | Hope updates do not break anything                             | Preview updates and protect every managed change with a snapshot |
 | Manually remember what was changed                             | Scan, reconcile, remove, roll back, or completely uninstall      |
 
-Loadout is local, open source, and preview-first. It does not need an OpenAI or
-Anthropic API key to manage skills. MCP servers and executable tools stay behind
-their own explicit setup and permission steps.
+Loadout is local, open source, and preview-first. It does not need an LLM API key
+to manage skills. MCP servers and executable tools stay behind their own explicit
+setup and permission steps.
 
 ### Demo
 
@@ -128,7 +222,7 @@ you can run yourself.
 
 ## Stable workflow
 
-### Stable Boost: install the essentials and start building
+### Stable: install the essentials and start building
 
 Stable is the recommended daily driver: **30 selected skill directories from four
 pinned public sources**, installed into each agent you choose. It covers planning,
@@ -185,9 +279,31 @@ checked by `loadout update` without moving them to a different agent path.
 
 ## Profiles
 
-Loadout is opinionated when you want it to be and precise when you do not.
+Loadout is opinionated when you want it to be and precise when you do not. The
+modes differ in one thing: how much of the reviewed catalog they install.
+
+| Mode      | Sources               | Skills | Active by default                |
+| --------- | --------------------- | ------ | -------------------------------- |
+| `stable`  | 4                     | 30     | yes — recommended starting point |
+| `power`   | 8                     | 56     | yes                              |
+| `maximum` | all reviewed          | all    | **no — downloaded but disabled** |
+| `custom`  | your `--package` list | varies | yes                              |
 
-### Power Boost: a larger cross-project toolkit
+**Maximum is the one worth understanding.** It downloads the entire reviewed
+library and leaves every skill _disabled_. Nothing reaches an agent prompt until
+a project activates what it needs:
+
+```bash
+loadout setup --mode maximum --yes
+cd ~/code/my-app
+loadout optimize --project .   # scans the repo, proposes an active set
+loadout activate               # enable just those here
+```
+
+That trade is deliberate: disk is cheap and context is not. A large disabled
+library plus a small active set beats installing everything into every prompt.
+
+### Power: a larger cross-project toolkit
 
 Power draws a skill-level allowlist from eight major collections. The prepared set
 is deduplicated and invalid units are quarantined, so the final count can be lower
@@ -218,9 +334,9 @@ project choose a focused active set:
 
 ```bash
 loadout setup --mode maximum
-loadout recommend --project . --agent codex
-loadout optimize --project . --agents codex,claude-code --limit 30
-loadout optimize --project . --agents codex,claude-code --limit 30 --yes
+loadout recommend --project .
+loadout optimize --project . --limit 30
+loadout optimize --project . --limit 30 --yes
 ```
 
 This is the difference between “install everything” and “have everything ready.”
@@ -242,11 +358,11 @@ managed profile:
 
 ```bash
 
-# Install the reviewed Humanizer writing skill into Codex
-loadout install --mode custom --package humanizer --agents codex
+# Install the reviewed Humanizer writing skill
+loadout install --mode custom --package humanizer
 
-# Install the reviewed Obsidian skills explicitly
-loadout install --mode custom --package obsidian-skills --agents codex,claude-code
+# Install the reviewed Obsidian skills for specific agents
+loadout install --mode custom --package obsidian-skills --agents claude-code,cursor
 ```
 
 Run `loadout profiles` to compare every mode. MCP servers always use a separate
@@ -266,12 +382,9 @@ loadout mcp-recipe --credential-free
 Preview and configure one for the host you use:
 
 ```bash
-loadout mcp-recipe playwright --agent codex
-loadout mcp-recipe playwright --agent codex --yes
-loadout mcp-recipe playwright --agent codex --verify
-
 loadout mcp-recipe playwright --agent claude-code
 loadout mcp-recipe playwright --agent claude-code --yes
+loadout mcp-recipe playwright --agent claude-code --verify
 ```
 
 Configuration alone does not start the server. Test a real connection separately
@@ -282,12 +395,12 @@ variables or the OS keychain without printing their values.
 
 [Graphify](https://github.com/Graphify-Labs/graphify) is an optional codebase graph
 tool. It installs both a command and an agent skill, so Loadout keeps it separate from
-the normal profiles. It does not require an OpenAI or Anthropic API key:
+the normal profiles. It does not require an LLM API key:
 
 ```bash
-loadout tool graphify --agents codex,claude-code
-loadout tool graphify --agents codex,claude-code --yes --approve-risk
-loadout tool graphify --remove --agents codex,claude-code --yes --approve-risk
+loadout tool graphify
+loadout tool graphify --yes --approve-risk
+loadout tool graphify --remove --yes --approve-risk
 ```
 
 Executable tools remain an explicit choice instead of hiding inside a profile.
@@ -338,7 +451,7 @@ Loadout does not claim there is one universally “best” configuration. Recomm
 
 <!-- loadout:daily-discovery:start -->
 
-**Discovery snapshot (generated 2026-08-27):** [236 repositories observed](./docs/DISCOVERED.md), including 217 uncataloged review candidates and 19 repositories already in the inspected catalog.
+**Discovery snapshot (generated 2026-08-31):** [238 repositories observed](./docs/DISCOVERED.md), including 219 uncataloged review candidates and 19 repositories already in the inspected catalog.
 <!-- loadout:daily-discovery:end -->
 
 The checked-in discovery report proves only its dated snapshot, not the success of every scheduled run. Use `loadout discover --source all --queue`, `loadout review-queue`, and `loadout candidate inspect owner/repository` to inspect candidates before catalog promotion.
@@ -355,11 +468,11 @@ The checked-in discovery report proves only its dated snapshot, not the success
 
 <!-- loadout:current-limits:start -->
 
-- **6 catalog records** currently have `NOASSERTION` license status and need upstream-license review before a public release decision.
+- **4 catalog records** currently have `NOASSERTION` license status and need upstream-license review before a public release decision.
 
 <!-- loadout:current-limits:end -->
 
-The six records have an explicit public-release decision rather than an assumed
+The four records have an explicit public-release decision rather than an assumed
 license. Read [Upstream license decisions](./docs/UPSTREAM_LICENSE_DECISIONS.md) for
 the source-by-source record and the boundary applied to Power, Maximum, and Custom.
 
@@ -387,97 +500,44 @@ Configured paths and disposable filesystem lifecycle tests do not prove that nat
 
 Start at the top and stop whenever Loadout does everything you need.
 
-| Priority | What it does                                                    | Command                                                            |
-| -------: | --------------------------------------------------------------- | ------------------------------------------------------------------ |
-|        1 | Opens the beginner-friendly guided path                         | `loadout guide`                                                    |
-|        2 | Previews the recommended 30-skill daily setup                   | `loadout setup --mode stable`                                      |
-|        3 | Previews the broader Power setup                                | `loadout setup --mode power`                                       |
-|        4 | Downloads the broad screened library, disabled by default       | `loadout setup --mode maximum`                                     |
-|        5 | Shows Loadout-managed packages and active skills                | `loadout status`; `loadout library`                                |
-|        6 | Inventories skills across detected agents without changing them | `loadout scan`                                                     |
-|        7 | Explains what fits the current repository                       | `loadout recommend --project . --agent codex`                      |
-|        8 | Previews a bounded project-specific active set                  | `loadout optimize --project . --limit 30`                          |
-|        9 | Compares existing skills with reviewed catalog copies           | `loadout reconcile --refresh`                                      |
-|       10 | Checks managed active and disabled-library sources for changes  | `loadout update`                                                   |
-|       11 | Finds newly launched or newly popular candidates                | `loadout discover --source all --queue`                            |
-|       12 | Shows candidates waiting for deeper review                      | `loadout review-queue`                                             |
-|       13 | Lists MCP recipes and credential needs                          | `loadout mcp-recipe`; `loadout mcp-recipe --credential-free`       |
-|       14 | Previews an MCP configuration                                   | `loadout mcp-recipe playwright --agent codex`                      |
-|       15 | Lists and installs isolated runtime tools such as Graphify      | `loadout tool`; `loadout tool graphify --agents codex,claude-code` |
-|       16 | Lists snapshots or restores the latest managed change           | `loadout rollback --list`; `loadout rollback`                      |
-|       17 | Previews removal of one managed package                         | `loadout remove <package-id>`                                      |
-|       18 | Previews complete removal of Loadout-managed state              | `loadout uninstall`                                                |
-|       19 | Enables read-only daily discovery and update checks             | `loadout autopilot --yes`                                          |
-|       20 | Shows the complete CLI                                          | `loadout --help`; `loadout advanced`                               |
+| Priority | What it does                                                    | Command                                                      |
+| -------: | --------------------------------------------------------------- | ------------------------------------------------------------ |
+|        1 | Opens the beginner-friendly guided path                         | `loadout guide`                                              |
+|        2 | Previews the recommended 30-skill daily setup                   | `loadout setup --mode stable`                                |
+|        3 | Previews the broader Power setup                                | `loadout setup --mode power`                                 |
+|        4 | Downloads the broad screened library, disabled by default       | `loadout setup --mode maximum`                               |
+|        5 | Shows Loadout-managed packages and active skills                | `loadout status`; `loadout library`                          |
+|        6 | Inventories skills across detected agents without changing them | `loadout scan`                                               |
+|        7 | Explains what fits the current repository                       | `loadout recommend --project .`                              |
+|        8 | Previews a bounded project-specific active set                  | `loadout optimize --project . --limit 30`                    |
+|        9 | Compares existing skills with reviewed catalog copies           | `loadout reconcile --refresh`                                |
+|       10 | Checks managed active and disabled-library sources for changes  | `loadout update`                                             |
+|       11 | Finds newly launched or newly popular candidates                | `loadout discover --source all --queue`                      |
+|       12 | Shows candidates waiting for deeper review                      | `loadout review-queue`                                       |
+|       13 | Lists MCP recipes and credential needs                          | `loadout mcp-recipe`; `loadout mcp-recipe --credential-free` |
+|       14 | Previews an MCP configuration                                   | `loadout mcp-recipe playwright --agent claude-code`          |
+|       15 | Installs Loadout's own skill into your agents                   | `loadout skills install loadout-router --yes`                |
+|       16 | Recommends the right model and agent for a task                 | `loadout route design the auth system`                       |
+|       17 | Shows the full model catalog with pricing                       | `loadout route --models`; `loadout route --cost`             |
+|       18 | Sends a task to another agent via file-based handoff            | `loadout handoff send codex "write tests for auth"`          |
+|       19 | Checks agent health, permissions, and setup                     | `loadout doctor`; `loadout doctor --verbose`                 |
+|       20 | Lists and installs isolated runtime tools such as Graphify      | `loadout tool`; `loadout tool graphify`                      |
+|       21 | Lists snapshots or restores the latest managed change           | `loadout rollback --list`; `loadout rollback`                |
+|       22 | Previews removal of one managed package                         | `loadout remove <package-id>`                                |
+|       23 | Previews complete removal of Loadout-managed state              | `loadout uninstall`                                          |
+|       24 | Enables read-only daily discovery and update checks             | `loadout autopilot --yes`                                    |
+|       25 | Shows the complete CLI                                          | `loadout --help`; `loadout advanced`                         |
 
 Most mutating commands are dry runs first. After reading the preview, add `--yes` to
 apply. Commands with executable or connection risk require the additional approval
 shown in their output.
 
-## Built with Codex and GPT-5.6
-
-Loadout was built during OpenAI Build Week by a three-person team working with Codex
-and GPT-5.6. Codex was not a chat box bolted onto the finished project. It was the
-engineering environment we used to plan, build, test, and repeatedly challenge the
-product while it was taking shape.
-
-### From a broad idea to a working product
-
-The starting idea was simple: one install that gives every coding agent the best
-extensions on GitHub. The difficult part was everything hidden inside that sentence.
-What counts as “best”? How much should stay active? What happens to skills a user
-already has? How do you update a repository without silently trusting new code? How
-do you undo changes across several agents?
-
-We used GPT-5.6 through Codex for the repo-wide reasoning behind those decisions.
-Together, we turned the idea into three distinct modes: a bounded Stable daily
-driver, a larger Power setup, and a Maximum library that keeps broad optionality
-without loading thousands of skills into every prompt.
-
-| Part of the build  | How we used Codex and GPT-5.6                                                                                                | What made it into Loadout                                                                                   |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Product planning   | Broke the original idea into testable user journeys and challenged unsafe assumptions                                        | Stable, Power, Maximum, Custom, project optimization, discovery, updates, and complete uninstall            |
-| Architecture       | Traced how catalogs, adapters, agent directories, manifests, and snapshots affect one another                                | A local TypeScript CLI with a shared catalog, 12 agent adapters, and snapshot-backed transactions           |
-| Ecosystem research | Compared repositories, checked source layouts and licenses, and separated popularity from evidence                           | 53 pinned catalog sources plus a discovery snapshot watching 240 repositories                               |
-| Implementation     | Wrote and refactored CLI commands, schemas, source fetchers, installers, active-set logic, and MCP configuration             | The published `loadout-ai` package and the commands documented above                                        |
-| Safety work        | Looked for scripts, hooks, binaries, credential references, target collisions, stale previews, and external edits            | Preview-first changes, quarantined skill units, explicit risk approval, drift protection, and rollback      |
-| Testing            | Generated adversarial cases, reproduced failures from real terminal sessions, and converted them into regression tests       | 632 passing tests, CLI and README end-to-end flows, package smoke tests, and a 1,000-skill performance gate |
-| Team integration   | Audited teammate branches, compared them with `main`, prepared focused pull requests, and checked what was actually complete | One public history instead of three disconnected prototypes                                                 |
-| Release work       | Verified npm contents, version behavior, GitHub metadata, documentation claims, and public CI                                | A public npm package, credited upstream catalog, release evidence, and a reproducible verification command  |
-
-### Real testing changed the code
-
-Codex was most useful when the neat plan met a messy laptop. A few examples:
-
-- A Graphify install appeared in Claude Code but vanished from Codex inventory
-  because the generated runtime skill and the normal skill scanner used different
-  Codex paths. The scan now recognizes managed runtime-tool skills explicitly.
-- Update checks repeatedly timed out on large repositories. We measured the real
-  clone cost, changed the update path to check remote commit metadata first, and only
-  fetch a full snapshot when a pinned source actually changed.
-- Existing unmanaged skills could occupy the same target as a Stable install.
-  Instead of overwriting them, Loadout now stops, scans, compares, and offers a
-  separate reconciliation path for exact or unambiguous matches.
-- ChatGPT and Claude subscriptions were easy to confuse with separately billed API
-  access. Setup now asks about API access explicitly, while credentialed MCP servers
-  remain separate from automatic skill installation.
-
-Those fixes came from a loop we repeated throughout the week: run the real command,
-paste the exact output into Codex, trace the behavior through the codebase, write a
-regression test, fix the smallest responsible layer, and run the full release gate.
-
-### What the team owned
-
-The humans chose the product direction, selected the tradeoffs, reviewed upstream
-projects, tested Loadout on real Codex and Claude Code profiles, approved risky
-operations, and made every release decision. GPT-5.6 helped with high-context design,
-debugging, and review; Codex handled the implementation loop and verification tools.
-Neither replaced human judgment about what should be installed on someone else's
-machine.
-
-Loadout itself does **not** call GPT-5.6 and does not require an OpenAI API key to
-manage skills. Codex and GPT-5.6 helped build the tool; they are not a hidden runtime
-dependency.
+## Built with Claude
+
+Loadout was designed and built by [Viraj Mishra](https://github.com/VirajMishra1) with Claude Code.
+
+Loadout itself does **not** call any LLM API and does not require an LLM API key
+to manage skills. Claude helped build the tool; it is not a hidden runtime dependency.
 
 ## Development