loadout-ai 0.9.4 → 0.9.5

package/docs/superpowers/plans/2026-09-08-fast-launch-demo.md

@@ -0,0 +1,65 @@
+# Fast Launch Demo Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the five-minute demo script with a deterministic 60–75 second narrated launch cut.
+
+**Architecture:** Prepare genuine CLI outputs and Kokoro narration before capture, replay those artifacts on a fixed scene timeline, then mux and verify one 1080p MP4. The completed discussion thread `a71874c7-5ac` supplies real Claude Code and Codex output without paid-turn waiting.
+
+**Tech Stack:** Bash, Loadout CLI, Kokoro, macOS `screencapture`, FFmpeg, FFprobe.
+
+## Global Constraints
+
+- Preserve Maximum, Optimize, Handoff, Coordination, and Discussion scenes.
+- Omit rollback.
+- Do not fabricate provider output.
+- Cap the final video at 75 seconds.
+- Write the result to `/Users/viraj/Desktop/loadout-demo-1080p.mp4`.
+
+---
+
+### Task 1: Precompute genuine demo artifacts
+
+**Files:**
+
+- Modify: `/Users/viraj/Desktop/run-loadout-demo.sh`
+
+**Interfaces:**
+
+- Consumes: current Loadout build, isolated demo state, completed discussion `a71874c7-5ac`.
+- Produces: disposable text outputs and seven Kokoro WAV clips under `.loadout-demo-tmp`.
+
+- [ ] **Step 1:** Replace live in-capture commands with preflight commands whose stdout is stored under `.loadout-demo-tmp/output`.
+- [ ] **Step 2:** Generate seven concise `af_heart` narration clips before capture.
+- [ ] **Step 3:** Verify `bash -n /Users/viraj/Desktop/run-loadout-demo.sh` succeeds.
+
+### Task 2: Record a hard-bounded scene timeline
+
+**Files:**
+
+- Modify: `/Users/viraj/Desktop/run-loadout-demo.sh`
+
+**Interfaces:**
+
+- Consumes: Task 1 text and WAV artifacts.
+- Produces: `.loadout-demo-tmp/raw.mov` and `.loadout-demo-tmp/narration.wav`.
+
+- [ ] **Step 1:** Render seven scenes using saved real output and sleep only for the associated narration duration.
+- [ ] **Step 2:** Use the completed discussion transcript instead of starting paid provider turns.
+- [ ] **Step 3:** Set `screencapture` to a 75-second safety cap and finalize it with `SIGINT`.
+
+### Task 3: Export and verify the launch MP4
+
+**Files:**
+
+- Modify: `/Users/viraj/Desktop/run-loadout-demo.sh`
+- Create at runtime: `/Users/viraj/Desktop/loadout-demo-1080p.mp4`
+
+**Interfaces:**
+
+- Consumes: Task 2 video and narration tracks.
+- Produces: one verified H.264/AAC 1920×1080 MP4.
+
+- [ ] **Step 1:** Concatenate narration clips with short pauses and mux them with the captured video.
+- [ ] **Step 2:** Scale and pad to exactly 1920×1080 with `yuv420p` and Fast Start.
+- [ ] **Step 3:** Fail if FFprobe reports a duration outside 45–75 seconds or missing video/audio streams.

package/docs/superpowers/plans/2026-09-08-maximum-curator-demo-recording.md

@@ -0,0 +1,247 @@
+# Maximum + Curator demo recording implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Record, narrate, and export a truthful two-minute Loadout flagship demo to the user’s Desktop.
+
+**Architecture:** A disposable TypeScript fixture and a local copy of the published 0.9.4 CLI provide deterministic terminal output. The Maximum install intentionally targets every detected real agent after the approved risk acknowledgement so pre-existing active skills are preserved; the recorded curation and coordination scenes remain focused on Claude Code and Codex. All visible work remains in one clean Terminal window. Screen capture, voice narration, captions, and H.264 export are produced outside the repository.
+
+**Tech Stack:** Node.js 20+, npm, Loadout 0.9.4, macOS Terminal, `screencapture`, macOS `say`, FFmpeg, Claude Code CLI, Codex CLI/SDK.
+
+## Global Constraints
+
+- Final video duration: 120 seconds or less.
+- Final output: `/Users/viraj/Desktop/loadout-demo-maximum-curator-1080p.mp4`.
+- Capture one terminal rectangle only; do not show any Claude, Codex, browser, Finder, or existing-project UI.
+- Show the real Maximum preview before using `--yes --approve-risk`.
+- Do not enable credentialed MCP integrations.
+- Use real Claude Code and Codex replies for the bounded discussion; label removed idle wait time.
+- Do not commit demo recordings, temporary scripts, audio, or fixture data to this repository.
+
+---
+
+### Task 1: Prepare the isolated recording workspace and published CLI
+
+**Files:**
+
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/package.json`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/fixture/src/api/checkout.ts`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/fixture/src/frontend/checkout.ts`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/fixture/package.json`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/output/raw/`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/output/final/`
+
+**Interfaces:**
+
+- Consumes: npm registry package `loadout-ai@0.9.4`.
+- Produces: `node_modules/.bin/loadout` resolving to 0.9.4 and a small backend/frontend checkout fixture.
+
+- [ ] **Step 1: Create the workspace and fixture files with no personal content.**
+
+  The fixture API file must export `CheckoutRequest`, `CheckoutResult`, and
+  `submitCheckout`. The frontend file must import `CheckoutRequest` from the
+  API file, making the contract detector and ownership split meaningful.
+
+- [ ] **Step 2: Install exactly the published CLI.**
+
+  Run:
+
+  ```bash
+  npm install --prefix /Users/viraj/Desktop/.loadout-demo-2026-09-08 loadout-ai@0.9.4
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout --version
+  ```
+
+  Expected: `0.9.4`.
+
+- [ ] **Step 3: Preflight the recording dependencies.**
+
+  Run:
+
+  ```bash
+  command -v ffmpeg
+  command -v /usr/sbin/screencapture
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout recommend --project /Users/viraj/Desktop/.loadout-demo-2026-09-08/fixture
+  ```
+
+  Expected: FFmpeg and macOS screen capture are available; the fixture is
+  recognized as a TypeScript/Node project.
+
+### Task 2: Apply Maximum, curate a focused set, and prove rollback
+
+**Files:**
+
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/scripts/prepare-state.sh`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/transcript/setup.txt`
+
+**Interfaces:**
+
+- Consumes: the published CLI from Task 1 and the user's approved real agent setup.
+- Produces: a verified Maximum library, a curated fixture-specific active set, and rollback evidence.
+
+- [ ] **Step 1: Run and retain the Maximum preview.**
+
+  Run:
+
+  ```bash
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout setup --mode maximum --agents claude-code,codex --api-access none --details
+  ```
+
+  Expected: a summary containing reviewed sources, installable repositories,
+  quarantined units, deferred integrations, and the Docker preparation failure.
+
+- [ ] **Step 2: Apply the approved Maximum plan to every detected agent.**
+
+  Run:
+
+  ```bash
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout setup --mode maximum --agents claude-code,codex,cursor,gemini-cli,windsurf --api-access none --yes --approve-risk
+  ```
+
+  Expected: a managed library and rollback snapshot for every detected agent;
+  Docker MCP Gateway is explicitly skipped after its preparation failure, and no
+  credentialed MCP setup is enabled.
+
+- [ ] **Step 3: Curate and apply the fixture working set.**
+
+  Run:
+
+  ```bash
+  cd /Users/viraj/Desktop/.loadout-demo-2026-09-08/fixture
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout recommend --project .
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout optimize --project . --agents claude-code,codex --limit 30
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout optimize --project . --agents claude-code,codex --limit 30 --yes
+  ```
+
+  Capture concise `status` output after the `--yes` activation transaction.
+
+- [ ] **Step 4: Prove reversibility.**
+
+  Run:
+
+  ```bash
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout rollback --list
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout rollback
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout status
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout optimize --project . --agents claude-code,codex --limit 30 --yes
+  ```
+
+  Expected: the first rollback restores the Maximum-library state that preceded
+  the project activation. The final optimize reuses the same deterministic
+  project rules so handoff and coordination scenes retain their curated set.
+
+- [ ] **Step 5: Verify the real setup remains healthy.**
+
+  Run:
+
+  ```bash
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout status
+  /Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout health
+  ```
+
+  Expected: managed state is readable and no credentialed integration was
+  enabled inadvertently.
+
+### Task 3: Capture handoff, coordination, and a real bounded discussion
+
+**Files:**
+
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/scripts/demo-scenes.sh`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/transcript/coordination.txt`
+
+**Interfaces:**
+
+- Consumes: checkout fixture, Loadout 0.9.4, real Claude Code/Codex credentials.
+- Produces: durable handoff and coordination events including a real three-turn discussion.
+
+- [ ] **Step 1: Record a bundled verified handoff.**
+
+  Set `LOADOUT_BIN` to
+  `/Users/viraj/Desktop/.loadout-demo-2026-09-08/node_modules/.bin/loadout` and
+  run from the fixture:
+
+  ```bash
+  "$LOADOUT_BIN" handoff codex "Review checkout validation and add edge-case tests" --from claude-code --bundle src/api/checkout.ts --verify "Unit tests cover empty cart IDs"
+  "$LOADOUT_BIN" handoff codex
+  ```
+
+  Expected: durable inbox entry with bundle metadata and verification criterion.
+
+- [ ] **Step 2: Record ownership and contract coordination.**
+
+  Run:
+
+  ```bash
+  "$LOADOUT_BIN" coord start --agents claude-code,codex --split backend/frontend
+  "$LOADOUT_BIN" coord start --agents claude-code,codex --split backend/frontend --yes
+  "$LOADOUT_BIN" coord contract checkout-api --agent claude-code --format typescript --body 'export interface CheckoutAPI { submit(input: CheckoutRequest): Promise<CheckoutResult>; }'
+  "$LOADOUT_BIN" coord snapshot codex
+  ```
+
+  Expected: explicit ownership, a TypeScript contract, and a Codex-readable snapshot.
+
+- [ ] **Step 3: Record one real three-turn provider exchange.**
+
+  Run:
+
+  ```bash
+  "$LOADOUT_BIN" coord discuss start "Should checkout validation live in the API handler or domain service?" --agents claude-code,codex --rounds 1 --max-turns 3 --timeout 120 --thread-id demo-checkout-architecture
+  "$LOADOUT_BIN" coord replay
+  ```
+
+  Expected: visible provider labels and actual Claude Code/Codex replies, followed
+  by a durable replay. If a provider is unavailable, stop the recording and
+  report the exact adapter error rather than substituting simulated output.
+
+### Task 4: Record, narrate, and edit the final two-minute video
+
+**Files:**
+
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/audio/narration.txt`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/audio/narration.aiff`
+- Create: `/Users/viraj/Desktop/.loadout-demo-2026-09-08/output/raw/loadout-demo.mov`
+- Create: `/Users/viraj/Desktop/loadout-demo-maximum-curator-1080p.mp4`
+
+**Interfaces:**
+
+- Consumes: real terminal capture and scene timestamps from Tasks 2–3.
+- Produces: an H.264 1920×1080 video no longer than 120 seconds.
+
+- [ ] **Step 1: Prepare the clean terminal framing.**
+
+  Use one Terminal window, hide unrelated panes, set a large monospace font, and
+  size the window to a 960×540-point rectangle. Only that rectangle may be
+  recorded.
+
+- [ ] **Step 2: Start macOS region capture and run the prepared scene script.**
+
+  Run:
+
+  ```bash
+  /usr/sbin/screencapture -x -v -V120 -R276,221,960,540 /Users/viraj/Desktop/.loadout-demo-2026-09-08/output/raw/loadout-demo.mov
+  ```
+
+  Capture real scenes, cutting only idle Maximum-install and provider-wait time.
+  Add visible cards reading `Maximum install — elapsed time removed` and `Real
+Claude + Codex turns — waiting time removed` at those cuts.
+
+- [ ] **Step 3: Generate concise synthetic narration.**
+
+  Write a 100–120 second narration matching the timed sequence exactly. Generate
+  it with an installed macOS synthetic voice, review it for intelligibility, and
+  keep it lower than the terminal output during provider turns.
+
+- [ ] **Step 4: Export the video.**
+
+  Run FFmpeg with H.264 video, AAC narration, `yuv420p`, and `+faststart` to
+  create `/Users/viraj/Desktop/loadout-demo-maximum-curator-1080p.mp4`.
+
+- [ ] **Step 5: Verify the final artifact.**
+
+  Run:
+
+  ```bash
+  ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 /Users/viraj/Desktop/loadout-demo-maximum-curator-1080p.mp4
+  ```
+
+  Expected: a duration at or below `120.0`. Open the exported file once and
+  verify terminal text, captions, narration, and privacy constraints visually.

package/docs/superpowers/specs/2026-09-08-fast-launch-demo-design.md

@@ -0,0 +1,42 @@
+# Fast Launch Demo Design
+
+## Goal
+
+Produce a polished 60–75 second Loadout launch video that demonstrates Maximum,
+Optimize/Curator, bundled Handoff, Coordination, and a genuine Claude Code ↔
+Codex Discussion without recording network or provider wait time.
+
+## Story
+
+The cut opens with Loadout's one-line value proposition, then moves through five
+proof points: the screened Maximum library, project-aware optimization, a
+context-bundled handoff, explicit ownership/contracts, and a previously completed
+real two-provider discussion. Rollback is omitted to protect pace.
+
+## Capture model
+
+Slow read-only commands and demo-state mutations run before screen capture and
+write their real terminal output into a disposable directory. During capture,
+the script displays the exact command followed by that saved output. The video
+labels removed setup or provider waiting time. No agent response is invented.
+
+## Audio and timing
+
+Kokoro `af_heart` narrates seven short clips generated before capture. Each scene
+remains visible for the corresponding clip duration, and the clips are assembled
+automatically into the final audio track. The recording is capped at 75 seconds.
+
+## Privacy and output
+
+The user records from a fresh full-screen Terminal window. The export is H.264,
+1920×1080, AAC audio, `yuv420p`, and Fast Start, written to
+`/Users/viraj/Desktop/loadout-demo-1080p.mp4`.
+
+## Acceptance criteria
+
+- Final duration is between 45 and 75 seconds.
+- Maximum, Optimize, Handoff, Coordination, and Discussion are visible.
+- Discussion output comes from a genuinely completed Claude Code ↔ Codex thread.
+- No rollback scene, live network wait, paid-provider wait, or unrelated project
+  UI appears.
+- The MP4 contains one video stream and one audible AAC audio stream.

package/docs/superpowers/specs/2026-09-08-maximum-curator-demo-design.md

@@ -0,0 +1,73 @@
+# Maximum + Curator flagship demo design
+
+## Goal
+
+Produce a terminal-only launch demo of no more than two minutes that proves Loadout's complete
+lifecycle without exposing unrelated Claude Code or Codex projects. The video
+uses the user's real agent setup only through terminal commands; it never opens
+either agent's project or conversation UI.
+
+## Audience and promise
+
+The video is for developers who have multiple coding agents and too many skills
+to manage. It demonstrates that Loadout can safely assemble a large reviewed
+library, select a project-relevant working set, reverse a change, transfer
+durable context, and let Claude Code and Codex make a bounded decision together.
+
+## Recording environment
+
+- Use a newly created, disposable TypeScript checkout fixture with no personal
+  files or unrelated repositories.
+- Use the published Loadout 0.9.4 CLI, not the older globally installed binary.
+- Install Maximum into all detected real agent setups only after displaying its
+  preview and safety findings and using the user's approved `--yes --approve-risk`
+  command. This preserves the user's existing active skills across agents; the
+  recorded curation and coordination scenes remain focused on Claude Code and Codex.
+- Keep the capture to a single Terminal window. Do not open Claude Code, Codex,
+  a browser, Finder, or any existing project during the take.
+- Capture only the terminal rectangle and use text overlays in post-production.
+
+## Two-minute narrative sequence
+
+| Time      | Scene            | Proof on screen                                                                                                                                      |
+| --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0:00–0:08 | Hook             | “One loadout. Every coding agent.” and the unified workflow image.                                                                                   |
+| 0:08–0:22 | Maximum          | Maximum preview summary: reviewed sources, quarantined units, deferred integrations, and the one blocked source.                                     |
+| 0:22–0:38 | Curator          | A short time-compressed Maximum apply, then `recommend` and `optimize` selecting a focused TypeScript/Node/Vitest set.                               |
+| 0:38–0:48 | Rollback         | Status, one rollback command, and the restored prior state.                                                                                          |
+| 0:48–1:03 | Handoff          | A bundled checkout task with its verification criterion and durable inbox.                                                                           |
+| 1:03–1:20 | Coordinate       | Backend/frontend ownership, a checkout contract, and Codex’s snapshot.                                                                               |
+| 1:20–1:48 | Discuss for real | One bounded, three-turn Claude Code ↔ Codex discussion. Their provider labels and actual terminal replies are visible; no provider app UI is opened. |
+| 1:48–2:00 | Replay           | Durable replay and a concise final payoff card.                                                                                                      |
+
+## Safety and truthfulness
+
+- The Maximum preview must be visible before applying. State precisely that the
+  current plan has quarantined and deferred components; do not imply every
+  catalog record is installed.
+- Never configure credentialed MCP services in the demo.
+- Do not show private projects, account identifiers beyond the CLI's ordinary
+  provider availability output, secrets, browser tabs, or notification banners.
+- Do not claim a provider exchange is live unless the recorded command actually
+  completed with both providers.
+- Maximum writes a managed library and snapshot. The Curator's project-specific
+  active set is the recommendation, not an assertion that all Maximum content is
+  good for every project.
+
+## Audio and edit
+
+- Add a concise synthetic voice walkthrough that explains each proof point in
+  plain language. It is narration, not a text-message-song treatment.
+- Use no background track under the narration or provider output; clean terminal
+  sound and subtitles take priority.
+- Show real terminal output; compress only inactive install/provider wait time,
+  with an explicit on-screen note when time is removed.
+
+## Acceptance criteria
+
+- No unrelated project or agent UI is visible in any frame.
+- The final export is 1920×1080 H.264, has a maximum duration of two minutes,
+  includes legible terminal text, captions, and synthetic voice narration.
+- The recording shows Maximum, Curator, rollback, a bundled handoff,
+  coordination ownership/contracts, a real bounded discussion, and replay.
+- A clean published 0.9.4 CLI is used and the recorded commands succeed.

package/docs/superpowers/specs/2026-09-08-social-launch-copy-design.md

@@ -0,0 +1,43 @@
+# Loadout Social Launch Copy Design
+
+## Goal
+
+Introduce Loadout on X and LinkedIn in Viraj Mishra's established voice: start
+with a concrete problem, explain what he built in plain language, support it
+with specific facts, and end with a direct invitation to try or contribute.
+
+## Positioning
+
+Loadout is the package manager for AI coding agent extensions. The launch
+should lead with the fragmented setup problem, then distinguish Loadout through
+project-aware optimization and durable Claude Code/Codex collaboration.
+
+Avoid unsupported claims such as "the first ever," "revolutionary," or
+guarantees of virality. Prefer demonstrable facts from the repository and the
+recorded product demo.
+
+## X Structure
+
+The main post contains the native video, GitHub link, product hook, and the
+strongest feature summary. It must fit the standard X character limit. A short
+reply thread then explains:
+
+1. Why agent-extension discovery and setup are broken.
+2. How Maximum and Optimize avoid prompt pollution.
+3. How Handoff carries source context and verification criteria.
+4. How Coord uses ownership and contracts for parallel work.
+5. How Discuss produces a bounded Claude Code/Codex decision.
+6. The local, preview-first trust model and install command.
+
+## LinkedIn Structure
+
+Use one longer post in Viraj's problem → evidence → product → invitation
+pattern. Include concrete repository facts, readable feature bullets, the demo,
+the install command, GitHub link, and a request for feedback, issues, stars, and
+contributions. Do not copy the X thread verbatim.
+
+## Editorial Process
+
+Codex writes the fact-checked draft. Claude receives one compact editorial turn
+to challenge the hook, pacing, and authenticity. Codex then produces the final
+paste-ready versions while retaining only claims supported by the repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "private": false,
   "license": "MIT",
   "description": "The package manager for AI coding agent extensions",
@@ -46,6 +46,7 @@
     "node": ">=20"
   },
   "scripts": {
+    "prepare": "git config core.hooksPath .githooks || true",
     "clean": "node scripts/clean-dist.mjs",
     "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.json",
@@ -86,7 +87,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@types/node": "^22.10.0",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.12.0",
@@ -94,6 +95,6 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.64.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   }
 }