@limina-labs/momentum 0.30.2

package/adapters/antigravity/workflows/review-code.md

@@ -0,0 +1,84 @@
+---
+description: Multi-perspective code review of pending changes on the current branch. Spawns three momentum reviewer skills in parallel — security, QA, architecture — and consolidates findings into a single Critical/Important/Minor report. Use before completing a phase or opening a PR.
+---
+
+# review-code
+
+### 1. Determine review scope
+
+Default: the diff between the current branch and `main`. Run:
+
+```bash
+git diff main...HEAD --stat
+git diff main...HEAD
+```
+
+User arguments override the default:
+- `staged` → `git diff --cached`
+- `working` → `git diff` (unstaged)
+- `<commit-sha>` → `git diff <commit-sha>...HEAD`
+- `<file-path>` → restrict to that path within default scope
+
+If no diff exists, report "no changes to review" and stop.
+
+### 2. Read project rules
+
+Before dispatching reviewers, read:
+- `AGENTS.md` (primary instructions)
+- `specs/status.md` (current phase context)
+
+This ensures each reviewer scores the diff against THIS project's rules, not generic best practices alone.
+
+### 3. Dispatch three reviewer skills in parallel
+
+Use Antigravity's native parallel subagent fan-out to spawn three reviewer subagents IN A SINGLE TURN, each loaded with one of the momentum reviewer skills installed at `.agents/skills/`:
+
+- `momentum-reviewer-security` (OWASP/STRIDE lens)
+- `momentum-reviewer-qa` (test coverage / edge cases / regressions)
+- `momentum-reviewer-architecture` (rule compliance / pattern consistency)
+
+Each subagent gets the diff + relevant project rules excerpt as input.
+
+### 4. Consolidate findings
+
+When all three return, merge findings into one report ordered:
+
+```
+## Code Review
+
+### Critical (N)
+- [security] <finding> (file:line)
+- [arch] <finding> (file:line)
+
+### Important (N)
+- [qa] <finding> (file:line)
+
+### Minor (N)
+- [arch] <finding> (file:line)
+```
+
+Tag each finding with reviewer (`[security]`, `[qa]`, `[arch]`). De-duplicate findings raised by multiple reviewers; tag with all sources (`[security][arch]`). Surface conflicts (Critical vs Minor from different reviewers) and note the disagreement.
+
+### 5. Surface to user via the task.md artifact
+
+Update the active `task.md` artifact with each Critical and Important finding as a task entry. Then ask:
+
+> "Which findings should I act on now? Options:
+>   1. All Critical
+>   2. All Critical + Important
+>   3. Specific items (list IDs)
+>   4. None — log all to backlog only
+>   5. Cancel"
+
+### 6. Act + verify
+
+For findings the user acts on: implement each as a separate commit. For deferred findings: file each via `/track` at appropriate priority (Critical → P0/P1, Important → P1/P2, Minor → P2/P3).
+
+After fixes, per Rule 12 (Verify Before Claim): run the relevant verification command (test, lint, typecheck) BEFORE marking done. Append the verification evidence to the active `walkthrough.md` artifact.
+
+## Constraints
+
+- Reviewer skills are READ-ONLY — they cannot modify the codebase.
+- Dispatch all three reviewers in ONE turn using parallel fan-out — do not sequence them.
+- The review NEVER auto-fixes findings. The user always decides what to act on.
+- If a reviewer's output is malformed (missing severity headers), re-dispatch THAT single reviewer with a stricter format reminder. Do not silently reformat.

package/adapters/antigravity/workflows/scout.md

@@ -0,0 +1,42 @@
+---
+description: Read-only context fetch from one ecosystem member repo. Returns a structured summary, writes a scout artifact to .momentum/runs/. Use when you need to understand another repo's state before planning cross-repo work.
+---
+
+# scout
+
+### 1. Resolve target
+
+Identify the ecosystem member to scout from the user's input (member id or path). Look up `ecosystem.json` to confirm the member exists. If the user did not specify a target, ask for one and stop until they answer.
+
+### 2. Read the target's status
+
+From the target repo, read these in order (skip silently if any is missing):
+
+1. `specs/status.md`
+2. `specs/backlog/backlog.md` (just the open P0/P1 lines)
+3. `specs/phases/<active-phase>/tasks.md` (just the in-flight rows)
+4. `AGENTS.md` (only if the user asked about rules)
+
+### 3. Synthesize the scout result
+
+Produce a structured summary with these sections in this order:
+
+- **Repo**: <member id>
+- **Active phase**: <phase name> + status
+- **Blockers / P0s**: bullet list or "(none)"
+- **Recent decisions**: top 3 history entries by recency
+- **Relevance to current task**: 1–2 sentences explaining how the scouted state affects what we're trying to do
+
+### 4. Write the scout artifact
+
+Append a scout entry to `.momentum/runs/scout-<NNN>.md` with the same structured summary so the result is durable across sessions.
+
+### 5. Return to user
+
+Present the synthesis as the response. Do not propose follow-up work — scout is read-only. If follow-up is needed, the user invokes `/handoff` or `/dispatch` next.
+
+## Constraints
+
+- READ-ONLY. Do not modify any files in the target repo.
+- Do not invoke other slash commands as a side effect.
+- Stay under ~500 tokens in the response unless the user asks for a deeper read.

package/adapters/antigravity/workflows/swarm.md

@@ -0,0 +1,203 @@
+---
+description: Sustained parallel multi-project feature delivery. Spawns one supervisor agent per impacted repo via Antigravity's Agent Manager, each pinned to that repo's cwd. The user's session becomes the conductor. Use for cross-repo features with dependency ordering.
+---
+
+# swarm
+
+> Phase 18 / v0.20.4 — Antigravity parity of the Phase 17 + 17.5 swarm
+> surface that originally shipped Claude Code only. All 13 subcommands
+> work through the Antigravity `adapter.spawn(directive)` dispatch
+> (`adapters/antigravity/adapter.js`), which shells `agy` via the Agent
+> Manager primitive.
+
+A **swarm** is a declared cross-repo work unit driven from ONE user session. Your session becomes the **conductor**. The conductor spawns one **supervisor** Antigravity session per impacted repo via the Agent Manager, each pinned to that repo's working directory. Each supervisor BECOMES the `swarm-supervisor` skill (loaded from `.agents/skills/swarm-supervisor/SKILL.md`) and runs momentum's normal `/start-phase` → implement → `/sync-docs` → `/complete-phase` loop INSIDE its repo.
+
+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`.
+
+## Antigravity specifics
+
+- **Supervisor skill**: `.agents/skills/swarm-supervisor/SKILL.md`. Each supervisor BECOMES this skill on spawn.
+- **Spawn dispatch**: the CLI floor (`momentum swarm start --spawn …`) dispatches each spawn directive through `adapters/antigravity/adapter.js::spawn()`. The adapter shells `agy` with the supervisor skill as the persona and the directive's `repoPath` as the cwd, exploiting Antigravity's native `parallelSubagents: true` capability.
+- **Hook integration**: `.agents/hooks.json` PreToolUse matchers (`run_command|view_file|.*write.*|apply_patch`) apply uniformly inside each supervisor — the brainstorm gate keeps supervisors from drifting into spec edits during phase implementation.
+
+## 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.
+
+### 1. `/swarm start <slug> --initiative <slug> --repos r1,r2,... --phase <phase-slug> [--mode checkpoint|autopilot]`
+
+Plan + spawn Wave 1.
+
+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 and WAIT for approval. After approval, run with `--spawn`:
+
+```bash
+momentum swarm start <slug> --initiative <slug> --repos ... --phase <phase-slug> --mode <mode> --spawn
+```
+
+`bin/swarm.js` dispatches each directive through `adapters/antigravity/adapter.js::spawn()`, which shells `agy` with the supervisor skill loaded and the repo path as cwd. If `agy` is not on PATH, the CLI surfaces the spawn directives and exits non-zero — degrade by reporting the directives to the user (they can launch sessions manually) and continue with conductor polling on the existing manifest.
+
+### 2. `/swarm status <swarm-id>`
+
+Render the materialized board cache. Read-only — no manifest mutation. Conductor reads ONLY `board.json` (~3KB).
+
+```bash
+momentum swarm status <swarm-id>
+```
+
+Default output is a rendered ANSI table. Pass `--json` for machine-readable.
+
+### 3. `/swarm tell <swarm-id> <repo> "<text>"`
+
+Push a one-shot context note to a specific supervisor. The text lands at `specs/phases/<phase-slug>/swarm-context.md` inside the target repo.
+
+```bash
+momentum swarm tell <swarm-id> <repo> "<text>"
+```
+
+### 4. `/swarm broadcast <swarm-id> "<text>"`
+
+Push context to every supervisor in the swarm.
+
+```bash
+momentum swarm broadcast <swarm-id> "<text>"
+```
+
+Use sparingly — broadcast costs each supervisor a context-fetch turn.
+
+### 5. `/swarm verify <swarm-id>`
+
+Run the contract verifier + manifest+brief drift check. Read-only. Exits non-zero if any drift surfaces.
+
+```bash
+momentum swarm verify <swarm-id>
+```
+
+### 6. `/swarm complete <swarm-id>`
+
+Synthesize the cross-repo changeset and finalize the swarm.
+
+```bash
+momentum swarm complete <swarm-id>
+```
+
+### 7. `/swarm resume <swarm-id> [--session <id>]`
+
+Re-attach the current session to an existing swarm; renews leases this session owns.
+
+```bash
+momentum swarm resume <swarm-id> [--session <id>]
+```
+
+### 8. `/swarm cancel <swarm-id> [--reason "<text>"]`
+
+Graceful halt. Halts every supervisor, marks the swarm `cancelled` in the manifest, preserves all artifacts for forensics. **Confirm with the user before running.**
+
+```bash
+momentum swarm cancel <swarm-id> --reason "<text>"
+```
+
+### 9. `/swarm budget <swarm-id> <repo> +N | -N`
+
+Adjust the per-repo token budget.
+
+```bash
+momentum swarm budget <swarm-id> <repo> +100000
+```
+
+### 10. `/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.
+
+```bash
+momentum swarm claim <swarm-id> <repo> [--session <id>] [--lease-hours 24]
+```
+
+### 11. `/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>`. Idempotent.
+
+```bash
+momentum swarm release <swarm-id> <repo> [--session <id>]
+```
+
+### 12. `/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 and hand control to a second Antigravity session.
+
+```bash
+momentum swarm focus <swarm-id> <repo> [--session <id>] [--expires-min 60]
+```
+
+### 13. `/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 Antigravity session to `<swarm-id>` as a co-conductor.
+
+```bash
+momentum swarm join <swarm-id> [--token <token>] [--claim <repo>] [--session <id>]
+```
+
+### 14. `/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>`.
+
+```bash
+momentum swarm absorb <target-swarm-id> <source-swarm-id> [--yes] [--session <id>]
+```
+
+### 15. `/swarm inbox list|write|resolve <swarm-id> …`
+
+Supervisor → conductor questions.
+
+```bash
+momentum swarm inbox list <swarm-id>
+momentum swarm inbox write <swarm-id> --repo <r> --slug <s> --question "<text>"
+momentum swarm inbox resolve <swarm-id> <id> --answer "<text>"
+```
+
+### 16. `/swarm preview-merge <swarm-id>`
+
+Dry-run `git merge --no-commit --no-ff` for every supervisor branch against `main`. Always aborts.
+
+```bash
+momentum swarm preview-merge <swarm-id>
+```
+
+## 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.
+- **Native artifacts**: keep `task.md` synced with `tasks.md` and `implementation_plan.md` with `plan.md` — same pattern as standalone phase work.
+
+## 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.
+- `agy` CLI not on PATH → degrade to dry-run + manual spawn instructions.

package/adapters/claude-code/adapter.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// Claude Code adapter for momentum.
+//
+// Two responsibilities:
+//
+//   1. Declare destinations — where overlay subdirs (commands, agent-rules,
+//      scripts) land in the target project. The CLI uses these for both core
+//      copies AND any adapter overlay files placed at:
+//        adapters/claude-code/commands/      → .claude/commands/
+//        adapters/claude-code/agent-rules/   → .agent/rules/
+//        adapters/claude-code/scripts/       → scripts/
+//
+//   2. runInstall / runUpgrade — anything that isn't a plain file copy
+//      (currently: wiring `.claude/settings.json` for hooks).
+//
+// Overlay contract (Phase 6 / FEAT-012): a given filename lives in EITHER
+// `core/<sub>/` OR `adapters/claude-code/<sub>/`, never both. The CLI errors
+// before any writes if a duplicate is detected.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+module.exports = {
+  displayName: 'Claude Code',
+
+  destinations: {
+    commands: ['.claude', 'commands'],
+    'agent-rules': ['.agent', 'rules'],
+    scripts: ['scripts'],
+    engines: ['.agent', 'engines'],
+    // Phase 16 Rework: uniform contract — declared but unused on Claude
+    // Code (no overlay content shipped). Claude Code has no per-project
+    // workflows/skills/subagent file-discovery surface today; the
+    // destinations are reserved for cross-adapter contract consistency.
+    workflows: ['.claude', 'workflows'],
+    skills: ['.claude', 'skills'],
+    agents: ['.claude', 'agents'],
+  },
+
+  primaryInstruction: {
+    source: ['core', 'specs-templates', 'CLAUDE.md'],
+    sourceBase: 'package',
+    destination: ['CLAUDE.md'],
+    label: 'CLAUDE.md',
+    markerAware: true,
+  },
+
+  configFiles: [
+    {
+      source: ['settings.json'],
+      destination: ['.claude', 'settings.json'],
+      label: '.claude/settings.json',
+    },
+  ],
+
+  capabilities: {
+    hooks: true,
+    slashCommands: true,
+    subagents: true,
+    parallelSubagents: true,
+    sessionStartHook: true,
+    skills: false,
+    browser: false,
+    computerUse: false,
+  },
+
+  roadmap: {},
+
+  runInstall(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged } = helpers;
+
+    // .claude/settings.json
+    console.log('→ Configuring Claude Code hooks...');
+    const settingsDest = path.join(targetDir, '.claude', 'settings.json');
+    // Record as adapter-managed regardless of whether we write it, so the
+    // lock file is complete and orphan cleanup never drops it (Phase 20).
+    if (recordManaged) recordManaged(settingsDest);
+    if (!fileExists(settingsDest)) {
+      copyFile(path.join(adapterDir, 'settings.json'), settingsDest);
+    } else {
+      console.log('  ⚠️  .claude/settings.json already exists.');
+      console.log(`     Merge hooks manually from: ${path.join(adapterDir, 'settings.json')}`);
+    }
+  },
+
+  runUpgrade(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged, dryRun } = helpers;
+
+    // .claude/settings.json
+    console.log('→ Upgrading Claude Code hooks...');
+    const src = path.join(adapterDir, 'settings.json');
+    const dest = path.join(targetDir, '.claude', 'settings.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: .claude/settings.json');
+        } else {
+          fs.copyFileSync(dest, dest + '.bak');
+          copyFile(src, dest);
+          console.log(`  ↑ upgraded: .claude/settings.json (original saved as .bak)`);
+        }
+      }
+      // identical — silent skip
+    } else {
+      copyFile(src, dest);
+      console.log(`  ${dryRun ? '✋ would add:    ' : '+ added:   '} .claude/settings.json`);
+    }
+  },
+
+  // Phase 18 — adapter.spawn(directive) contract.
+  // Launch ONE Claude Code background session for this directive via
+  // `claude --bg --cwd <repoPath>`. Pipes the supervisor recipe + brief
+  // pointer over stdin. Returns the canonical per-repo result shape.
+  // See `bin/momentum.js` for the directive contract.
+  spawn(directive) {
+    if (!directive || directive.platform !== 'claude-code') {
+      return {
+        repoId: directive && directive.repoId,
+        status: -1,
+        detail: `non-claude-code platform: ${directive && directive.platform}`,
+      };
+    }
+    const claudeBin = process.env.CLAUDE_CODE_BIN || 'claude';
+    const args = ['--bg', '--cwd', directive.repoPath];
+    const prompt = [
+      `You are a swarm supervisor. Recipe: ${directive.recipePath}`,
+      `Read the recipe and the brief at specs/phases/${directive.phaseSlug}/overview.md.`,
+      `Begin the boot sequence.`,
+    ].join('\n');
+    const r = spawnSync(claudeBin, 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),
+    };
+  },
+};

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

@@ -0,0 +1,82 @@
+Pick up a pending handoff in this repo. Reads `.momentum/inbox/handoff-NNN.md`, parses the structured context block, marks the inbox file as read, and emits a `[NOTE]` in the receiving repo's active phase history.
+
+> **Three doors, one library.** This is the slash-command door for Claude Code. The CLI door is `momentum continue [--handoff <id>]`. The auto-greet door fires via the SessionStart hook when you open a fresh session with pending handoffs. All three call `core/orchestration/continue.js`.
+
+## When to use
+
+- The SessionStart auto-greet hook printed a "1 pending handoff" banner and you typed `y`.
+- You know there's a pending handoff from another repo and want to start with that context.
+- You want to list pending handoffs and pick one explicitly.
+
+## Usage
+
+```
+/continue                     pick up the OLDEST pending handoff
+/continue <id>                pick up handoff-<id> specifically
+/continue list                list pending handoffs without picking
+```
+
+## Steps
+
+### Step 1 — List or pick
+
+If `list`, run:
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const pending = orchestration.continueHandoff.listPending('<this repo>');
+```
+
+Render: `▸ N pending handoff(s):` then `▸ <id> from <fromRepo>: <summary>`. Stop.
+
+Otherwise, pick:
+
+```js
+const block = await orchestration.continueHandoff.continueHandoff({
+  repo: '<this repo absolute path>',
+  handoffId: '<id-if-specified>', // omit for oldest
+  ecosystem: { rootPath: '<ecosystem root>', memberId: '<this repo member id>' },
+});
+```
+
+This parses the inbox file, moves it to `.momentum/inbox/read/`, and emits a `[NOTE]` in this repo's active phase history (handoff pickup IS a meaningful event worth tracking).
+
+### Step 2 — Act on the block
+
+Narrate it to the user:
+
+```
+▸ picking up handoff-NNN from <fromRepo>
+
+Summary: <summary>
+
+Decisions:
+  - <decision 1>
+  - <decision 2>
+
+Files touched (in originating session):
+  - <file 1>
+  - <file 2>
+
+Verification:
+  $ <command 1>
+
+Open questions:
+  ? <question 1>
+```
+
+Then proceed with the work the handoff describes — the user shouldn't have to re-explain anything.
+
+### Step 3 — Don't surprise the user
+
+If the handoff is large (>30 lines of decisions/files), summarise + offer "want me to read the full block? [y/n]" before diving in. Otherwise just proceed.
+
+## Tracking contract
+
+- **Auto every time:** inbox file moved to `read/` + `[NOTE]` in receiving repo's active phase history referencing the picked-up handoff.
+
+## Errors
+
+- No pending handoffs → "no pending handoffs in this repo" and stop. NOT an error.
+- Specified handoff id not found → error with list of pending ids.
+- Inbox file is malformed → error pointing at the file with a hint to inspect.