@limina-labs/momentum 0.30.2

package/adapters/codex/instructions/header.md

@@ -0,0 +1,3 @@
+# Project Rules: <Project Name>
+
+> Codex configuration for this momentum-managed project.

package/adapters/codex/instructions/surfaces.md

@@ -0,0 +1,206 @@
+## Momentum Recipes — Codex Skills
+
+Each momentum recipe ships as a native Codex skill at
+`.agents/skills/<name>/SKILL.md` ([Codex skills
+docs](https://developers.openai.com/codex/skills)). Codex auto-discovers
+skills under `.agents/skills/` at session start across CLI, IDE, and
+desktop app — so when the user invokes `/brainstorm-phase`, asks "run
+brainstorm-phase", or types `$brainstorm-phase`, Codex routes directly
+to that skill.
+
+The shipped recipe set (one skill per recipe, all under
+`.agents/skills/`):
+
+| Recipe | What it does |
+|---|---|
+| brainstorm-idea | Explore an idea before scaffolding anything |
+| brainstorm-phase | Plan the next implementation phase (gate-protected) |
+| start-project | Scaffold a new spec-driven project |
+| start-phase | Begin a planned phase (autonomous execution contract) |
+| complete-phase | Verify, retro, release a finished phase |
+| sync-docs | Propagate history entries to other spec docs |
+| track | Track a backlog item (bug / feature / tech debt / enhancement) |
+| review | Review and groom the backlog between phases |
+| log | Append a manual narrative entry to the history of the phase bound to your branch (fallback: status.md) |
+| migrate | Onboard an existing project into momentum |
+| validate | Check spec structure health |
+| ecosystem | Cross-repo ecosystem coordination |
+| initiative | Manage cross-repo initiatives |
+| session | Append a manual narrative entry to today's ecosystem session log |
+| systematic-debug | Systematically isolate, reproduce, and resolve task execution failures |
+| scout | Read-only context fetch from one ecosystem member repo |
+| dispatch | Parallel multi-repo fan-out + synthesis |
+| handoff | Cross-session control transfer with structured context block |
+| continue | Pick up a pending handoff in this repo |
+| review-code | Multi-perspective code review (uses momentum-reviewer-* subagents) |
+| swarm | Sustained parallel multi-project feature delivery (uses swarm-supervisor subagent) |
+| momentum-orient | Read `specs/status.md` before starting any work (Rule 1) |
+
+Each `SKILL.md` declares `name` + `description` frontmatter and includes
+the full recipe body. The recipes are platform-independent — they
+describe what to do, not how Codex specifically should do it. When you
+read a recipe that mentions "use the Task tool" (Claude Code
+terminology), translate to Codex's equivalent: spawn the relevant
+`momentum-reviewer-*` subagent (see below), or use natural-language
+parallel fan-out.
+
+> Legacy installs from momentum ≤ v0.20.0 shipped recipes as Markdown
+> fragments under `.codex/commands/`. `momentum upgrade --agent codex`
+> regenerates skills under `.agents/skills/` and removes the old
+> lookup directory.
+
+## Codex Subagents
+
+Momentum ships four subagents discoverable at `.codex/agents/`:
+
+- `momentum-reviewer-security.toml` — OWASP/STRIDE-focused
+- `momentum-reviewer-qa.toml` — test coverage + edge cases + regression risk
+- `momentum-reviewer-architecture.toml` — rule compliance + pattern consistency
+- `swarm-supervisor.toml` — Phase 18 / v0.20.4. Per-repo supervisor spawned by `/swarm start`. Drives one repo's phase to completion under a pinned cwd (see MCP cwd shim section below).
+
+The three reviewers each declare `sandbox_mode = "read-only"` so they
+cannot modify the codebase. The `review-code` recipe dispatches all
+three in a single turn so Codex can fan them out in parallel (subject
+to `agents.max_threads`, default 6). The swarm supervisor does not
+declare a read-only sandbox — supervisors write code, that's the job.
+
+To add a project-specific reviewer, drop another `*.toml` into
+`.codex/agents/` with required keys `name`, `description`,
+`developer_instructions`. Optionally set `sandbox_mode = "read-only"` if
+the subagent shouldn't modify files.
+
+## Codex Hooks
+
+Codex hook wiring lives in `.codex/hooks.json`. Momentum installs reusable
+shell scripts to `scripts/` and references them from this file:
+
+| Event | Matcher | Script | Purpose |
+|---|---|---|---|
+| `PreToolUse` | `apply_patch\|Bash` | `scripts/brainstorm-gate.sh` | Blocks writes to `specs/` while a `/brainstorm-*` session is active (sentinel `.momentum/brainstorm-active`). Exits 2 to block. |
+| `PostToolUse` | `apply_patch\|Bash` | `scripts/check-history-reminder.sh` | Prompts for `history.md` append when meaningful edits land during phase work — resolved to the phase bound to the current branch (fallback: `status.md`) (Rule 8). |
+| `SessionStart` | (none) | `scripts/sessionstart-handoff.sh` | Auto-greets with any pending handoff banner + ecosystem context. |
+
+> Matcher uses `Bash` (not `shell`) because that's the canonical
+> `tool_name` Codex emits for shell tool calls — see the [Codex hooks
+> reference](https://developers.openai.com/codex/hooks).
+
+### Trust review
+
+Hooks are **enabled by default** in current Codex CLI (`hooks` is `stable`
+in `codex features list`). The first time momentum's hooks run in a fresh
+project, Codex prompts you to review and trust them via `/hooks`. Trust is
+recorded per-hash, so any change to the hook command requires re-approval.
+
+If hooks don't appear to fire:
+
+1. Run `/hooks` inside Codex and confirm `brainstorm-gate.sh`,
+   `check-history-reminder.sh`, and `sessionstart-handoff.sh` are listed
+   and marked trusted.
+2. Run `codex doctor` and confirm `hooks` shows as `stable: true`.
+3. Only as a last resort, force-enable in `~/.codex/config.toml`:
+
+   ```toml
+   [features]
+   hooks = true
+   ```
+
+The `brainstorm-gate.sh` script resolves the project root from
+`CLAUDE_PROJECT_DIR` → `MOMENTUM_PROJECT_DIR` → `pwd`, so Codex's default
+cwd-as-session-root behavior works without env-var configuration.
+
+## Codex Skills
+
+All momentum recipes ship as Codex skills under `.agents/skills/<name>/SKILL.md`
+(see the "Momentum Recipes — Codex Skills" section above for the full
+shipped set). Each `SKILL.md` declares `name` + `description` frontmatter
+per the [Codex skills format](https://developers.openai.com/codex/skills).
+
+Add additional project-specific skills under
+`.agents/skills/<name>/SKILL.md` following the same convention. Invoke
+via the `/skills` picker or `$<skill-name>` mention.
+
+## Swarm — Lookup Pattern
+
+Momentum's swarm primitive — sustained parallel multi-project feature
+delivery — ships on Codex as of Phase 18 / v0.20.4. The swarm recipe
+lives as a Codex skill at `.agents/skills/swarm/SKILL.md`; Codex
+auto-discovers and routes `/swarm <sub>` to it.
+
+The CLI floor is `momentum swarm <sub> [args]`. The slash command and
+the CLI produce the same on-disk artifacts — pick whichever fits the
+moment.
+
+| Subcommand | What it does |
+|---|---|
+| `start` | Plan + spawn Wave 1. Presents wave plan for approval before any spawn. |
+| `status` | Render the materialized board cache. Read-only. |
+| `tell` | Push a one-shot context note to one supervisor (`swarm-context.md`). |
+| `broadcast` | Push context to every supervisor in the swarm. |
+| `verify` | Contract verifier + manifest+brief drift check. |
+| `complete` | Synthesize the cross-repo changeset and finalize the swarm. |
+| `resume` | Re-attach this session to a swarm; renews owned leases. |
+| `cancel` | Graceful halt; preserves all artifacts for forensics. |
+| `budget` | Adjust a per-repo token budget. |
+| `claim` | Multi-session ownership primitive (Phase 17.5). |
+| `release` | Release ownership; idempotent. |
+| `focus` | Issue a single-use focus token to hand a repo to a side session. |
+| `join` | Register a second session as co-conductor; optionally consume a token. |
+| `absorb` | Converge two swarms back into one (forensic-preserving). |
+| `inbox` | Supervisor → conductor questions (`list` / `write` / `resolve`). |
+| `preview-merge` | Dry-run `git merge --no-commit` per supervisor branch. |
+
+**Supervisor declaration**: `.codex/agents/swarm-supervisor.toml`. Each
+supervisor reads `core/swarm/supervise.md` end-to-end on boot. The
+conductor (this user session) dispatches spawns through
+`adapters/codex/adapter.js::spawn(directive)` — which shells
+`codex --cwd <repoPath>` with the supervisor TOML.
+
+If `codex` CLI isn't on PATH, `momentum swarm start --spawn` degrades
+to dry-run: it prints the spawn directives so the user can launch
+sessions manually.
+
+## MCP cwd shim — Codex configuration
+
+> Phase 18 / v0.20.4. Required for the swarm primitive to honor the
+> per-repo cwd pin every supervisor needs.
+
+Each supervisor must run with its `repoPath` as its working directory —
+that's the hard invariant the supervise.md recipe is written against
+(every "stay in repoPath, never cd out" guard in `swarm-supervisor.toml`).
+
+Codex's CLI accepts `--cwd <path>` for each `codex` invocation, so the
+conductor's spawn call honors cwd at process boundary. Inside a
+supervisor session, momentum relies on Codex's MCP filesystem server to
+keep file ops scoped to that cwd — which means you (the user) configure
+the MCP filesystem server's `--root` to follow `$PWD`.
+
+In `~/.codex/config.toml` add:
+
+```toml
+[mcp_servers.filesystem]
+command = "npx"
+args    = ["-y", "@modelcontextprotocol/server-filesystem", "${PWD}"]
+```
+
+(See [Codex MCP servers](https://developers.openai.com/codex/mcp) for
+the canonical form. `${PWD}` is interpolated by Codex at server-spawn
+time, so each supervisor sees its own pinned `repoPath` as the
+filesystem server root.)
+
+**Verifying the shim**: inside a supervisor session, run:
+
+```bash
+pwd
+ls -la
+```
+
+You should see `repoPath` and the repo's top-level contents, not the
+ecosystem root. If you see the ecosystem root, the shim isn't applied —
+exit and reconfigure before launching supervisors.
+
+**If the doc-only shim doesn't hold on your Codex version**: file a
+bug against momentum and fall back to running each supervisor in a
+separate terminal with `cd <repoPath> && codex …` — a manual cwd pin.
+This is the documented escalation point referenced in Phase 18 G1
+plan.md; if the MCP shim is widely broken, momentum will ship a
+minimal `core/swarm/mcp-cwd-server.js` in a follow-up.

package/adapters/codex/instructions/vars.json

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

package/adapters/codex/skills/momentum-orient/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: momentum-orient
+description: Read specs/status.md before starting any work in a momentum-managed project. Activates at the start of every new task to ensure the agent has current phase context. Codifies Rule 1 (Orient First).
+---
+
+# momentum-orient
+
+When this skill activates (at session start or when the user asks you to
+work on something new), read these files in order before any other action:
+
+1. `specs/status.md` — current phase, blockers, P0 items, next actions
+2. `specs/backlog/backlog.md` — P0/P1 items that may block the current task
+3. `specs/phases/<active-phase>/tasks.md` — what's done / in flight / blocked
+4. `AGENTS.md` — project rules and constraints (the complete rulebook)
+
+Then proceed with the user's request, framing any output in terms of:
+- which phase is active
+- whether the requested work belongs in the active phase or is a side track
+- any existing tasks or history entries that already cover the request
+
+This skill is shipped by the momentum toolkit. It codifies Rule 1 (Orient
+First) from the project rules. See `AGENTS.md` for the full set of rules.
+
+## When NOT to apply this skill
+
+- If the user's message is purely conversational ("what is X?") and doesn't
+  require touching the codebase, you don't need to orient.
+- If you've already oriented this session and nothing on disk has changed
+  since, don't re-orient.

package/adapters/opencode/adapter.js

@@ -0,0 +1,224 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// opencode adapter for momentum.
+//
+// opencode (https://opencode.ai) is a terminal-first AI coding agent with
+// native project-level surfaces for every momentum concept: markdown
+// commands (.opencode/commands/), JS plugins with blocking pre-tool hooks
+// (.opencode/plugins/), markdown agents with per-agent permissions
+// (.opencode/agents/), and skills (.opencode/skills/<name>/SKILL.md).
+// AGENTS.md is its primary instruction surface. Every surface auto-loads
+// from its directory — momentum ships NO opencode.json and never touches
+// user-owned config.
+//
+// Recipes install via the standard overlay into .opencode/commands/ where
+// each file IS a native slash command (filename → /<name>). runInstall then
+// prepends a `description` frontmatter block (extracted from the recipe's
+// first line, same heuristic as the Codex skills transform) so the TUI
+// command picker shows what each recipe does.
+
+module.exports = {
+  displayName: 'opencode',
+
+  destinations: {
+    commands: ['.opencode', 'commands'],
+    'agent-rules': ['.agent', 'rules'],
+    scripts: ['scripts'],
+    engines: ['.agent', 'engines'],
+    // workflows declared but unused on opencode (no native workflow surface;
+    // recipes are commands)
+    workflows: ['.opencode', 'workflows'],
+    skills: ['.opencode', 'skills'],
+    agents: ['.opencode', 'agents'],
+  },
+
+  primaryInstruction: {
+    source: ['instructions', 'AGENTS.md'],
+    destination: ['AGENTS.md'],
+    label: 'AGENTS.md',
+    markerAware: true,
+  },
+
+  configFiles: [
+    {
+      source: ['plugins', 'momentum.js'],
+      destination: ['.opencode', 'plugins', 'momentum.js'],
+      label: '.opencode/plugins/momentum.js',
+    },
+  ],
+
+  capabilities: {
+    hooks: true, // live-validated: gate blocked a real specs/ edit; reminder stamp observed (G5 checks 2-3)
+    slashCommands: true, // live-validated: /validate executed the recipe in run-mode (G5 check 1)
+    subagents: true, // live-validated: all 4 agents discovered; supervisor selected via --agent (G5 checks 5-6)
+    parallelSubagents: true, // live-validated: two task-tool subagents with overlapping start/end timestamps (G5)
+    sessionStartHook: true, // live-validated post-phase: banner fired in a served session via the event bus (run-mode excluded — see roadmap)
+    skills: true, // live-validated: skill tool loaded momentum-orient; multi-adapter coexistence clean (G5 check 7)
+    browser: false,
+    computerUse: false,
+    planningMode: true, // built-in read-only Plan agent (Tab-cycle primary)
+  },
+
+  roadmap: {
+    sessionStartHook:
+      'Flipped true on live serve-session evidence (fix/opencode-sessionstart-banner): session events ' +
+      'reach plugins only via the generic `event` bus (a named "session.created" hook key never fires ' +
+      'on 1.17.x), and the banner now rides that bus. Deliberately EXCLUDED from `opencode run` ' +
+      'non-interactive mode: the event handler\'s mere presence hangs run-mode (reproduced on 1.17.13, ' +
+      'upstream issue candidate), and a session-start banner is meaningless there. Evidence: ' +
+      'specs/adhoc/fix-opencode-sessionstart-banner/record.md.',
+  },
+
+  runInstall(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged, dryRun } = helpers;
+
+    console.log('→ Configuring momentum plugin for opencode...');
+    const pluginDest = path.join(targetDir, '.opencode', 'plugins', 'momentum.js');
+    if (recordManaged) recordManaged(pluginDest); // managed regardless of write
+    if (!fileExists(pluginDest)) {
+      copyFile(path.join(adapterDir, 'plugins', 'momentum.js'), pluginDest);
+    } else {
+      console.log('  ⚠️  .opencode/plugins/momentum.js already exists.');
+      console.log(`     Merge manually from: ${path.join(adapterDir, 'plugins', 'momentum.js')}`);
+    }
+
+    console.log('→ Adding command frontmatter for the opencode TUI picker...');
+    if (dryRun) console.log('  ✋ would add description frontmatter to .opencode/commands/*.md');
+    else ensureCommandFrontmatter(targetDir);
+  },
+
+  runUpgrade(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged, dryRun } = helpers;
+
+    console.log('→ Upgrading momentum plugin for opencode...');
+    const src = path.join(adapterDir, 'plugins', 'momentum.js');
+    const dest = path.join(targetDir, '.opencode', 'plugins', 'momentum.js');
+    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: .opencode/plugins/momentum.js');
+        } else {
+          fs.copyFileSync(dest, dest + '.bak');
+          copyFile(src, dest);
+          console.log('  ↑ upgraded: .opencode/plugins/momentum.js (original saved as .bak)');
+        }
+      }
+    } else {
+      copyFile(src, dest);
+      console.log(`  ${dryRun ? '✋ would add:   ' : '+ added:   '} .opencode/plugins/momentum.js`);
+    }
+
+    console.log('→ Refreshing command frontmatter...');
+    if (dryRun) console.log('  ✋ would refresh description frontmatter on .opencode/commands/*.md');
+    else {
+      ensureCommandFrontmatter(targetDir);
+      cleanupConvergedBackups(path.join(targetDir, '.opencode', 'commands'));
+    }
+  },
+
+  // adapter.spawn(directive) — Phase 18 contract. Shells `opencode run` in
+  // non-interactive mode with the supervisor agent; `--dir` pins the
+  // supervisor's working directory to its repo (no MCP cwd shim needed,
+  // unlike Codex). See `bin/momentum.js` for the directive contract.
+  spawn(directive) {
+    if (!directive || directive.platform !== 'opencode') {
+      return {
+        repoId: directive && directive.repoId,
+        status: -1,
+        detail: `non-opencode platform: ${directive && directive.platform}`,
+      };
+    }
+    const opencodeBin = process.env.OPENCODE_BIN || 'opencode';
+    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 args = ['run', '--dir', directive.repoPath, '--agent', 'swarm-supervisor', prompt];
+    const r = spawnSync(opencodeBin, args, {
+      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),
+    };
+  },
+};
+
+// ─── Command frontmatter transform ───────────────────────────────────────────
+//
+// opencode registers every .opencode/commands/*.md file as a /<name> command
+// as-is; the optional YAML frontmatter `description` is what the TUI's
+// command picker displays. Recipes follow the house style where line 1 is a
+// one-sentence "what it does", so reuse it (same heuristic as the Codex
+// skills transform). Idempotent: files that already start with frontmatter
+// are left untouched.
+function ensureCommandFrontmatter(targetDir) {
+  const commandsDir = path.join(targetDir, '.opencode', 'commands');
+  if (!fs.existsSync(commandsDir)) {
+    console.log('  (no .opencode/commands/ to annotate — skipping)');
+    return;
+  }
+  let count = 0;
+  for (const file of fs.readdirSync(commandsDir)) {
+    if (!file.endsWith('.md')) continue;
+    const filePath = path.join(commandsDir, file);
+    const body = fs.readFileSync(filePath, 'utf8');
+    if (body.startsWith('---\n')) continue; // already has frontmatter
+    const description = extractRecipeDescription(body, file.replace(/\.md$/, ''));
+    const frontmatter = `---\ndescription: ${yamlQuote(description)}\n---\n\n`;
+    fs.writeFileSync(filePath, frontmatter + body);
+    count++;
+  }
+  console.log(`  + description frontmatter added to ${count} command(s)`);
+}
+
+// First non-heading, non-blank, non-blockquote line of the recipe.
+function extractRecipeDescription(body, name) {
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith('#') || trimmed.startsWith('>')) continue;
+    // Truncate to a single-sentence-ish length for the picker.
+    return trimmed.length > 200 ? `${trimmed.slice(0, 197)}...` : trimmed;
+  }
+  return `momentum ${name} recipe`;
+}
+
+function yamlQuote(s) {
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+// The generic overlay upgrade sees the install-time frontmatter as drift from
+// the pristine template, so it backs up each command before replacing it —
+// then the transform above re-adds identical frontmatter, converging the file
+// back to its pre-upgrade bytes. A `.bak` byte-identical to its base is that
+// cycle's artifact, not a user modification — remove it. Real user edits
+// leave a differing `.bak`, which is kept.
+function cleanupConvergedBackups(dir) {
+  if (!fs.existsSync(dir)) return;
+  let removed = 0;
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.bak')) continue;
+    const bakPath = path.join(dir, f);
+    const basePath = path.join(dir, f.slice(0, -'.bak'.length));
+    if (!fs.existsSync(basePath)) continue;
+    if (fs.readFileSync(bakPath, 'utf8') === fs.readFileSync(basePath, 'utf8')) {
+      fs.unlinkSync(bakPath);
+      removed++;
+    }
+  }
+  if (removed) console.log(`  - ${removed} converged .bak backup(s) removed (frontmatter cycle)`);
+}

package/adapters/opencode/agents/momentum-reviewer-architecture.md

@@ -0,0 +1,54 @@
+---
+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.
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git diff*": allow
+    "git log*": allow
+    "git show*": allow
+    "git status*": allow
+---
+
+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.

package/adapters/opencode/agents/momentum-reviewer-qa.md

@@ -0,0 +1,48 @@
+---
+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.
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git diff*": allow
+    "git log*": allow
+    "git show*": allow
+    "git status*": allow
+---
+
+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.

package/adapters/opencode/agents/momentum-reviewer-security.md

@@ -0,0 +1,48 @@
+---
+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.
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git diff*": allow
+    "git log*": allow
+    "git show*": allow
+    "git status*": allow
+---
+
+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.

package/adapters/opencode/agents/swarm-supervisor.md

@@ -0,0 +1,51 @@
+---
+description: Drive a single repo through its phase as part of a swarm. Read the recipe at the path supplied in the spawn directive (typically core/swarm/supervise.md), read the brief at specs/phases/<phase-slug>/overview.md, and execute the boot sequence. State lives in files; the conductor reads board.json between turns. Dispatched by the conductor; not invoked directly by the user.
+mode: all
+---
+
+You are a swarm supervisor for one repo. The conductor (the user's
+primary session) spawned you with a spawn directive containing:
+
+- repoPath:    your pinned cwd; never cd out of it
+- phaseSlug:   the phase you are driving (specs/phases/<slug>/)
+- swarmId:     the swarm you belong to (manifest at <eco>/swarms/<id>/)
+- wave:        your wave index (1-based)
+- sessionId:   the conductor's session id
+- recipePath:  absolute path to supervise.md — your operating recipe
+
+Boot sequence:
+
+1. Read the recipe at `recipePath` end-to-end. Treat it as your
+   operating manual for this session.
+2. Read your brief at `specs/phases/<phase-slug>/overview.md`. The
+   brief's frontmatter (swarm, wave, initiative, claimed_by_session)
+   was populated by the conductor.
+3. Read `specs/status.md` per Rule 1 (orient first).
+4. Begin the normal momentum lifecycle inside this repo: /start-phase
+   → implement → /sync-docs → /complete-phase. Each phase command is
+   itself an opencode command — invoke it by name.
+
+Operating constraints:
+
+- Stay in `repoPath` (your session was spawned with `opencode run --dir
+  <repoPath>`, so your working directory is already pinned). Never `cd`
+  to a sibling repo. Cross-repo concerns go through the inbox primitive
+  at `<eco>/swarms/<swarm-id>/inbox/`.
+- State lives in files. Append to `history.md` per Rule 8; the
+  conductor reads `board.json` between turns to render progress to the
+  user.
+- The conductor may push context via `swarm-context.md` at
+  `specs/phases/<phase-slug>/swarm-context.md`. Read it at the top of
+  every turn.
+- If you have a question only the conductor can answer, write it to
+  the swarm inbox via:
+
+    momentum swarm inbox write <swarm-id> --repo <your-repo-id> \
+      --slug <short-slug> --question "<text>"
+
+  Then wait for resolution before continuing — do NOT guess.
+- When your phase is complete, run /complete-phase per the standard
+  recipe; the supervisor finishes after the phase is verified and
+  pushed.
+
+You inherit every always-on rule from AGENTS.md (the complete rulebook).