loadout-ai 0.7.0 → 0.9.0

package/docs/REFERENCE.md

@@ -0,0 +1,163 @@
+# Loadout Reference
+
+Detailed configuration, profiles, integrations, and discovery documentation.
+For the quick start, see the [README](../README.md).
+
+## Profiles
+
+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                              |
+
+**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.
+
+### Stable: the essentials
+
+Stable is the recommended daily driver: **30 selected skill directories from four
+pinned public sources**, installed into each agent you choose.
+
+| Included source                                                        | What Stable takes from it                                     | GitHub                                                                                                                                            |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Superpowers](https://github.com/obra/superpowers)                     | Planning, execution, testing, review, verification            | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)               |
+| [Context7](https://github.com/upstash/context7)                        | Current documentation and MCP workflows                       | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)               |
+| [Addy Osmani Agent Skills](https://github.com/addyosmani/agent-skills) | Engineering, frontend, debugging, performance, docs, shipping | [![GitHub stars](https://img.shields.io/github/stars/addyosmani/agent-skills?style=flat&label=stars)](https://github.com/addyosmani/agent-skills) |
+| [Agent Skills Marketplace](https://github.com/wshobson/agents)         | Architecture, review, error handling, JavaScript, Python      | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                 |
+
+```bash
+loadout setup --mode stable
+loadout setup --mode stable --yes
+```
+
+### Power: a larger cross-project toolkit
+
+Power draws a skill-level allowlist from eight major collections.
+
+| Included source                                                          | Focus                                                     | GitHub                                                                                                                                                                      |
+| ------------------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Anthropic Skills](https://github.com/anthropics/skills)                 | Documents, frontend, MCP building, web testing            | [![GitHub stars](https://img.shields.io/github/stars/anthropics/skills?style=flat&label=stars)](https://github.com/anthropics/skills)                                       |
+| [OpenAI Skills](https://github.com/openai/skills)                        | CLI, docs, browser work, images, security                 | [![GitHub stars](https://img.shields.io/github/stars/openai/skills?style=flat&label=stars)](https://github.com/openai/skills)                                               |
+| [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)       | React, web design, composition, deployment                | [![GitHub stars](https://img.shields.io/github/stars/vercel-labs/agent-skills?style=flat&label=stars)](https://github.com/vercel-labs/agent-skills)                         |
+| [Superpowers](https://github.com/obra/superpowers)                       | Planning, debugging, testing, collaboration               | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)                                         |
+| [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | UI systems, slides, styling, product design               | [![GitHub stars](https://img.shields.io/github/stars/nextlevelbuilder/ui-ux-pro-max-skill?style=flat&label=stars)](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
+| [Context7](https://github.com/upstash/context7)                          | Current documentation and MCP workflows                   | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)                                         |
+| [Agent Skills Marketplace](https://github.com/wshobson/agents)           | Architecture, testing, APIs, TypeScript, Python           | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                                           |
+| [Awesome Copilot](https://github.com/github/awesome-copilot)             | Codebase knowledge, plans, browser and security workflows | [![GitHub stars](https://img.shields.io/github/stars/github/awesome-copilot?style=flat&label=stars)](https://github.com/github/awesome-copilot)                             |
+
+```bash
+loadout setup --mode power
+```
+
+### Maximum: download broadly, activate intelligently
+
+Downloads every non-archived, technically screened skill component into
+Loadout's **disabled local library**. Then let the current project choose:
+
+```bash
+loadout setup --mode maximum
+loadout recommend --project .
+loadout optimize --project . --limit 30
+loadout optimize --project . --limit 30 --yes
+```
+
+### Custom: take exact control
+
+```bash
+# Replace the managed profile
+loadout setup --mode custom --package superpowers --package context7
+
+# Add without replacing
+loadout install --mode custom --package humanizer
+loadout install --mode custom --package obsidian-skills --agents claude-code,cursor
+```
+
+Run `loadout profiles` to compare every mode.
+
+## MCP integrations
+
+Profiles never start MCP servers silently.
+
+```bash
+loadout mcp-recipe                                          # list recipes
+loadout mcp-recipe --credential-free                        # no-credential subset
+loadout mcp-recipe playwright --agent claude-code           # preview
+loadout mcp-recipe playwright --agent claude-code --yes     # configure
+loadout mcp-recipe playwright --agent claude-code --verify  # test
+```
+
+Configuration alone does not start the server. Test a real connection separately
+with `--connect --approve-risk`. Loadout can reference credentials from environment
+variables or the OS keychain without printing their values.
+
+## Optional runtime tools
+
+[Graphify](https://github.com/Graphify-Labs/graphify) is an optional codebase graph
+tool. It does not require an LLM API key:
+
+```bash
+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.
+
+## Catalog and discovery
+
+The catalog is not a frozen list. Loadout separates **discovery** from
+**installation** so a viral repo can be noticed quickly without being trusted
+blindly.
+
+```bash
+loadout discover --source all --queue      # find candidates
+loadout review-queue                        # inspect the queue
+loadout candidate inspect owner/repository  # deep inspection
+loadout update                              # check for source changes
+loadout health --updates                    # managed source health
+```
+
+Daily checks are opt-in and read-only:
+
+```bash
+loadout autopilot --yes
+loadout autopilot --status
+```
+
+## Manage skills you already have
+
+```bash
+loadout scan                          # read-only inventory
+loadout reconcile --refresh           # compare with catalog
+loadout reconcile --yes               # record ownership for exact matches
+loadout reconcile --replace-outdated  # preview replacing old copies
+```
+
+Unknown or ambiguous copies stay untouched.
+
+## Agent support
+
+Loadout's adapter capability matrix covers **12 agents**: Claude Code, Cline,
+Codex, Cursor, Gemini CLI, GitHub Copilot, Hermes, Junie, Kiro CLI, OpenCode,
+Roo Code, Windsurf.
+
+See the [complete feature matrix](./FEATURE_TEST_MATRIX.md) for configured
+paths, filesystem lifecycle, platform, and native-host evidence.
+
+Use `loadout doctor --verbose` for the local component matrix.

package/docs/RELEASE_REVIEW.md

@@ -19,10 +19,9 @@ For current behavior and evidence, use:
   catalog/support facts;
 - the [changelog](../CHANGELOG.md) for released behavior;
 - the [feature test matrix](./FEATURE_TEST_MATRIX.md) for adapter evidence;
-- the [repository stabilization record](./REPOSITORY_STABILIZATION.md) and
   [sanitized July 19 live checks](./evidence/live-checks-2026-07-19.json) only when
   investigating that historical release line.
 
-The current release gate is `npm run verify`. Publication status must be checked
+The current release gate is `npm run verify:full`. Publication status must be checked
 against the npm registry and the corresponding GitHub release rather than inferred
 from this archived document.

package/docs/TESTING.md

@@ -68,7 +68,23 @@ checks the current pinned Stable sources and remains network-dependent.
 
 Run `npm run verify` for formatting, lint, types, deterministic evidence checks, all
 Vitest suites, both CLI journeys, package smoke, and the performance gate.
-`npm run verify:full` is retained as an alias for the same complete CLI gate.
+Run `npm run verify:full` before a release; it runs that gate and then enforces
+the global and security-sensitive per-file coverage floors.
+
+The coordination suites exercise the protocol separately from paid providers:
+
+```bash
+npx vitest run 'tests/coordination*.test.ts'
+npm run test:package
+```
+
+They cover cross-process ordering, ownership/revision conflicts, redaction,
+retention and recovery, daemon authentication, MCP framing, provider command/SDK
+shapes, automatic watcher delivery, passive interrupt policy, singleton bridge
+ownership, bounded two-agent discussion turns and reply chains, leases, and
+runaway-turn limits. Fake provider drivers are used for deterministic
+tests; the suite does not spend Claude or Codex quota. Follow the disposable
+manual flow in `docs/USER_TEST_GUIDE.md` for an intentional real-host test.
 
 Current npm publication, the current pinned Stable repositories, and GitHub repository
 settings are external state. Check them separately with:

package/docs/USER_TEST_GUIDE.md

@@ -192,7 +192,142 @@ GitHub token; use `loadout mcp-recipe --credential-free` to exclude every servic
 credential too. Browser configuration and real connection testing remain explicit.
 Graphify is a separate runtime tool, not an MCP server.
 
-## 8. Preview complete cleanup
+## 8. Test handoff and live coordination in a disposable repository
+
+Create a temporary Git repository so the test does not add handoff files to a
+real project:
+
+```bash
+mkdir loadout-coordination-test
+cd loadout-coordination-test
+git init
+```
+
+First test the stable session-boundary inbox:
+
+```bash
+loadout handoff codex "Implement the frontend" --context "Claude owns src/api; consume checkout-api"
+loadout handoff codex
+loadout handoff
+```
+
+Copy the task ID printed by the inbox, then settle it:
+
+```bash
+loadout handoff --done <task-id>
+loadout handoff codex
+```
+
+Next test structured coordination without running either model:
+
+```bash
+loadout coord own claude-code src/api
+loadout coord own codex src/web
+loadout coord contract checkout-api --agent claude-code \
+  --body "POST /api/checkout -> 201 { id: string }"
+loadout coord snapshot codex
+loadout coord ack codex 2
+loadout coord status
+loadout coord replay
+```
+
+Sequence numbers are printed by each command; use the actual latest relevant
+sequence if it differs from `2`. Confirm that the first overlapping exclusive
+claim is refused, then release the original path and confirm the retry succeeds:
+
+```bash
+loadout coord own codex src/api/checkout.ts
+loadout coord release claude-code src/api
+loadout coord own codex src/api/checkout.ts
+```
+
+Test the authenticated live dashboard in one terminal:
+
+```bash
+loadout daemon start
+```
+
+Open the exact dashboard URL it prints. In a second terminal, run another
+`loadout coord update` and confirm it appears. A bare `/api/status` request
+without the bearer token should return `401`. Press Ctrl+C in the daemon
+terminal when finished.
+
+Test the packaged MCP transport without changing either agent's configuration:
+
+```bash
+loadout serve
+```
+
+The process waits for MCP JSON-RPC on stdin and should print no banners or prose
+to stdout. Press Ctrl+C. Host-specific configuration and the exact tool list are
+in [the live coordination guide](./LIVE_COLLABORATION.md).
+
+Finally, inspect the provider bridge surface:
+
+```bash
+loadout coord agents detect
+loadout coord agents list
+loadout coord agents bridge --help
+```
+
+The next commands run real provider turns and may consume Claude/Codex quota.
+Only run them when you intentionally want that test:
+
+```bash
+loadout coord agents start claude-code "Claim backend files and publish a test contract"
+loadout coord agents start codex "Read the shared snapshot and acknowledge the contract"
+loadout coord agents bridge claude-code:<session-id> codex:<thread-id> --max-turns 4
+```
+
+While the bridge runs, publish a new contract from another terminal. Confirm
+both provider sessions can proceed concurrently and that the bridge prints
+their responses. Progress-only `update` events remain passive by default. Use
+Ctrl+C to stop the bridge. Activate `loadout daemon kill "user test"` to verify
+that new coordination writes and provider turns stop, then run
+`loadout daemon resume`.
+
+Now test an actual back-and-forth design discussion. This spends exactly three
+provider turns: one Claude proposal, one Codex critique, and one Claude
+synthesis. Neither agent should edit the disposable repository.
+
+```bash
+loadout coord discuss start "Should this test service expose REST or GraphQL?" \
+  --agents claude-code,codex \
+  --rounds 1 \
+  --max-turns 3 \
+  --timeout 120
+```
+
+Confirm all of the following before publishing:
+
+1. stderr announces exactly three paid provider turns before either provider
+   runs;
+2. Claude Code proposes a design and Codex directly critiques that proposal;
+3. Claude's synthesis names a decision, rationale, alternatives, and any
+   unresolved disagreement;
+4. `loadout coord discuss list` reports the thread as `closed`;
+5. `loadout coord discuss show <thread-id>` shows the linked public transcript;
+6. `loadout coord replay` includes the discussion and the resulting decision;
+7. `git status --short` shows that neither agent edited a project file.
+
+Repeat with known real session IDs to validate resumption:
+
+```bash
+loadout coord discuss start "What validation boundary should this service use?" \
+  --sessions claude-code:<session-id> codex:<thread-id> \
+  --rounds 1 --max-turns 3
+```
+
+For the kill-switch check, start a two-round discussion in one terminal and run
+`loadout daemon kill "stop design room"` in another while the first provider
+turn is active. The in-flight provider may finish, but its response must not be
+persisted and Codex must not receive the next turn. Run `loadout daemon resume`
+after confirming the halt.
+
+Delete the disposable repository after inspection. Its `.handoff` directory
+contains the local task/event audit trail, token, and session IDs.
+
+## 9. Preview complete cleanup
 
 ```bash
 loadout uninstall
@@ -211,7 +346,7 @@ cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle te
 ## Troubleshooting and recovery
 
 - **`loadout` is not found after installation:** confirm `npm install --global
-loadout-ai@0.5.9` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.9.0` completed, run `hash -r`, and confirm npm's global binary
   directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
 - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
   credentials, binaries, or instruction findings. If you accept that specific plan,
@@ -238,7 +373,7 @@ loadout-ai@0.5.9` completed, run `hash -r`, and confirm npm's global binary
   Unmanaged content is preserved, and modified managed files can make cleanup refuse
   until you explicitly review the command's force path.
 
-## 9. Advanced surface
+## 10. Advanced surface
 
 The first help screen deliberately focuses on daily use. Existing advanced
 commands have not been removed:

package/docs/decisions/001-coordination-jsonl-locking.md

@@ -0,0 +1,35 @@
+# ADR 001: JSONL plus a project lock for coordination state
+
+- Status: accepted
+- Date: 2026-09-03
+
+## Context
+
+Loadout coordinates a small number of local coding-agent processes in one
+repository. Events need durable ordering, human inspectability, recovery after
+partial writes, and parity across CLI, MCP, HTTP, and provider adapters. A
+database would add installation, migration, backup, and corruption-recovery
+surface before the expected workload requires indexed storage.
+
+## Decision
+
+Use `.handoff/coordination.jsonl` as the source of truth. Serialize every
+mutation with `.handoff/coordination.lock`, created exclusively with owner-only
+permissions. Allocate event sequences and contract revisions while holding that
+lock. Derive current ownership, contracts, acknowledgements, and snapshots from
+validated events.
+
+Compaction holds the same lock, writes a complete owner-only archive first,
+then atomically replaces the working log with a valid summary and retained
+events. Missing files mean empty state; other I/O errors propagate. Invalid
+lines are reported without hiding valid neighbors.
+
+## Consequences
+
+- The audit trail is readable and easy to back up or remove.
+- Independent local processes cannot allocate duplicate sequences or accept
+  conflicting ownership claims concurrently.
+- Reads are linear in the active log, so retention must keep it bounded.
+- This design is for local repository coordination, not a remote multi-user
+  service. A future remote transport would require a separate trust and storage
+  decision rather than exposing this daemon to a network.

package/docs/decisions/002-local-daemon-authentication.md

@@ -0,0 +1,32 @@
+# ADR 002: Loopback-only authenticated coordination daemon
+
+- Status: accepted
+- Date: 2026-09-03
+
+## Context
+
+A localhost HTTP service is still reachable by browser pages, local malware,
+and other users on an incorrectly configured machine. Coordination events can
+contain private repository structure and can influence paid provider turns.
+
+## Decision
+
+Bind the daemon only to `127.0.0.1`. Generate a random 32-byte project token in
+`.handoff/daemon.token` with mode `0600`. REST and SSE require a bearer header;
+query-string tokens are rejected. Validate loopback Host headers and allow only
+same-origin browser requests.
+
+The CLI passes the token to the dashboard in a URL fragment. The dashboard
+moves it into session storage immediately and removes the fragment from browser
+history. Human-readable status does not expose the project root. Request bodies,
+routes, cursors, agent names, and typed event payloads are bounded and validated.
+
+## Consequences
+
+- The dashboard opens conveniently without putting credentials in HTTP request
+  URLs or referrers.
+- API clients must explicitly read the local token and set `Authorization`.
+- The daemon is observability and local transport only; it is not supported as
+  a LAN or internet-facing service.
+- Activating the project kill switch fails closed across storage, daemon,
+  compaction, MCP/CLI writes, and provider-driven turns.

package/docs/decisions/003-bounded-agent-discussions.md

@@ -0,0 +1,91 @@
+# ADR 003: Bounded sequential agent discussions
+
+## Status
+
+Accepted
+
+## Date
+
+2026-09-04
+
+## Context
+
+The coordination bridge can deliver structured events to Claude Code and Codex,
+but it does not make the agents deliberate. Users who want both models to weigh
+the same feature must manually relay responses, and an unconstrained automatic
+relay could consume quota indefinitely, spread prompt injection, or let two
+agents edit the same files concurrently.
+
+Provider interfaces can start or resume turns, but neither supported interface
+offers a shared hidden context or reliable mid-turn steering. Provider output
+is also untrusted data and may be empty, malformed, oversized, or contain
+instructions unrelated to the user's question.
+
+## Decision
+
+Implement an opt-in, two-participant design room as a sequential protocol:
+
+- one proposer and one reviewer alternate for 1-8 rounds;
+- each response is explicitly public, redacted, bounded, persisted, and linked
+  to the prior event by thread and reply IDs;
+- each round costs two provider turns and final synthesis costs one, so the
+  exact required budget is known before any provider session starts;
+- prompts prohibit file edits, commands, tools, and disclosure of private
+  reasoning;
+- the proposer returns a strict final JSON decision, rationale, alternatives,
+  and unresolved disagreements;
+- Loadout emits a normal decision event and a terminal discussion event;
+- provider rejection, invalid output, and empty output close the discussion as
+  failed without silent retries;
+- the existing project kill switch is checked before every provider turn;
+- provider turns default to 120 seconds and are explicitly bounded to a
+  user-selectable 10-600 seconds.
+
+Fresh sessions start lazily with their first discussion prompt so setup does not
+spend a hidden extra turn. Existing provider session IDs are attached without a
+turn and then resumed on the first discussion response. The project bridge
+lease prevents a background bridge and a design room from controlling the same
+sessions concurrently.
+
+## Alternatives considered
+
+### Let both agents edit the same feature during the discussion
+
+Rejected. The purpose of the design room is to settle an approach before file
+ownership and implementation. Concurrent edits make the outcome harder to
+review and reintroduce the conflicts the ownership protocol prevents.
+
+### Forward full provider transcripts automatically
+
+Rejected. It would expose unrelated context, increase prompt-injection risk,
+and make storage and quota use unpredictable. Only responses requested for the
+public discussion are shared.
+
+### Run both agents concurrently and ask a third model to judge
+
+Rejected for the first release. Parallel first proposals do not support genuine
+back-and-forth critique, and a third model adds provider, billing, and tie-break
+semantics without evidence that it improves decisions.
+
+### Continue until the agents agree
+
+Rejected. Agreement is not guaranteed, and an unbounded loop is unsafe. The
+final result preserves unresolved disagreement rather than claiming consensus.
+
+### Host a remote coordination bus
+
+Rejected for this release. Authentication, tenant isolation, encryption,
+availability, and remote conflict semantics require a separate design. The
+current protocol remains local to one repository and machine.
+
+## Consequences
+
+- Users get a real Claude↔Codex critique loop with a predictable maximum cost.
+- The transcript is inspectable with `coord discuss show` and the normal replay.
+- The discussion cannot steer a provider mid-turn; a kill switch takes effect
+  before the next turn.
+- Strict final JSON may fail when a provider ignores the requested format. That
+  failure is visible and auditable instead of being misrepresented as a valid
+  decision.
+- More than two agents, voting, hosted rooms, and automatic implementation are
+  intentionally out of scope.