@limina-labs/momentum 0.30.2

package/adapters/opencode/instructions/surfaces.md

@@ -0,0 +1,119 @@
+## Momentum Recipes — opencode Commands
+
+Every momentum recipe ships as a native opencode command at
+`.opencode/commands/<name>.md` ([opencode commands
+docs](https://opencode.ai/docs/commands/)). opencode auto-discovers them
+at startup — type `/` in the TUI and the full recipe set appears; e.g.
+`/brainstorm-phase` runs the phase-planning recipe. Arguments flow via
+`$ARGUMENTS` (e.g. `/track BUG some description`).
+
+The shipped recipe set (one command per recipe):
+
+| 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) |
+| hotfix | Ship a bounded ad-hoc change (quick-task / spike) without a phase |
+| lanes | Work with lanes — concurrent workstreams in one repo (Rule 15) |
+| 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 the swarm-supervisor agent) |
+
+The recipes are platform-independent — they describe what to do, not how
+opencode specifically should do it. When a recipe mentions "use the Task
+tool" (Claude Code terminology), use opencode's task tool: invoke the
+relevant subagent (`@momentum-reviewer-qa` mention or automatic task
+dispatch).
+
+## Momentum Skills
+
+Momentum also ships skills at `.opencode/skills/<name>/SKILL.md`
+([opencode skills docs](https://opencode.ai/docs/skills/)). opencode
+discovers them natively and exposes them through the `skill` tool — the
+agent loads a skill on demand when its description matches the work.
+Skills complement commands: commands are user-invoked (`/name`), skills
+are agent-invoked (momentum-orient runs Rule 1 orientation without you
+asking).
+
+Add project-specific skills under `.opencode/skills/<name>/SKILL.md`
+with `name` + `description` frontmatter (name must match
+`^[a-z0-9]+(-[a-z0-9]+)*$`).
+
+## Momentum Plugin — enforcement hooks
+
+Momentum's enforcement layer ships as one plugin at
+`.opencode/plugins/momentum.js` ([opencode plugins
+docs](https://opencode.ai/docs/plugins/)), auto-loaded at startup:
+
+| Hook | Purpose |
+|---|---|
+| `tool.execute.before` | Brainstorm gate — blocks write-class tools targeting `specs/**` while `.momentum/brainstorm-active` exists (throws to block, mirroring the Claude Code PreToolUse gate). |
+| `tool.execute.after` | History reminder — prompts for a `history.md` append when meaningful edits land during phase work (Rule 8); bash tool calls additionally delegate to the installed scripts/check-history-reminder.sh, which also feeds the ecosystem session log (ENH-058). |
+| `event (session.created)` | Handoff banner — surfaces pending `.momentum/inbox/` handoffs at session start. **Run-mode caveat**: this handler is registered only in TUI/serve sessions. In `opencode run` (headless/non-interactive) the handler is skipped — its mere presence hangs `opencode run` on 1.17.x (upstream candidate, noted in ENH-058). Session banners are meaningless in headless mode anyway. |
+
+The plugin is self-contained (no npm dependencies) and reads the same
+`.momentum/` sentinels as the other adapters' hook scripts — the
+enforcement semantics are identical across platforms.
+
+## Momentum Subagents
+
+Momentum ships four agents at `.opencode/agents/` ([opencode agents
+docs](https://opencode.ai/docs/agents/)):
+
+- `momentum-reviewer-security.md` — OWASP/STRIDE-focused
+- `momentum-reviewer-qa.md` — test coverage + edge cases + regression risk
+- `momentum-reviewer-architecture.md` — rule compliance + pattern consistency
+- `swarm-supervisor.md` — per-repo supervisor spawned by `/swarm start`
+
+The three reviewers declare `mode: subagent` with `permission: edit: deny`
+— they cannot modify the codebase. The `review-code` recipe dispatches
+all three in one turn so opencode can fan them out via the task tool.
+The swarm supervisor is not read-only — supervisors write code, that's
+the job.
+
+To add a project-specific reviewer, drop another `<name>.md` into
+`.opencode/agents/` with `description` + `mode: subagent` frontmatter.
+
+## Swarm — Lookup Pattern
+
+Momentum's swarm primitive ships on opencode. The swarm recipe lives at
+`.opencode/commands/swarm.md` (`/swarm <sub>`); the CLI floor is
+`momentum swarm <sub> [args]` — both produce the same on-disk artifacts.
+
+**Supervisor spawn**: the conductor dispatches spawns through
+`adapters/opencode/adapter.js::spawn(directive)`, which shells
+
+```bash
+opencode run --dir <repoPath> --agent swarm-supervisor "<boot directive>"
+```
+
+`--dir` pins each supervisor's working directory to its repo — no MCP
+cwd shim needed (unlike Codex). If `opencode` isn't on PATH,
+`momentum swarm start --spawn` degrades to dry-run and prints the spawn
+directives for manual launch.
+
+## Instruction precedence note
+
+opencode reads `AGENTS.md` (this file) as its primary project
+instruction, with `CLAUDE.md` as a compatibility fallback — when both
+exist (e.g. a project installed for multiple agents), `AGENTS.md` wins
+and nothing is read twice. opencode also discovers Claude-compatible
+skill paths (`.claude/skills/`, `.agents/skills/`); momentum's opencode
+surfaces live under `.opencode/` so multi-adapter installs stay
+side-by-side without collisions.

package/adapters/opencode/instructions/vars.json

@@ -0,0 +1 @@
+{ "TASK_TOOL": "the built-in **task** tool (subagent fan-out)", "TASK_TOOL_NAME": "The task tool" }

package/adapters/opencode/plugins/momentum.js

@@ -0,0 +1,219 @@
+// momentum enforcement plugin for opencode.
+//
+// Installed by momentum init/upgrade --agent opencode into
+// .opencode/plugins/momentum.js — auto-loaded by opencode at startup.
+//
+// One plugin, three hooks — the opencode-native equivalent of the shell
+// hooks the other adapters wire (core/scripts/brainstorm-gate.sh,
+// check-history-reminder.sh, sessionstart-handoff.sh). Reads the same
+// .momentum/ sentinels, so enforcement semantics are identical across
+// platforms:
+//
+//   tool.execute.before  — brainstorm gate: while .momentum/brainstorm-active
+//                          exists, write-class tools targeting specs/** throw
+//                          (throwing blocks the tool call).
+//   tool.execute.after   — history reminder: meaningful edits during phase
+//                          work prompt for a history.md append (Rule 8);
+//                          bash tool calls additionally delegate to the
+//                          installed scripts/check-history-reminder.sh,
+//                          which also feeds the ecosystem session log
+//                          (commit / pr events — ENH-058).
+//   event (session.created) — session banners: delegates to the installed
+//                          scripts/sessionstart-handoff.sh (ecosystem
+//                          context + handoff inbox, same output as every
+//                          other adapter); pure-JS handoff fallback when
+//                          the script is absent. TUI/serve sessions only;
+//                          see the run-mode note below.
+//
+// Node builtins only, no npm dependencies. The ecosystem behaviors reuse the
+// SAME installed shell scripts the other adapters wire (scripts/ self-guard
+// and no-op outside ecosystems), so semantics stay identical across
+// platforms. Fail-open by design: any unexpected error in reminder/banner
+// paths is swallowed; only the gate throws, and only on a confirmed
+// specs/-write during an active brainstorm.
+
+import fs from "node:fs"
+import path from "node:path"
+import { spawnSync } from "node:child_process"
+
+const WRITE_TOOLS = new Set(["write", "edit", "patch"])
+const REMINDER_THROTTLE_MS = 30 * 60 * 1000 // one nudge per 30 min
+const SCRIPT_TIMEOUT_MS = 3000
+
+// Run an installed momentum hook script (scripts/<name>) with the canonical
+// JSON hook payload on stdin. Returns trimmed combined output, or null when
+// the script is missing/failed — callers treat null as "nothing to show".
+function runInstalledScript(root, name, payload) {
+  try {
+    const script = path.join(root, "scripts", name)
+    if (!fs.existsSync(script)) return null
+    const r = spawnSync("bash", [script], {
+      cwd: root,
+      input: payload ? JSON.stringify(payload) : "",
+      encoding: "utf8",
+      timeout: SCRIPT_TIMEOUT_MS,
+      env: { ...process.env, MOMENTUM_PROJECT_DIR: root },
+    })
+    if (r.error) return null
+    const out = `${r.stdout || ""}${r.stderr || ""}`.trim()
+    return out.length ? out : ""
+  } catch {
+    return null
+  }
+}
+
+function extractTargetPath(tool, args) {
+  if (!args || typeof args !== "object") return null
+  if (typeof args.filePath === "string") return args.filePath
+  if (typeof args.path === "string") return args.path
+  if (tool === "bash" && typeof args.command === "string") {
+    // Mirror brainstorm-gate.sh's shell heuristic: first specs/ path in the
+    // command (catches `> specs/...`, `sed -i ... specs/...`, `tee specs/...`).
+    const m = args.command.match(/specs\/[^\s"'\\]+/)
+    return m ? m[0] : null
+  }
+  return null
+}
+
+function isUnderSpecs(root, targetPath) {
+  const abs = path.isAbsolute(targetPath) ? targetPath : path.join(root, targetPath)
+  const rel = path.relative(path.join(root, "specs"), abs)
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))
+}
+
+export const MomentumPlugin = async ({ directory, worktree }) => {
+  const root = worktree || directory || process.cwd()
+  const momentumDir = path.join(root, ".momentum")
+
+  // tool.execute.after does NOT carry tool args (confirmed live, Phase 22 G5)
+  // — only the before hook sees them. Correlate by callID so the reminder
+  // knows which path a completed write touched. Bounded: entries are removed
+  // at after-time; the cap guards sessions whose after hooks never fire.
+  const pendingWrites = new Map()
+  const pendingBash = new Map()
+  const PENDING_CAP = 512
+
+  const remember = (map, key, value) => {
+    if (map.size >= PENDING_CAP) map.delete(map.keys().next().value)
+    map.set(key, value)
+  }
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      const tool = (input && input.tool) || ""
+      if (!WRITE_TOOLS.has(tool) && tool !== "bash") return
+      const target = extractTargetPath(tool, output && output.args)
+      if (target && WRITE_TOOLS.has(tool) && input && input.callID) {
+        remember(pendingWrites, input.callID, target)
+      }
+      if (tool === "bash" && input && input.callID) {
+        const command = output && output.args && output.args.command
+        if (typeof command === "string") remember(pendingBash, input.callID, command)
+      }
+      if (!fs.existsSync(path.join(momentumDir, "brainstorm-active"))) return
+      if (!target) return // fail-open when no path is extractable
+      if (isUnderSpecs(root, target)) {
+        throw new Error(
+          [
+            "[brainstorm-gate] Blocked: cannot write to specs/ during active brainstorm.",
+            `[brainstorm-gate] Path: ${target}`,
+            "[brainstorm-gate] The conversation IS the draft. Get explicit user approval, then:",
+            "[brainstorm-gate]   rm .momentum/brainstorm-active",
+            "[brainstorm-gate] and retry the write.",
+          ].join("\n"),
+        )
+      }
+    },
+
+    "tool.execute.after": async (input, output) => {
+      try {
+        const tool = (input && input.tool) || ""
+        // Bash completions delegate to the installed reminder script, which
+        // also appends commit/pr events to the ecosystem session log
+        // (ENH-058). The script self-guards: instant no-op outside
+        // ecosystems and for non-matching commands.
+        if (tool === "bash") {
+          let command = input && input.callID ? pendingBash.get(input.callID) : undefined
+          if (input && input.callID) pendingBash.delete(input.callID)
+          if (!command && output && output.args) command = output.args.command
+          if (typeof command !== "string" || !command) return
+          const out = runInstalledScript(root, "check-history-reminder.sh", {
+            tool_name: "Bash",
+            tool_input: { command },
+          })
+          if (out) console.log(out)
+          return
+        }
+        if (!WRITE_TOOLS.has(tool)) return
+        // Args live only in the before hook — recover the path via callID
+        // (fallback to output.args for synthetic/direct invocations).
+        let target = input && input.callID ? pendingWrites.get(input.callID) : undefined
+        if (input && input.callID) pendingWrites.delete(input.callID)
+        if (!target) target = extractTargetPath(tool, output && output.args)
+        if (!target) return
+        // Edits to the spec layer ARE the tracking — only code/doc edits
+        // outside specs/ and .momentum/ warrant a history nudge.
+        if (isUnderSpecs(root, target)) return
+        const rel = path.relative(root, path.isAbsolute(target) ? target : path.join(root, target))
+        if (rel.startsWith(".momentum")) return
+
+        const stampFile = path.join(momentumDir, "history-reminder-stamp")
+        const now = Date.now()
+        try {
+          const last = fs.statSync(stampFile).mtimeMs
+          if (now - last < REMINDER_THROTTLE_MS) return
+        } catch {
+          /* no stamp yet — proceed */
+        }
+        fs.mkdirSync(momentumDir, { recursive: true })
+        fs.writeFileSync(stampFile, String(now))
+        console.log(
+          "[momentum] Meaningful edit landed — if this completes a decision, discovery, or " +
+            "scope change, append a history entry to your phase's history.md (Rule 8). " +
+            "Resolve your phase from the current branch (Rule 15).",
+        )
+      } catch {
+        /* reminder is best-effort; never disturb the session */
+      }
+    },
+
+    // Handoff banner. Session events reach plugins ONLY via the generic
+    // `event` bus in opencode 1.17.x — a named "session.created" hook key
+    // never fires (live-verified, Phase 22 follow-up). The event handler is
+    // registered conditionally: its mere presence HANGS `opencode run`
+    // non-interactive mode (reproduced on 1.17.13), and a session-start
+    // banner is meaningless there anyway — so run-mode skips it.
+    ...(process.argv.includes("run")
+      ? {}
+      : {
+          event: async ({ event }) => {
+            try {
+              if (!event || event.type !== "session.created") return
+              // Preferred path (ENH-058): the installed script prints BOTH
+              // banners — ecosystem context (parent-walk + sibling-scan) and
+              // the handoff inbox — with the same output every other adapter
+              // shows. Non-TTY stdin keeps it prompt-free.
+              const banners = runInstalledScript(root, "sessionstart-handoff.sh", null)
+              if (banners !== null) {
+                if (banners) console.log(banners)
+                return
+              }
+              // Fallback (script not installed): pure-JS handoff banner.
+              const inboxDir = path.join(momentumDir, "inbox")
+              if (!fs.existsSync(inboxDir)) return
+              const pending = fs
+                .readdirSync(inboxDir)
+                .filter((f) => /^handoff-\d+\.md$/.test(f))
+                .sort()
+              if (pending.length === 0) return
+              console.log(
+                `[momentum] ${pending.length} pending handoff(s) in .momentum/inbox/: ` +
+                  `${pending.join(", ")} — run /continue (or \`momentum continue\`) to pick up.`,
+              )
+            } catch {
+              /* banner is best-effort; never disturb the session */
+            }
+          },
+        }),
+  }
+}

package/adapters/opencode/skills/momentum-lanes/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: momentum-lanes
+description: Work with concurrent workstreams (Rule 15). Activates when the session involves multiple active branches, cross-lane coordination, or when starting work that should not live on the current branch.
+---
+
+# momentum-lanes
+
+Use this skill when you detect concurrent workstreams or need to coordinate
+across branches. Key behaviors:
+
+1. **Lane binding**: your phase is the phase bound to your branch
+   (`phase-N-shortname`). `specs/status.md` is the cross-lane overview.
+2. **Lane-scoped tracking**: write ONLY your own phase's artifacts
+   (`tasks.md`, `history.md`, `evidence/`). Shared files (`status.md`,
+   `backlog.md`, `changelog/`) are append / own-row-touch only.
+3. **Landing order**: one lane at a time, suite green on updated `main`
+   between landings, remaining lanes rebase.
+
+When the user starts a second workstream or asks about what's in flight,
+read the lane board before proceeding.
+
+## When NOT to apply
+
+- Single-lane, single-branch sessions with no cross-lane coordination
+
+## References
+
+- Rule 15 in `AGENTS.md` — concurrent workstreams
+- `/lanes` command — board, queue, signal, land
+- `specs/status.md` — cross-lane overview

package/adapters/opencode/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/skills/momentum-track/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: momentum-track
+description: Record a new backlog item (bug, feature, tech debt, or enhancement) when you discover work that needs tracking. Activates when the session identifies unplanned work that should be tracked in the backlog.
+---
+
+# momentum-track
+
+When you discover something that should be tracked during a session
+(a bug, a missing feature, tech debt, an enhancement), automatically:
+
+1. Read `specs/backlog/backlog.md` to find the next available ID
+2. Determine item type and prefix: `BUG-`, `FEAT-`, `TD-`, or `ENH-`
+3. Add a row to the appropriate table with priority (infer from urgency), status `open`, and target phase or `unscheduled`
+4. Mention the new item to the user: "I found [issue] and added it as [ID] to backlog"
+
+This skill codifies Rule 3 (Auto-Track Discoveries) from the project rules.
+
+## When NOT to apply
+
+- If the user explicitly asks you not to track something
+- If the issue is already tracked (check the backlog first)
+- For purely conversational exploration where no work item is identified
+
+## References
+
+- `/track` command for manual tracking
+- `specs/backlog/backlog.md` — the backlog file
+- Rule 3 in `AGENTS.md` — auto-track discoveries

package/adapters/opencode/skills/momentum-validate/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: momentum-validate
+description: Check spec structure health of the momentum project. Activates when the user runs `/validate`, asks for a health check, or when spec changes need verification before phase completion.
+---
+
+# momentum-validate
+
+When spec health validation is needed:
+
+1. Read `specs/status.md` — verify required fields are present
+2. Read `specs/backlog/backlog.md` — verify all 4 section tables
+3. For each phase directory under `specs/phases/`: verify all required files
+   and frontmatter
+4. Check `.momentum/installed.json` — verify schema and agent entries
+5. Verify `AGENTS.md` or `CLAUDE.md` primary instruction file has the
+   `## Project Extensions` marker
+6. Report all failures found
+
+This skill supports the `/validate` command for deep spec structure checks.
+Use it proactively before `/complete-phase` to catch structural issues early.
+
+## When NOT to apply
+
+- During active implementation work (validation should not interrupt flow)
+- When the user explicitly asks for no validation
+
+## References
+
+- `/validate` command — run health checks
+- `specs/status.md` — project status
+- Rule 9 in `AGENTS.md` — doc sync protocol

package/bin/antigravity.js

@@ -0,0 +1,112 @@
+'use strict';
+
+// momentum antigravity <subcommand> — Antigravity-specific utilities.
+//
+// Phase 22b G3 (ADR-0006). The only subcommand today is `plugin-pack`:
+// assembles momentum's skills into a native Antigravity PLUGIN bundle
+// (`plugins/<name>/plugin.json` + `skills/`, per the vendor plugin layout —
+// fact-sheet §6). Two targets:
+//
+//   momentum antigravity plugin-pack             → <cwd>/.agents/plugins/momentum/
+//   momentum antigravity plugin-pack --global    → ~/.gemini/config/plugins/momentum/
+//
+// The --global form is the explicit OPT-IN way to get momentum's skills in
+// every Antigravity workspace on this machine (global discovery root,
+// priority below workspace files — a project-level install always wins).
+// Hooks are deliberately NOT packed: plugin hooks run with CWD = the
+// plugin's own directory, so momentum's project-relative hook commands only
+// make sense installed per-project by `momentum init/upgrade`.
+//
+// momentum never installs or provisions the `agy` binary itself — see the
+// VAL-002 adjudication (specs/adhoc/feat-VAL-002-antigravity-compatibility/).
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PLUGIN_NAME = 'momentum';
+
+function copyDirRecursive(src, dest, dryRun, log) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      if (!dryRun) fs.mkdirSync(d, { recursive: true });
+      copyDirRecursive(s, d, dryRun, log);
+    } else {
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(d), { recursive: true });
+        fs.copyFileSync(s, d);
+      }
+      log.push(d);
+    }
+  }
+}
+
+function cmdPluginPack(args) {
+  const global = args.includes('--global');
+  const dryRun = args.includes('--dry-run');
+  const positional = args.filter((a) => !a.startsWith('--'));
+
+  const skillsSrc = path.join(__dirname, '..', 'adapters', 'antigravity', 'skills');
+  if (!fs.existsSync(skillsSrc)) {
+    throw new Error(`antigravity skills source not found at ${skillsSrc}`);
+  }
+
+  const home = process.env.MOMENTUM_HOME_OVERRIDE || os.homedir();
+  const base = global
+    ? path.join(home, '.gemini', 'config', 'plugins', PLUGIN_NAME)
+    : path.join(path.resolve(positional[0] || process.cwd()), '.agents', 'plugins', PLUGIN_NAME);
+
+  console.log(`→ Packing momentum as an Antigravity plugin${dryRun ? ' (dry-run)' : ''}...`);
+  console.log(`  target: ${base}`);
+
+  const written = [];
+  const manifestPath = path.join(base, 'plugin.json');
+  if (!dryRun) {
+    fs.mkdirSync(base, { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify({ name: PLUGIN_NAME }, null, 2) + '\n');
+  }
+  written.push(manifestPath);
+  copyDirRecursive(skillsSrc, path.join(base, 'skills'), dryRun, written);
+
+  for (const f of written) {
+    console.log(`  ${dryRun ? '✋ would write' : '+ wrote'}: ${path.relative(path.dirname(base), f)}`);
+  }
+  console.log('');
+  console.log(`  ✓ plugin ${dryRun ? 'planned' : 'packed'} (${written.length} files).`);
+  console.log(`  Validate: agy plugin validate "${base}"`);
+  if (global) {
+    console.log('  Global plugins apply to every Antigravity workspace on this machine;');
+    console.log('  a per-project momentum install always takes priority.');
+  }
+  return base;
+}
+
+function usage() {
+  console.log('Usage: momentum antigravity <subcommand>');
+  console.log('');
+  console.log('Subcommands:');
+  console.log('  plugin-pack [target] [--global] [--dry-run]');
+  console.log('      Assemble momentum skills as a native Antigravity plugin at');
+  console.log('      <target>/.agents/plugins/momentum/ (or the global discovery');
+  console.log('      root ~/.gemini/config/plugins/momentum/ with --global).');
+}
+
+function runAntigravity(args) {
+  const sub = args[0];
+  if (!sub || sub === 'help' || sub === '--help') {
+    usage();
+    return;
+  }
+  if (sub === 'plugin-pack') {
+    cmdPluginPack(args.slice(1));
+    return;
+  }
+  console.error(`Unknown antigravity subcommand: ${sub}`);
+  usage();
+  process.exit(1);
+}
+
+module.exports = { runAntigravity, cmdPluginPack };