loadout-ai 0.7.0 → 0.9.0

package/docs/superpowers/plans/2026-09-04-bounded-agent-discussions.md

@@ -0,0 +1,121 @@
+# Bounded Agent Discussions Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let Claude Code and Codex conduct a safe, bounded, auditable design discussion and record a final decision.
+
+**Architecture:** Add one typed discussion event to the append-only coordination protocol and reconstruct thread state from those events. A provider-neutral orchestrator alternates two responders sequentially, while a thin Commander module starts or resumes concrete Claude/Codex sessions and enforces the paid-turn budget before any turn.
+
+**Tech Stack:** TypeScript, Commander, Zod, Vitest, existing provider adapters and JSONL coordination store.
+
+## Global constraints
+
+- Exactly two participants and 1-8 rounds in the MVP.
+- Required provider turns are `rounds * 2 + 1` and may never exceed `--max-turns`.
+- Only explicit design-room responses are persisted; private reasoning is never requested or stored.
+- Discussion prompts prohibit edits and command execution.
+- Every provider turn is preceded by a kill-switch check.
+- No new dependency.
+
+---
+
+### Task 1: Define the discussion protocol and state reader
+
+**Files:**
+
+- Modify: `src/core/coordination/events.ts`
+- Create: `src/core/coordination/discussion.ts`
+- Test: `tests/coordination-discussion.test.ts`
+
+**Interfaces:**
+
+- Produces: `discussionPayloadSchema`, `DiscussionPayload`,
+  `listDiscussions(projectRoot)`, and `getDiscussion(projectRoot, threadId)`.
+
+- [ ] Write schema/state tests for strict kinds, bounds, reply IDs, bounded lists,
+      and reconstruction from real coordination events.
+- [ ] Run `npx vitest run tests/coordination-discussion.test.ts` and confirm the
+      missing exports fail.
+- [ ] Add the event schema and minimal state reader.
+- [ ] Re-run the focused test until green.
+
+### Task 2: Implement the provider-neutral bounded orchestrator
+
+**Files:**
+
+- Modify: `src/core/coordination/discussion.ts`
+- Modify: `src/core/coordination/adapters/types.ts`
+- Test: `tests/coordination-discussion.test.ts`
+- Test: `tests/coordination-adapters.test.ts`
+
+**Interfaces:**
+
+- Consumes: `emit(projectRoot, EmitOptions)` and participant `respond(prompt)`.
+- Produces: `runDiscussion(projectRoot, options): Promise<DiscussionResult>` and
+  public transcript formatting.
+
+- [ ] Write failing tests for alternating turns, reply chains, safe prompts,
+      exact turn counts, final synthesis, provider rejection, and kill switch.
+- [ ] Run the focused tests and confirm behavioral failures.
+- [ ] Implement the minimum sequential orchestration and discussion formatting.
+- [ ] Re-run the focused suites until green.
+
+### Task 3: Add the public CLI and provider-session bridge
+
+**Files:**
+
+- Create: `src/commands/coordination-discussions.ts`
+- Modify: `src/commands/coordinate.ts`
+- Modify: `src/core/coordination/session-manager.ts`
+- Test: `tests/coordination-session-commands.test.ts`
+- Test: `tests/coordination-discussion.test.ts`
+
+**Interfaces:**
+
+- Produces: `parseDiscussionAgents`, `parseDiscussionSessions`,
+  `registerCoordinationDiscussions`, and a SessionManager-backed responder.
+
+- [ ] Write failing parser and provider-composition tests.
+- [ ] Reject invalid rounds, insufficient budgets, duplicate providers, and
+      simultaneous `--agents`/`--sessions` before starting a provider session.
+- [ ] Implement `start`, `list`, and `show` with JSON output.
+- [ ] Run CLI and discussion focused suites until green.
+
+### Task 4: Integrate visibility and documentation
+
+**Files:**
+
+- Modify: `src/core/coordination/replay.ts`
+- Modify: `src/core/coordination/interrupt-policy.ts`
+- Modify: `README.md`
+- Modify: `docs/LIVE_COLLABORATION.md`
+- Modify: `docs/USER_TEST_GUIDE.md`
+- Create: `docs/decisions/003-bounded-agent-discussions.md`
+- Test: `tests/coordination-replay.test.ts`
+- Test: `tests/coordination-interrupt-policy.test.ts`
+- Test: `tests/readme-product-flow.test.ts`
+
+**Interfaces:**
+
+- Consumes: additive `discussion` events.
+- Produces: readable replay, safe-boundary delivery, and copy-paste user flows.
+
+- [ ] Write failing formatting/policy/docs assertions.
+- [ ] Add replay and injection visibility without changing existing semantics.
+- [ ] Record why the design is bounded, sequential, and local-first.
+- [ ] Run focused tests until green.
+
+### Task 5: Release-quality verification and review
+
+**Files:**
+
+- Modify: `CHANGELOG.md`
+- Modify: `tasks/plan.md`
+- Modify: `tasks/todo.md`
+
+- [ ] Run `npx vitest run 'tests/coordination*.test.ts'`.
+- [ ] Run `npm run verify:full` and inspect every exit code and test count.
+- [ ] Run `git diff --check`, inspect the complete diff for correctness,
+      readability, architecture, security, and performance, and fix findings.
+- [ ] Update the 0.9.0 changelog and task checklist with the verified behavior.
+- [ ] Commit atomically and push the feature branch; do not tag or publish npm.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "loadout-ai",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "private": false,
   "license": "MIT",
-  "description": "Universal upgrade manager for AI coding agents",
+  "description": "The package manager for AI coding agent extensions",
   "type": "module",
   "bin": {
     "loadout": "dist/src/cli.js"
@@ -15,7 +15,6 @@
     "docs",
     "README.md",
     "CHANGELOG.md",
-    "MASTER_PLAN.md",
     "SECURITY.md",
     "LICENSE"
   ],
@@ -32,10 +31,16 @@
   },
   "keywords": [
     "ai-agents",
+    "agent-skills",
+    "ai-coding",
     "codex",
     "claude-code",
+    "cursor",
+    "gemini-cli",
     "mcp",
-    "skills"
+    "skills",
+    "developer-tools",
+    "model-context-protocol"
   ],
   "engines": {
     "node": ">=20"
@@ -57,6 +62,7 @@
     "test:e2e:readme": "node scripts/readme-product-flow.mjs",
     "test:package": "node scripts/package-smoke.mjs",
     "pretest:performance": "npm run build",
+    "test:coverage": "vitest run --coverage",
     "test:performance": "node scripts/scan-benchmark.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "readme:update": "node scripts/update-readme-facts.mjs",
@@ -65,19 +71,24 @@
     "check:live": "node scripts/check-live-evidence.mjs",
     "check:allowlists": "npm run build && node scripts/check-mode-allowlists.mjs",
     "check:catalog-freshness": "npm run build && node scripts/check-catalog-freshness.mjs",
-    "check:evidence": "node scripts/check-catalog-attribution.mjs && node scripts/check-discovery-artifacts.mjs && npm run check:readme-claims",
-    "verify": "npm run format:check && npm run lint && npm run typecheck && npm run check:evidence && npm test -- --run && npm run test:e2e:cli && npm run test:e2e:readme && npm run test:package && npm run test:performance",
-    "verify:full": "npm run verify"
+    "check:audit": "npm audit --audit-level=high",
+    "check:evidence": "node scripts/check-catalog-attribution.mjs && node scripts/check-discovery-artifacts.mjs && node scripts/check-documented-commands.mjs && npm run check:readme-claims",
+    "verify": "npm run format:check && npm run lint && npm run typecheck && npm run check:audit && npm run check:evidence && npm test -- --run && npm run test:e2e:cli && npm run test:e2e:readme && npm run test:package && npm run test:performance",
+    "verify:full": "npm run verify && npm run test:coverage"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@openai/codex-sdk": "^0.153.2",
     "commander": "^12.1.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.12.0",
     "prettier": "^3.9.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",

package/skills/loadout-handoff/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: loadout-handoff
+description: Pass coding work between Claude Code and Codex, check the other agent's work, coordinate simultaneous implementation, or run a bounded two-agent design discussion. Use for delegation, pending handoffs, shared contracts and file ownership, or when the user wants both agents to debate an approach before coding.
+---
+
+# Loadout Handoff
+
+Claude Code and Codex cannot see each other. Loadout gives them a shared,
+append-only task log in the repository so work can pass between them.
+
+## Prerequisite
+
+```bash
+loadout --version
+```
+
+If that fails, tell the user to install it (`npm install --global loadout-ai`)
+and stop.
+
+## Check your inbox
+
+At the start of a session, and after finishing a task, run only the command for
+the current agent:
+
+```bash
+# When you are running in Codex
+loadout handoff codex
+
+# When you are running in Claude Code
+loadout handoff claude-code
+```
+
+If tasks are listed, work them in order and run the `loadout handoff --done <id>`
+command printed with each one. If nothing is pending, say nothing about it and
+carry on — do not narrate an empty inbox.
+
+Read the `context` line carefully. It is the only thing the sender chose to
+carry across; the rest of their conversation is not available to you.
+
+## Send a task
+
+```bash
+loadout handoff codex "write vitest coverage for src/auth.ts" --context "zod schemas already exist, stripe v16"
+```
+
+One command. It creates the log on first use and adds a short block to
+`CLAUDE.md` and `AGENTS.md` telling each agent to check its inbox.
+
+**Write the context as if the receiver knows nothing about this conversation,
+because it does not.** Include:
+
+- the files involved, by path
+- decisions already made, so they are not relitigated
+- what you deliberately left out and why
+- how to tell the work is finished
+
+A task with no context usually comes back wrong or gets redone.
+
+## When to suggest a handoff
+
+Delegating has a real cost: the other agent starts cold and the user has to
+switch windows. It is worth it when:
+
+- the work is genuinely separable, like tests for code that is already written
+- a second opinion matters more than continuity, such as reviewing a change you
+  authored
+- the user has said they want to spread work across their two subscriptions
+
+It is not worth it for something you could finish in the next few minutes.
+
+## Confirm before sending
+
+Sending writes to a shared file in the user's repository. Confirm first unless
+they asked for the handoff themselves.
+
+## Seeing everything
+
+```bash
+loadout handoff              # every pending task, both directions
+loadout handoff --done 4f2a1c
+```
+
+If the log reports unreadable lines, tell the user which line numbers — the log
+is append-only and a partial write can leave one corrupt entry. The remaining
+messages are still shown.
+
+## Live coordination (automatic)
+
+When the user says both agents are working simultaneously (e.g. "Claude does
+backend, Codex does frontend"), **you handle coordination automatically**. The
+user should never have to type `loadout coord` commands — that is your job.
+
+### At session start — check for updates
+
+Use the current agent id in every command: `claude-code` inside Claude Code and
+`codex` inside Codex.
+
+```bash
+loadout coord snapshot <current-agent> --json
+```
+
+If there are unacknowledged events (contracts, decisions, ownership claims from
+the other agent), read them, incorporate them into your work, and acknowledge:
+
+```bash
+loadout coord ack <current-agent> <seq>
+```
+
+Tell the user briefly what the other agent has been doing: "Codex published
+auth-api rev2 — I'll build against that contract."
+
+### When you start working on files — claim ownership
+
+Before writing to files, claim them so the other agent knows not to touch them:
+
+```bash
+loadout coord own <current-agent> src/api/ src/db/ --json
+```
+
+If there's a conflict (other agent already owns those paths), tell the user and
+ask how to proceed. Do not silently overwrite another agent's work.
+
+### When you create or change an API/schema/interface — publish a contract
+
+Whenever you create or modify something the other agent depends on (API
+endpoints, database schemas, TypeScript interfaces, environment variables),
+publish it:
+
+```bash
+loadout coord contract auth-api --body "export interface AuthAPI {
+  login(credentials: LoginRequest): Promise<Session>;
+  logout(sessionId: string): Promise<void>;
+  refresh(token: string): Promise<Session>;
+}" --format typescript --agent <current-agent>
+```
+
+The revision auto-increments. The other agent sees it on their next check.
+
+### When you finish a chunk of work — report progress
+
+```bash
+loadout coord update <current-agent> --note "Auth endpoints done, rate limiting added" --files src/api/auth.ts src/api/middleware.ts --next "Starting payment integration"
+```
+
+Release exact paths when you are finished with them so ownership does not stay
+stale:
+
+```bash
+loadout coord release <current-agent> src/api/ src/db/
+```
+
+### When you make a design decision — record it
+
+```bash
+loadout coord decide <current-agent> "Use JWT for session tokens" --rationale "Stateless, works across services, Codex frontend can decode without API call"
+```
+
+### When the user asks what the other agent is doing
+
+```bash
+loadout coord snapshot <current-agent>
+```
+
+This shows pending tasks, active contracts, file ownership, recent decisions,
+and unacknowledged events in one bounded summary.
+
+## Live daemon mode
+
+If the user starts `loadout daemon start`, dashboards and custom clients can
+observe the local event stream via authenticated SSE:
+
+- Open the authenticated dashboard URL printed by the command.
+- REST and SSE require a bearer token; query-string tokens are rejected.
+- The dashboard observes events. It does not inject them into an agent session.
+
+All write paths redact secret-like data at the shared storage boundary.
+
+## Provider bridge mode (opt-in)
+
+### Debate one design before coding
+
+When the user explicitly asks Claude Code and Codex to compare approaches on
+the same feature before either agent writes code, offer a bounded discussion:
+
+```bash
+loadout coord discuss start "REST or GraphQL for checkout?" \
+  --agents claude-code,codex --rounds 2 --max-turns 5
+```
+
+Use `--proposer codex` to swap roles, or reuse explicit sessions with
+`--sessions claude-code:<session-id> codex:<thread-id>`. Each round gives both
+agents one turn and the final synthesis uses one more turn. Tell the user the
+exact number of paid provider turns. Do not start without an explicit user request.
+
+The design room records only responses produced for that public discussion.
+It tells both agents not to edit files, run commands, use tools, or reveal
+private reasoning. Review the final decision with the user before claiming
+ownership or beginning implementation. Inspect it later with
+`loadout coord discuss show <thread-id>`.
+
+### Route implementation events
+
+When the user explicitly wants automatic follow-up turns, they can run:
+
+```bash
+loadout coord agents detect
+loadout coord agents bridge claude-code:<session-id> codex:<thread-id>
+```
+
+The bridge uses supported provider interfaces and delivers relevant events at
+safe turn boundaries. It cannot steer a turn already in progress. Progress
+updates are passive by default, one bridge may own a project, and automatic
+turns stop after 20 per session unless the user changes `--max-turns`. Starting,
+attaching, sending, or bridging provider sessions can consume the user's
+provider quota, so do not do it without an explicit request.
+
+## What this is not (without the provider bridge)
+
+Without a provider bridge, the other agent is **not given a new turn
+automatically**. The daemon can receive events instantly, but an agent sees them
+when it next checks its MCP tools, snapshot, or subscription. If the user needs
+work now, tell them to open the other agent or explicitly start a bridge.
+
+## Summary of when to run what
+
+| Moment                                     | What to run                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------- |
+| Session start                              | `loadout handoff <agent>` + `loadout coord snapshot <agent> --json` |
+| Before writing files                       | `loadout coord own <agent> <paths...>`                              |
+| Created/changed an API or schema           | `loadout coord contract <name> --body "..." --agent <agent>`        |
+| Finished a chunk of work                   | `loadout coord update <agent> --note "..." --files "..."`           |
+| Finished writing owned paths               | `loadout coord release <agent> <paths...>`                          |
+| Made a design decision                     | `loadout coord decide <agent> "<title>" --rationale "..."`          |
+| Both agents should compare a design        | `loadout coord discuss start "<topic>" --agents claude-code,codex`  |
+| After reading other agent's events         | `loadout coord ack <agent> <seq>`                                   |
+| User asks "what is the other agent doing?" | `loadout coord snapshot <agent>`                                    |
+| Delegating a task                          | `loadout handoff <other-agent> "<task>" --context "..."`            |
+| Task complete                              | `loadout handoff --done <id>`                                       |