@limina-labs/momentum 0.30.2

package/adapters/claude-code/commands/swarm.md

@@ -0,0 +1,242 @@
+Swarm — sustained parallel multi-project feature delivery (Phase 17, v0.20.0).
+
+A **swarm** is a declared cross-repo work unit driven from ONE user session. The user's session becomes the **conductor**. The conductor spawns one **supervisor** subagent per impacted repo, each pinned to that repo's working directory with its own fresh context. Each supervisor runs momentum's normal `/start-phase` → implement → `/sync-docs` → `/complete-phase` loop INSIDE its repo. The conductor coordinates waves (computed from `ecosystem.json` dependency edges), surfaces inbox decisions, broadcasts cross-cutting concerns, and synthesizes per-repo retrospectives at fan-in.
+
+> v0.20.0 ships Claude Code only. Codex + Antigravity parity is Phase 18.
+
+## Architecture
+
+| Layer | Owns | Reads |
+|---|---|---|
+| Conductor (this user session) | `<eco>/swarms/<id>/manifest.json` + `board.json` + `contracts/` + `inbox/` + `signals/` + `changes/` | Per-supervisor `dispatch-run-<id>.json` (status) |
+| Supervisor (per repo, background) | `<repo>/specs/phases/phase-N-<slug>/*` + `<repo>/.momentum/runs/dispatch-run-<id>.json` | Its phase brief + contract + history.md tail |
+
+Agents are stateless across turns; **state lives in files**. A swarm survives session boundaries the same way a phase does — every state-changing action writes to disk; `/swarm resume` reconstitutes from disk.
+
+## When to use
+
+- A feature spans **two or more momentum-installed repos** AND has dependency ordering (frontend depends on backend depends on shared-types).
+- The user wants ONE session driving the whole feature, not three serial sessions.
+- An initiative exists or is about to exist at `<eco>/initiatives/<slug>.md`.
+
+Do NOT use `/swarm` for:
+- Read-only cross-repo audits — use `/dispatch`.
+- Single-repo phases — use `/start-phase` directly.
+- Pure context transfer — use `/handoff`.
+
+## Subcommands
+
+The slash command form mirrors the CLI: `/swarm <sub> [args]`. The CLI floor is `momentum swarm <sub> [args]` — pick whichever door fits the moment. Both produce the same on-disk artifacts.
+
+---
+
+### `/swarm start <slug> --initiative <slug> --repos r1,r2,... --phase <phase-slug> [--mode checkpoint|autopilot]`
+
+Plan + spawn Wave 1.
+
+**Step 1 — Present the plan and ask for approval.**
+
+Compute the wave plan in-process (no spawn yet) by calling the CLI floor in dry-run:
+
+```bash
+momentum swarm start <slug> --initiative <slug> --repos r1,r2,... --phase <phase-slug> --mode <mode> --json
+```
+
+Read the JSON. Render the wave plan to the user:
+
+```
+▸ Swarm <NNNN-slug> — planned (not yet spawning)
+  Initiative: <slug>
+  Mode: <mode>
+  Waves:
+    Wave 1: <r1>, <r2>
+    Wave 2: <r3>
+    Wave 3: <r4>
+  Token budget: 300k per supervisor (override with /swarm budget)
+  Lease: 24h per repo, renewed each turn
+
+Proceed?
+```
+
+WAIT for user approval. If `mode = autopilot`, plan approval is the only checkpoint until completion. If `mode = checkpoint`, you'll also pause between waves.
+
+**Step 2 — Spawn Wave 1 supervisors (foreground synthesis, background sessions).**
+
+After approval, spawn one Claude Code background session per Wave 1 repo. The CLI does this when invoked with `--spawn`:
+
+```bash
+momentum swarm start <slug> --initiative <slug> --repos ... --phase <phase-slug> --mode <mode> --spawn
+```
+
+If `claude --bg` is not available in this env, the CLI surfaces the spawn directives and exits — degrade by reporting the directives to the user (they can launch sessions manually) and continue with conductor polling on the existing manifest.
+
+**Step 3 — Begin the conductor poll loop.**
+
+See `/swarm status` (next subcommand). On every conductor turn:
+
+1. Read `<eco>/swarms/<id>/board.json` (≈3KB).
+2. Read `<eco>/swarms/<id>/inbox/INDEX.md`.
+3. If `inbox_count > 0`, surface each pending item; resolve interactively.
+4. If a supervisor reports `done: true` for the active wave's last repo, run the wave checkpoint flow (see `/swarm verify` — Phase 17 G2).
+
+---
+
+### `/swarm status <swarm-id>`
+
+Render the materialized board cache. Read-only — no manifest mutation. Strategy A from the indexing design: conductor reads ONLY `board.json` (~3KB).
+
+```bash
+momentum swarm status <swarm-id>
+```
+
+Default output is a rendered ANSI table. Pass `--json` for machine-readable.
+
+Surface:
+- Per-repo: wave, status, tasks N/M, tokens used/budget, commits, current task.
+- `inbox_count` warning at the bottom if > 0.
+- Recent activity tail (last 10 audit events).
+
+When inboxes are pending, prompt: "Run `/swarm verify <id>` to surface the questions, or `/swarm tell <id> <repo> '...'` to push context to a specific supervisor."
+
+---
+
+### `/swarm claim <swarm-id> <repo> [--session <id>] [--lease-hours 24]`
+
+> Phase 17.5 / v0.20.2 — multi-session ownership primitive.
+
+Claim ownership of `<repo>` inside `<swarm-id>` for the current session. The conductor library uses this whenever a session needs authority to write to a repo's manifest entry — `/swarm focus`, `/swarm join`, and a co-conductor taking a wave all compose `claim` under the hood.
+
+```bash
+momentum swarm claim <swarm-id> <repo> [--session <id>] [--lease-hours 24]
+```
+
+Claim succeeds when:
+- the repo is `_unclaimed` or `_focusing` (sentinel — anyone may claim), OR
+- the current owner's `lease_expires_at` is in the past (takeover; audit logs both `claim` and `lease-takeover`).
+
+Claim is rejected when the current owner's lease is still valid; the CLI writes a `claim-request` signal so the existing owner sees the request on their next conductor poll. Exit code 1 on rejection.
+
+On success the manifest sets `owner = <session>`, refreshes `lease_renewed_at`, and sets `lease_expires_at = now + <lease-hours>`. The board cache is refreshed.
+
+---
+
+### `/swarm focus <swarm-id> <repo> [--session <id>] [--expires-min 60]`
+
+> Phase 17.5 / v0.20.2 — split one repo off the swarm into a side-session.
+
+Issue a single-use focus token for `<repo>` and hand control to a second Claude Code session. Use when one repo needs sustained one-on-one attention without halting the rest of the swarm. The original conductor keeps every other repo; the new side-session takes `<repo>` and drives its phase to completion. Reunite via `/swarm absorb`.
+
+```bash
+momentum swarm focus <swarm-id> <repo> [--session <id>] [--expires-min 60]
+```
+
+Behavior:
+1. Asserts the caller currently owns `<repo>` (rejected with exit 1 if not).
+2. Issues an opaque focus token at `<eco>/swarms/<id>/tokens/<token>.json` (single-use, 1-hour default expiry).
+3. Flips `repos[<repo>].owner` to the `_focusing` sentinel — anyone with the token may claim.
+4. Writes a `focus-request` signal carrying the token + repo.
+5. Audit-logs `focus`.
+6. Prints a spawn directive — run `claude --bg --cwd <eco>` in a second terminal, then inside that session call `momentum swarm join <swarm-id> --token <token>`.
+
+The token is single-use: consuming it (via `/swarm join --token`) deletes the file and atomically flips ownership to the receiver. If the token expires before consumption, run `/swarm claim <repo>` against the FOCUSING sentinel to recover.
+
+---
+
+### `/swarm join <swarm-id> [--token <token>] [--claim <repo>] [--session <id>]`
+
+> Phase 17.5 / v0.20.2 — register a session with an existing swarm.
+
+Attach the current session to `<swarm-id>` as a co-conductor. Adds the session to `sessions[]` (idempotent — touch on re-join), auto-renews any repos the session already owns, and optionally consumes a transfer token or claims a specific repo.
+
+```bash
+momentum swarm join <swarm-id> [--token <token>] [--claim <repo>] [--session <id>]
+```
+
+Three shapes:
+
+| Form | Result |
+|---|---|
+| `join <id>` | Registration only. Adds the session; renews any owned leases. |
+| `join <id> --token <token>` | Consumes the token. If `kind=focus`, claims the token's `target_repo` automatically. If `kind=join`, registers only (equivalent to plain join). |
+| `join <id> --claim <repo>` | Explicit claim — bound by the same lease rules as `/swarm claim`. Exits 1 if rejected. |
+
+Exit codes:
+- 0 on success.
+- 1 if the swarm doesn't exist, the token is missing/expired, or the claim is rejected (`EOWNERSHIP`).
+
+Audit log gets a `join` entry detailing the route — `registration only` / `via token kind=…` / `with --claim …`.
+
+---
+
+### `/swarm absorb <target-swarm-id> <source-swarm-id> [--yes] [--session <id>]`
+
+> Phase 17.5 / v0.20.2 — converge two swarms back into one.
+
+Merge `<source-swarm-id>` into `<target-swarm-id>` (the caller's swarm). Use to reunite after a `/swarm focus` split, or to absorb work from a peer swarm that's now done.
+
+```bash
+momentum swarm absorb <target-swarm-id> <source-swarm-id> [--yes] [--session <id>]
+```
+
+Behavior:
+1. Loads both manifests. If either is missing → exit 1.
+2. Detects contract conflicts: for every shared `surface` in both swarms' `contracts`, the `owner` must match and the `content_hash` (when present) must match. Mismatches abort cleanly — both swarms left untouched — with a printed diff for each conflict.
+3. Without `--yes`, prints a dry-run plan (repos to add, overlap, contract status) and exits 0 without writing. Re-run with `--yes` to proceed.
+4. On commit:
+   - `repos`: union; target wins on overlap (so a repo already in flight in target is not regressed by source's state)
+   - `waves`: recomputed via the wave-ordering library over the union of repos, against `ecosystem.json` dependencies
+   - `sessions[]`: union by `session_id` (earliest `first_seen`, latest `last_seen`)
+   - `contracts`: union; target's version kept on overlap (we verified compatibility above)
+   - `audit[]`: concat + sort by timestamp; append an `absorb` entry
+   - `inbox/`: source's pending items copied into target with bumped ids
+5. Archives the source swarm directory to `<eco>/swarms/.absorbed/<source-id>/`. Forensics preserved.
+6. Refreshes target's `board.json`.
+
+JSON output (`--json`) returns `{ absorbed, into, reposAdded, reposOverlapped, inboxMoved, archivedTo }`.
+
+---
+
+### `/swarm release <swarm-id> <repo> [--session <id>]`
+
+> Phase 17.5 / v0.20.2 — multi-session ownership primitive.
+
+Release the current session's ownership of `<repo>`. Sets `owner = _unclaimed`, clears the lease, and audit-logs `release`. Idempotent — releasing an already-unclaimed repo is a no-op.
+
+```bash
+momentum swarm release <swarm-id> <repo> [--session <id>]
+```
+
+Only the current owner may release. Attempting to release a repo you don't own exits 1 (you'd need `/swarm claim` against an expired lease, or the owner to release first).
+
+---
+
+### `/swarm cancel <swarm-id> [--reason "<text>"]`
+
+Graceful halt. Halts every supervisor, marks the swarm `cancelled` in the manifest, preserves all artifacts for forensics.
+
+```bash
+momentum swarm cancel <swarm-id> --reason "<text>"
+```
+
+**Confirm with the user before running.** Cancel is reversible only via `/swarm resume` re-attaching to a frozen state — you cannot un-cancel a wave that was mid-flight if commits have been pushed and force-overwrites would be needed.
+
+After cancel:
+1. All queued/running/blocked repos move to `cancelled`.
+2. All queued/running waves move to `cancelled`.
+3. Branches remain — supervisors do NOT force-push or delete.
+4. Audit log gains a `cancel` entry with the reason.
+
+---
+
+## Tracking contract
+
+- **Auto every time:** `manifest.json` writes via the conductor library; `board.json` regenerated on each write.
+- **Auto only when meaningful:** `[SWARM]` entry in each supervisor's repo `history.md` after wave completion; `[NOTE]` in the originating session log on wave transitions.
+- **Never:** silent overwrites of supervisor branches. Cancel preserves; resume reconstitutes.
+
+## Errors
+
+- Ecosystem root not found → suggest `--ecosystem <path>` or running from inside an ecosystem.
+- Repo arg not a member → list valid members and abort.
+- Initiative does not exist → suggest `momentum ecosystem initiative create <slug>` and abort.
+- `claude --bg` not on PATH → degrade to dry-run + manual spawn instructions.

package/adapters/claude-code/instructions/header.md

@@ -0,0 +1,3 @@
+# Project Rules: <Project Name>
+
+> Claude Code configuration for this project.

package/adapters/claude-code/instructions/vars.json

@@ -0,0 +1 @@
+{ "TASK_TOOL": "the built-in **TodoWrite** tool", "TASK_TOOL_NAME": "TodoWrite" }

package/adapters/claude-code/settings.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/brainstorm-gate.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/check-history-reminder.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/sessionstart-handoff.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/adapters/codex/adapter.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// Codex adapter for momentum.
+//
+// Codex uses AGENTS.md as its primary repository instruction surface. Generic
+// momentum command recipes install into .codex/commands/ via the standard
+// overlay, then are transformed in `runInstall` into native Codex skills at
+// .agents/skills/<name>/SKILL.md so each recipe becomes a first-class
+// auto-discoverable skill (per https://developers.openai.com/codex/skills).
+// The .codex/commands/ directory is removed post-transform — skills are the
+// canonical surface, not lookup fragments.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+module.exports = {
+  displayName: 'Codex',
+
+  destinations: {
+    commands: ['.codex', 'commands'],
+    'agent-rules': ['.agent', 'rules'],
+    scripts: ['scripts'],
+    engines: ['.agent', 'engines'],
+    // Phase 16 Rework: native Codex surfaces.
+    // Skills live at .agents/skills/ (shared with Antigravity; NOT .codex/skills/)
+    // Subagents live at .codex/agents/ (TOML files)
+    // workflows declared but unused on Codex (no native workflow surface)
+    workflows: ['.codex', 'workflows'],
+    skills: ['.agents', 'skills'],
+    agents: ['.codex', 'agents'],
+  },
+
+  primaryInstruction: {
+    source: ['instructions', 'AGENTS.md'],
+    destination: ['AGENTS.md'],
+    label: 'AGENTS.md',
+    markerAware: true,
+  },
+
+  configFiles: [
+    {
+      source: ['hooks.json'],
+      destination: ['.codex', 'hooks.json'],
+      label: '.codex/hooks.json',
+    },
+  ],
+
+  capabilities: {
+    hooks: true,
+    slashCommands: true,
+    subagents: true,
+    parallelSubagents: false,
+    sessionStartHook: true,
+    skills: true,
+    browser: true,
+    computerUse: true,
+  },
+
+  roadmap: {
+    subagents:
+      'Codex declares a subagent surface; parallel-fanout not yet validated by momentum smoke tests. ' +
+      'capability-routing treats this as sequential until proven.',
+    parallelSubagents:
+      'Promote to true once dispatch parallel mode is exercised against Codex in CI (VAL-001).',
+  },
+
+  runInstall(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged, dryRun } = helpers;
+
+    console.log('→ Configuring Codex hooks...');
+    const hooksDest = path.join(targetDir, '.codex', 'hooks.json');
+    if (recordManaged) recordManaged(hooksDest); // managed regardless of write
+    if (!fileExists(hooksDest)) {
+      copyFile(path.join(adapterDir, 'hooks.json'), hooksDest);
+    } else {
+      console.log('  ⚠️  .codex/hooks.json already exists.');
+      console.log(`     Merge hooks manually from: ${path.join(adapterDir, 'hooks.json')}`);
+    }
+
+    console.log('→ Transforming recipes into native Codex skills...');
+    if (dryRun) console.log('  ✋ would generate skills at .agents/skills/ from recipes');
+    else transformCommandsIntoSkills(targetDir, recordManaged);
+  },
+
+  runUpgrade(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged, dryRun } = helpers;
+
+    console.log('→ Upgrading Codex hooks...');
+    const src = path.join(adapterDir, 'hooks.json');
+    const dest = path.join(targetDir, '.codex', 'hooks.json');
+    if (recordManaged) recordManaged(dest); // managed even when identical-skip
+
+    if (fileExists(dest)) {
+      const srcContent = fs.readFileSync(src, 'utf8');
+      const destContent = fs.readFileSync(dest, 'utf8');
+      if (srcContent !== destContent) {
+        if (dryRun) {
+          console.log('  ✋ would upgrade: .codex/hooks.json');
+        } else {
+          fs.copyFileSync(dest, dest + '.bak');
+          copyFile(src, dest);
+          console.log('  ↑ upgraded: .codex/hooks.json (original saved as .bak)');
+        }
+      }
+    } else {
+      copyFile(src, dest);
+      console.log(`  ${dryRun ? '✋ would add:    ' : '+ added:   '} .codex/hooks.json`);
+    }
+
+    console.log('→ Re-generating Codex skills from recipes...');
+    if (dryRun) console.log('  ✋ would re-generate skills at .agents/skills/ from recipes');
+    else transformCommandsIntoSkills(targetDir, recordManaged);
+  },
+
+  // Phase 18 G1 — adapter.spawn(directive) for Codex.
+  // Shells `codex --cwd <repoPath>` with the supervisor TOML as the
+  // subagent declaration. The MCP cwd shim (see AGENTS.md → "## MCP
+  // cwd shim — Codex configuration") keeps file ops inside the
+  // pinned cwd. See `bin/momentum.js` for the directive contract.
+  spawn(directive) {
+    if (!directive || directive.platform !== 'codex') {
+      return {
+        repoId: directive && directive.repoId,
+        status: -1,
+        detail: `non-codex platform: ${directive && directive.platform}`,
+      };
+    }
+    const codexBin = process.env.CODEX_BIN || 'codex';
+    const args = ['--cwd', directive.repoPath, '--agent', 'swarm-supervisor'];
+    const prompt = [
+      `You are a swarm supervisor. Recipe: ${directive.recipePath}`,
+      `Read the recipe and the brief at specs/phases/${directive.phaseSlug}/overview.md.`,
+      `Your repo: ${directive.repoId}. Your swarm: ${directive.swarmId} wave ${directive.wave}.`,
+      `Begin the boot sequence.`,
+    ].join('\n');
+    const r = spawnSync(codexBin, args, {
+      input: prompt,
+      env: Object.assign({}, process.env, directive.env),
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    return {
+      repoId: directive.repoId,
+      status: r.status == null ? -1 : r.status,
+      detail: (r.error && r.error.message) || (r.stderr || '').slice(0, 200),
+    };
+  },
+};
+
+// ─── Recipes → Skills transform (ENH-036) ────────────────────────────────────
+//
+// Per https://developers.openai.com/codex/skills the canonical project-scope
+// skill surface is $REPO_ROOT/.agents/skills/<name>/SKILL.md with YAML
+// frontmatter declaring `name` + `description`. Each momentum recipe becomes
+// one such skill so Codex auto-discovers and dispatches them natively (rather
+// than the AGENTS.md-lookup-then-follow-instructions pattern that shipped in
+// v0.19.0).
+function transformCommandsIntoSkills(targetDir, recordManaged) {
+  const commandsDir = path.join(targetDir, '.codex', 'commands');
+  const skillsRoot = path.join(targetDir, '.agents', 'skills');
+  if (!fs.existsSync(commandsDir)) {
+    console.log('  (no .codex/commands/ to transform — skipping)');
+    return;
+  }
+  fs.mkdirSync(skillsRoot, { recursive: true });
+
+  let count = 0;
+  for (const file of fs.readdirSync(commandsDir)) {
+    if (!file.endsWith('.md')) continue;
+    const name = file.replace(/\.md$/, '');
+    const body = fs.readFileSync(path.join(commandsDir, file), 'utf8');
+    const description = extractRecipeDescription(body, name);
+
+    const skillDir = path.join(skillsRoot, name);
+    fs.mkdirSync(skillDir, { recursive: true });
+    const skillBody = renderSkillMarkdown(name, description, body);
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    fs.writeFileSync(skillPath, skillBody);
+    // Generated skills are momentum-managed — record them so they appear in
+    // the lock file and a dropped recipe's skill is orphan-cleaned (Phase 20).
+    if (recordManaged) recordManaged(skillPath);
+    count++;
+  }
+
+  // Remove the lookup-fragment directory — skills are now the canonical
+  // surface. Keep .codex/agents/ + .codex/hooks.json + .codex/swarm/ etc.
+  fs.rmSync(commandsDir, { recursive: true, force: true });
+  console.log(`  + ${count} skill(s) generated at .agents/skills/ from recipes`);
+  console.log('  - .codex/commands/ removed (skills replace lookup fragments)');
+}
+
+// Extract the first non-heading, non-blank line of the recipe as the skill
+// description. Recipes follow a consistent house-style where line 1 is a
+// one-sentence "what it does" — well suited to Codex's "describe when to
+// trigger" requirement.
+function extractRecipeDescription(body, name) {
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith('#')) continue;
+    // Strip wrapping markdown emphasis if present.
+    return trimmed
+      .replace(/^[*_]+|[*_]+$/g, '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+  return `Run the momentum ${name} recipe.`;
+}
+
+function renderSkillMarkdown(name, description, recipeBody) {
+  // YAML frontmatter must escape colons / newlines. The description is one
+  // line by construction (extractRecipeDescription guarantees this), so a
+  // simple double-quoted string is safe — but we still escape embedded
+  // double-quotes and backslashes.
+  const safeDescription = description.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return [
+    '---',
+    `name: ${name}`,
+    `description: "${safeDescription} Activates when the user invokes /${name} or asks momentum to run the ${name} recipe."`,
+    '---',
+    '',
+    recipeBody.endsWith('\n') ? recipeBody : recipeBody + '\n',
+  ].join('\n');
+}

package/adapters/codex/agents/momentum-reviewer-architecture.toml

@@ -0,0 +1,57 @@
+# momentum reviewer — Architecture lens (Codex)
+#
+# Installed by momentum init/upgrade --agent codex into .codex/agents/.
+
+name = "momentum-reviewer-architecture"
+
+description = """
+Review a code diff for architectural fit, rule compliance, and pattern
+consistency. Returns Critical/Important/Minor findings ONLY — does not
+modify code, does not refactor. Dispatched by the review-code recipe.
+"""
+
+developer_instructions = """
+You are an architecture-focused code reviewer dispatched by the momentum
+toolkit. You will receive a code diff and the project's full rules
+(AGENTS.md — the complete rulebook).
+
+YOUR LENS: architectural fit, rule compliance, pattern consistency.
+
+For each change, ask:
+- Does it violate any of the 12 autonomous rules (orient first, update
+  tracking, auto-track discoveries, pre-phase bug check, phase boundary
+  awareness, git lifecycle, plan before implementing, record history,
+  doc sync protocol, architecture stability, evaluator discipline,
+  verify before claim)?
+- Does it match the patterns established elsewhere in the codebase?
+  Read 2-3 nearby files for convention.
+- Does it create hidden coupling, a leaky abstraction, or an
+  adapter/contract violation? (For momentum specifically: every
+  capability declaration uniform-boolean; overlay subdirs use the
+  destinations contract; adapter-specific code stays in adapters/,
+  generic in core/.)
+- Is it documented where rules say it should be (history.md entry, ADR
+  for decisional changes, backlog entry for discovered issues)?
+- Does the commit message convention match (feat / fix / docs / etc.)?
+
+Output format — return EXACTLY this structure:
+
+```
+## Architecture review
+
+### Critical
+- [finding] (file:line) — [why it's critical]
+
+### Important
+- [finding] (file:line) — [explanation]
+
+### Minor
+- [finding] (file:line) — [explanation]
+```
+
+If no findings at a severity level, write "(none)". Do NOT speculate
+beyond what the diff shows. Do NOT refactor yourself — flag the
+issue. Do NOT modify any files.
+"""
+
+sandbox_mode = "read-only"

package/adapters/codex/agents/momentum-reviewer-qa.toml

@@ -0,0 +1,52 @@
+# momentum reviewer — QA lens (Codex)
+#
+# Installed by momentum init/upgrade --agent codex into .codex/agents/.
+
+name = "momentum-reviewer-qa"
+
+description = """
+Review a code diff for test coverage, edge cases, and regression risk.
+Returns Critical/Important/Minor findings ONLY — does not modify code,
+does not write tests. Dispatched by the review-code recipe on the
+current branch's pending changes.
+"""
+
+developer_instructions = """
+You are a QA-focused code reviewer dispatched by the momentum toolkit.
+You will receive a code diff and a project-rules excerpt (especially
+Rule 12 — Verify Before Claim).
+
+YOUR LENS: test coverage, edge cases, regression risk.
+
+For each meaningful behavior change in the diff, ask:
+- Is there a test that exercises it? If yes, does it test the happy
+  path AND at least one edge case?
+- What edge cases are uncovered? Consider: empty input, large input,
+  concurrent access, error paths, network/IO failures, malformed data,
+  Unicode / non-ASCII, very long strings, off-by-one boundaries.
+- Could this change break an existing test or production path? Look
+  for callers of any modified function.
+- Does the change add a verification command, or rely on "should work
+  now" — Rule 12 territory.
+
+Output format — return EXACTLY this structure:
+
+```
+## QA review
+
+### Critical
+- [finding] (file:line) — [why it's critical]
+
+### Important
+- [finding] (file:line) — [explanation]
+
+### Minor
+- [finding] (file:line) — [explanation]
+```
+
+If no findings at a severity level, write "(none)". Do NOT speculate
+beyond what the diff shows. Do NOT write tests yourself — flag the
+gap. Do NOT modify any files.
+"""
+
+sandbox_mode = "read-only"

package/adapters/codex/agents/momentum-reviewer-security.toml

@@ -0,0 +1,57 @@
+# momentum reviewer — Security lens (Codex)
+#
+# Installed by `momentum init/upgrade --agent codex` into .codex/agents/.
+# Discovered automatically by Codex from .codex/agents/*.toml per vendor docs.
+# Spawned by natural language ("review the diff for security" or
+# "run momentum-reviewer-security"), typically as one of three parallel
+# subagents from the /review-code recipe.
+
+name = "momentum-reviewer-security"
+
+description = """
+Review a code diff through a security lens (OWASP Top 10, STRIDE threat
+categories). Returns Critical/Important/Minor findings ONLY — does not
+modify code, does not propose fixes. Dispatched by the review-code recipe
+on the current branch's pending changes.
+"""
+
+developer_instructions = """
+You are a security-focused code reviewer dispatched by the momentum
+toolkit. You will receive a code diff and a project-rules excerpt.
+
+YOUR LENS: OWASP Top 10 + STRIDE threat categories.
+
+Things to look for:
+- Hard-coded secrets, credentials, API keys
+- SQL/NoSQL injection vectors, unparameterized queries
+- XSS / SSRF / CSRF surfaces in any user-controlled input path
+- Authentication / authorization gaps in newly added endpoints
+- Insecure deserialization, prototype pollution
+- Logging of sensitive data (PII, tokens)
+- Race conditions / TOCTOU in security-relevant code paths
+- Cryptographic anti-patterns (weak algorithms, fixed IVs, MD5/SHA1
+  for security, broken random sources)
+- Dependency additions of known-vulnerable packages
+
+Output format — return EXACTLY this structure:
+
+```
+## Security review
+
+### Critical
+- [finding] (file:line) — [why it's critical]
+
+### Important
+- [finding] (file:line) — [explanation]
+
+### Minor
+- [finding] (file:line) — [explanation]
+```
+
+If no findings at a severity level, write "(none)". Do NOT speculate
+beyond what the diff shows. Do NOT propose code fixes — flag only.
+Do NOT modify any files. Do NOT run any code-modifying commands.
+"""
+
+# Read-only sandbox — reviewers cannot modify the codebase.
+sandbox_mode = "read-only"