@limina-labs/momentum 0.30.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avinash Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+<div align="center">
+  <img src="site/src/assets/logo/wordmark.svg" width="280" alt="momentum" />
+
+  ### Spec-driven discipline for agentic AI
+
+  Phases. Decisions. History. Backlog. First-class state across any AI IDE.
+
+  [![npm](https://img.shields.io/npm/v/@limina-labs/momentum?logo=npm)](https://www.npmjs.com/package/@limina-labs/momentum)
+  [![license](https://img.shields.io/github/license/LiminaLabsAI/momentum)](LICENSE)
+  [![visit the site](https://img.shields.io/badge/site-trymomentum.github.io-4F46E5)](https://trymomentum.github.io/)
+</div>
+
+---
+
+## What is momentum?
+
+**Your AI coding agent forgets.** Hit the context limit or open a fresh session and it loses the roadmap, the architecture decisions, the bug it fixed an hour ago. The chat window is the wrong place to keep your project's source of truth — the file system is.
+
+momentum makes your project's memory durable. Phases, decisions, history, and backlog live as plain files your agent reads at the start of every session and updates as it works — so the *project* persists, not just whatever the agent shipped this session. Whether your agent writes code, manages infrastructure, runs research, or operates pipelines, the same discipline applies: every phase planned, every decision recorded, every release tagged.
+
+## Quick install
+
+```bash
+npx @limina-labs/momentum@latest init
+```
+
+That's it. The agent picks up the workflow on next session start.
+
+> Always pin `@latest`. A bare `npx @limina-labs/momentum` can serve a
+> stale, cached version; `@latest` forces npx to resolve the newest release.
+
+```bash
+# Want a specific adapter?
+npx @limina-labs/momentum@latest init --agent opencode     # opencode
+npx @limina-labs/momentum@latest init --agent codex        # Codex
+npx @limina-labs/momentum@latest init --agent antigravity  # Antigravity
+
+# Coordinating multiple related projects?
+npx @limina-labs/momentum@latest init --ecosystem my-eco
+```
+
+## How it works — no daemon, no lock-in
+
+momentum isn't a framework or a background service. It's plain files and conventions your agent already knows how to read:
+
+1. **`init` writes files into your repo** — your agent's instruction file (`CLAUDE.md` / `AGENTS.md`), a `specs/` folder, rule and slash-command definitions, and git hooks.
+2. **Your AI IDE already reads that instruction file every session** — momentum just fills it with a structured workflow and a map of where project state lives.
+3. **Your agent maintains the state as it works** — it reads `status.md` to orient, logs decisions to `history.md`, and tracks work in `backlog.md`. Automatically.
+
+Nothing runs in the background. No service to manage, no lock-in: **uninstall = delete the files.**
+
+## Works with any AI IDE
+
+| Agent | Status | Primary instruction file |
+| --- | --- | --- |
+| [opencode](https://opencode.ai) | ✅ Shipped (v0.28.0, live-validated) | `AGENTS.md` |
+| [Claude Code](https://trymomentum.github.io/ide-support/#claude-code) | ✅ Shipped | `CLAUDE.md` |
+| [Codex](https://trymomentum.github.io/ide-support/#codex) | ✅ Shipped | `AGENTS.md` |
+| [Antigravity](https://trymomentum.github.io/ide-support/#antigravity) | ✅ Shipped | `AGENTS.md` |
+| [Cursor](https://trymomentum.github.io/ide-support/#cursor) | 🛠️ Planned (Phase 15) | `.cursor/rules/` |
+| [Gemini CLI](https://trymomentum.github.io/ide-support/#gemini-cli) | 🛠️ Planned (Phase 15) | `GEMINI.md` |
+
+Same commands, same workflow, every agent. Switch adapters anytime; the per-project state survives.
+
+## Keeping projects up to date
+
+Upgrading is **two steps** — update the CLI, then re-sync each project's files:
+
+```bash
+npm install -g @limina-labs/momentum@latest   # 1. update the CLI
+momentum upgrade                                    # 2. re-sync this project
+```
+
+`momentum upgrade` copies files from the *installed* CLI (not from npm), so your
+project files are only ever as new as the CLI — skip step 1 and step 2 just
+re-installs the same old files. Upgrade is safe by design: your `## Project
+Extensions` block is preserved, changed files are backed up to `.bak`, files a
+newer version drops are removed (also `.bak`-backed), and your own files are
+never touched. Preview anything with `momentum upgrade --dry-run`.
+
+Running an **ecosystem**? Sweep every member in one pass:
+
+```bash
+momentum ecosystem upgrade              # skips dirty repos; reports each version
+momentum ecosystem upgrade --dry-run    # preview the whole fleet, write nothing
+momentum ecosystem upgrade --autostash  # stash dirty repos, upgrade, restore them
+```
+
+`--autostash` lets a repo with uncommitted work upgrade anyway: it stashes the
+in-flight changes, runs the upgrade on a clean tree, then restores your work
+exactly as it was — so you don't have to commit or stash by hand first. If the
+upgrade ever touches a file you'd also changed, your work is kept safe in
+`git stash` rather than overwritten. (`--force` is the blunt alternative:
+upgrade in place without stashing.) Same flags work on single-repo
+`momentum upgrade`.
+
+A momentum-managed project records its version-of-record in
+`.momentum/installed.json` (committed) — that's what powers orphan cleanup and
+the ecosystem sweep's per-repo version report.
+
+## Your specs are an open knowledge bundle
+
+Every momentum project's `specs/` tree is a conformant **[Open Knowledge
+Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+(OKF v0.1)** bundle — Google Cloud's open, vendor-neutral standard for agent
+knowledge: markdown concept files with YAML frontmatter, reserved `index.md`
+listings for progressive disclosure, ordinary markdown links as the
+relationship graph. Any OKF consumer — a knowledge catalog, a visualizer,
+someone else's agent — can read your specs with zero momentum knowledge, and
+there is no JSON state left to drift: a phase's status lives in the phase's
+own `overview.md` frontmatter.
+
+```bash
+momentum okf check    # conformance report for specs/ (exit 1 on violations)
+momentum okf index    # regenerate the bundle listings
+```
+
+Existing projects convert automatically on `momentum upgrade`: legacy
+`specs/phases/index.json` is distributed into per-phase frontmatter,
+`impact-map.json` becomes a readable table, every spec file gains its `type`,
+and the old JSON is removed. The migration preserves your prose byte-for-byte
+and is idempotent. (ADR-0005.)
+
+## What you get
+
+| | |
+| --- | --- |
+| 🧭 **Phases** | Plan → execute → verify → release. Every phase has a brainstorm, plan, tasks, history. |
+| 📋 **Backlog** | Bugs / features / tech debt / enhancements with priorities and per-item context. |
+| 📜 **History** | Append-only log of decisions, discoveries, scope changes. The *why* outlives any session. |
+| ⚖️ **Rules** | 13 autonomous agent rules — orient first, verify before claim, log every decision. |
+| 🛠️ **Skills** | ~15 slash commands your agent runs — start, complete, sync, review, validate. |
+| 🌐 **Multi-project** | Ecosystem mode (state layer) + Orchestration primitives (action layer) for cross-project work. |
+
+## Single project ↔ Multi-project ecosystem
+
+Single-project usage is the default. When you have related projects that need to coordinate, ecosystem mode lets one agent session work across all of them.
+
+```mermaid
+flowchart LR
+    subgraph single [SINGLE PROJECT]
+        A1[your agent] --> A2[your-project/]
+    end
+
+    subgraph multi [ECOSYSTEM]
+        B1[one agent session]
+        B1 --> B2[my-eco/]
+        B2 --> B3[project-a/]
+        B2 --> B4[project-b/]
+        B2 --> B5[project-c/]
+    end
+
+    style single fill:#F8FAFC,stroke:#94A3B8,stroke-width:1px
+    style multi fill:#EEF2FF,stroke:#4F46E5,stroke-width:1px
+```
+
+**Hard invariant**: a project running `momentum init` without `--ecosystem` sees zero difference from before ecosystem mode existed. Ecosystem mode is purely additive.
+
+[Read the ecosystem deep dive →](https://trymomentum.github.io/ecosystem/)
+
+## Orchestration primitives
+
+Four verbs the agent composes per task — not a pipeline. They're how the agent **acts** across projects (ecosystem mode is the durable **state** they read and write).
+
+- **`scout`** — Read-only context fetch from a project without opening a session there.
+- **`dispatch`** — Parallel fan-out across N projects with auto-tailored prompts + synthesis.
+- **`handoff`** — Cross-session control transfer with a structured context block.
+- **`continue`** — Pick up a pending handoff. Idempotent.
+
+[Read the orchestration deep dive →](https://trymomentum.github.io/orchestration/)
+
+## Parallel workstreams
+
+One repo, several features in flight, each in its own agent session — momentum models each as a **lane**: a branch (usually in its own worktree) bound to one phase, with its own session. Each session resolves its phase from its branch, writes only its own lane's tracking, and finished lanes land on `main` **one at a time** with the suite green between landings. `momentum lanes` is the mechanism: open lanes (worktree created for you), see the ambient board with queue pressure from any session, signal other lanes, and land through a merge queue with graded evidence gates. Isolation substrate is yours to pick — plain `git worktree` works out of the box; treehouse pools or GitButler virtual branches light up extra speed. momentum recommends, never requires.
+
+[Read the parallel workstreams guide →](https://trymomentum.github.io/parallel-work/)
+
+## The 13 autonomous rules
+
+Discipline preserved without enforcement overhead. Three of the highest-leverage:
+
+- **Rule 6 — Git lifecycle.** Feature branch auto-created. Conventional commits. Push silently. NEVER merge to main without explicit OK.
+- **Rule 8 — Record phase history.** Every meaningful decision lands in `history.md` at the moment it happens. The *why* outlives every session.
+- **Rule 12 — Verify before claim.** No completion without evidence. Run the test, read the output, mark done only if the output shows pass.
+
+[Read all 13 rules with full text + red flags →](https://trymomentum.github.io/rules/)
+
+## Why momentum exists
+
+The thesis is narrow: **state that outlives any single session**.
+
+What's new about agentic AI is that the agent acts. What's old is that acts without context disappear into noise. Spec-driven discipline gives the agent context that outlives any single session — `status.md` at session start, `history.md` for every decision, `backlog.md` for everything queued. The agent verifies before claiming done. The agent doesn't pollute curated docs with orchestration noise.
+
+The discipline is the differentiator. The toolkit is the implementation.
+
+[Read the philosophy + design principles →](https://trymomentum.github.io/about/)
+
+## Docs
+
+- 🌐 **Live site** — [trymomentum.github.io](https://trymomentum.github.io/)
+- 📚 **Getting started** — [trymomentum.github.io/getting-started/](https://trymomentum.github.io/getting-started/)
+- 💡 **Concepts** — [trymomentum.github.io/concepts/](https://trymomentum.github.io/concepts/)
+- 🛠️ **Skills** — [trymomentum.github.io/skills/](https://trymomentum.github.io/skills/)
+- ⚖️ **Rules** — [trymomentum.github.io/rules/](https://trymomentum.github.io/rules/)
+- 🌐 **Multi-project** — [Ecosystem mode](https://trymomentum.github.io/ecosystem/) · [Orchestration](https://trymomentum.github.io/orchestration/)
+- ❓ **FAQ** — [trymomentum.github.io/faq/](https://trymomentum.github.io/faq/)
+
+## Contributing
+
+Issues + discussions + PRs welcome at [github.com/LiminaLabsAI/momentum](https://github.com/LiminaLabsAI/momentum). The project itself uses momentum, so contributing means following the same workflow — phases, history entries, conventional commits, `/complete-phase` before release.
+
+## License
+
+[MIT](LICENSE)

package/adapters/antigravity/adapter.js

@@ -0,0 +1,196 @@
+'use strict';
+
+// Antigravity adapter for momentum.
+//
+// Antigravity (2.x: IDE + `agy` CLI + Python SDK over one shared agent
+// harness) auto-loads AGENTS.md hierarchically as its primary instruction
+// surface and discovers workflows/skills/hooks/plugins under the `.agents/`
+// customization root. Contract locked by live probes against agy 1.0.16 —
+// see specs/phases/phase-22b-antigravity-2-adoption/evidence/fact-sheet.md
+// and ADR-0006.
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+module.exports = {
+  displayName: 'Antigravity',
+
+  destinations: {
+    // Phase 22b (ADR-0006): ONE canonical customization root — .agents/.
+    // agy 1.0.16 accepts .agents/.agent/_agents/_agent equally (fact-sheet §1);
+    // .agents/ is what every vendor example, the builtin reference docs, and
+    // the plugin layout use. Legacy .agent/ files are orphan-cleaned on
+    // upgrade (Phase 20 machinery; user-owned files keep their shield).
+    // Recipes are workflows (auto-register as /<name> slash commands).
+    // agents/ declared but unused — personas live as skills on Antigravity.
+    commands: ['.agents', 'workflows'], // legacy commands key reused — overlay still feeds via destinations[commands]
+    'agent-rules': ['.agents', 'rules'],
+    scripts: ['scripts'],
+    engines: ['.agents', 'engines'],
+    workflows: ['.agents', 'workflows'],
+    skills: ['.agents', 'skills'],
+    agents: ['.agents', 'agents'],
+  },
+
+  primaryInstruction: {
+    source: ['instructions', 'AGENTS.md'],
+    destination: ['AGENTS.md'],
+    label: 'AGENTS.md',
+    markerAware: true,
+  },
+
+  configFiles: [
+    {
+      source: ['hooks.json'],
+      destination: ['.agents', 'hooks.json'],
+      label: '.agents/hooks.json',
+    },
+  ],
+
+  capabilities: {
+    hooks: true,          // Phase 22b: five-event contract verified live (fact-sheet §5; PreToolUse/PostToolUse/PreInvocation/PostInvocation/Stop all fired)
+    slashCommands: true,  // Phase 22b: workflows auto-register as /<name> — verified live incl. planted markers (fact-sheet §3)
+    subagents: true,
+    parallelSubagents: true,
+    sessionStartHook: false, // Phase 22b: no SessionStart event EXISTS (5-event surface). Equivalent ships via PreInvocation invocationNum==0 + injectSteps; flip gated on the live injection round-trip (ENH-054 hang blocks re-probe).
+    skills: true,         // Phase 22b: <name>/SKILL.md discovery verified live (fact-sheet §4)
+    browser: false,
+    computerUse: false,
+    artifacts: true,
+    planningMode: true,
+  },
+
+  roadmap: {
+    sessionStartHook:
+      'Phase 22b (ADR-0006): SessionStart does not exist on Antigravity — the momentum-session-context PreInvocation hook injects the handoff banner + queued notices as ephemeralMessage at invocationNum 0. Capability flips true once the injection round-trip is verified live (re-probe blocked by the intermittent agy 1.0.16 hook-runner hang, ENH-054). AGENTS.md text carries the fallback handoff hint meanwhile.',
+  },
+
+  runInstall(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged } = helpers;
+
+    console.log('→ Configuring Antigravity hooks...');
+    const hooksDest = path.join(targetDir, '.agents', 'hooks.json');
+    if (recordManaged) recordManaged(hooksDest); // managed regardless of write
+    if (!fileExists(hooksDest)) {
+      copyFile(path.join(adapterDir, 'hooks.json'), hooksDest);
+    } else {
+      console.log('  ⚠️  .agents/hooks.json already exists.');
+      console.log(`     Merge hooks manually from: ${path.join(adapterDir, 'hooks.json')}`);
+    }
+  },
+
+  runUpgrade(targetDir, adapterDir, helpers) {
+    const { copyFile, fileExists, recordManaged, dryRun } = helpers;
+
+    console.log('→ Upgrading Antigravity hooks...');
+    const src = path.join(adapterDir, 'hooks.json');
+    const dest = path.join(targetDir, '.agents', '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: .agents/hooks.json');
+        } else {
+          fs.copyFileSync(dest, dest + '.bak');
+          copyFile(src, dest);
+          console.log('  ↑ upgraded: .agents/hooks.json (original saved as .bak)');
+        }
+      }
+    } else {
+      copyFile(src, dest);
+      console.log('  + added:    .agents/hooks.json');
+    }
+  },
+
+  // Phase 22b G2 — adapter.spawn(directive) on the REAL agy CLI surface.
+  //
+  // agy 1.0.16 has no --cwd/--skill flags (fact-sheet §7 — the Phase 18
+  // contract was written against a runtime that did not exist). Real shape:
+  //   - run FROM directive.repoPath (process cwd),
+  //   - headless print mode: -p <prompt>,
+  //   - --new-project: MANDATORY isolation — without it print mode can
+  //     resume an unrelated prior conversation for the workspace,
+  //   - skill engagement by name in the prompt (semantic activation),
+  //   - --dangerously-skip-permissions: supervisors edit files headlessly,
+  //   - --print-timeout as the in-CLI bound + detached launch with logs:
+  //     print runs take minutes and can hang PAST their own timeout when
+  //     hooks are present (ENH-054) — the conductor monitors via the board
+  //     and the per-repo log file; never block the conductor's session.
+  spawn(directive) {
+    if (!directive || directive.platform !== 'antigravity') {
+      return {
+        repoId: directive && directive.repoId,
+        status: -1,
+        detail: `non-antigravity platform: ${directive && directive.platform}`,
+      };
+    }
+    const agyBin = process.env.AGY_BIN || 'agy';
+
+    // Synchronous missing-binary detection (the async 'error' event would
+    // arrive after we return the contract tuple).
+    const resolved = agyBin.includes(path.sep)
+      ? (fs.existsSync(agyBin) ? agyBin : null)
+      : (() => {
+          const w = spawnSync('which', [agyBin], { encoding: 'utf8' });
+          return w.status === 0 ? agyBin : null;
+        })();
+    if (!resolved) {
+      return {
+        repoId: directive.repoId,
+        status: -1,
+        detail: `agy not found (${agyBin}) — install: curl -fsSL https://antigravity.google/cli/install.sh | bash`,
+      };
+    }
+
+    const printTimeout = process.env.MOMENTUM_AGY_PRINT_TIMEOUT || '30m';
+    const prompt = [
+      `Load the swarm-supervisor skill and stay in that persona.`,
+      `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 = [
+      '--new-project',
+      '--dangerously-skip-permissions',
+      '--print-timeout', printTimeout,
+      '-p', prompt,
+    ];
+
+    let logPath = null;
+    let out = 'ignore';
+    try {
+      const logDir = path.join(directive.repoPath, '.momentum');
+      fs.mkdirSync(logDir, { recursive: true });
+      logPath = path.join(logDir, `swarm-supervisor-${directive.swarmId}-w${directive.wave}.log`);
+      out = fs.openSync(logPath, 'a');
+    } catch (_) { /* log file is best-effort — spawn proceeds without it */ }
+
+    try {
+      const child = spawn(resolved, args, {
+        cwd: directive.repoPath,
+        env: Object.assign({}, process.env, directive.env),
+        detached: true,
+        stdio: ['ignore', out, out],
+      });
+      child.unref();
+      if (typeof out === 'number') fs.closeSync(out);
+      return {
+        repoId: directive.repoId,
+        status: 0,
+        detail: `launched pid ${child.pid}${logPath ? ` (log: ${logPath})` : ''}`,
+      };
+    } catch (err) {
+      if (typeof out === 'number') { try { fs.closeSync(out); } catch (_) {} }
+      return {
+        repoId: directive.repoId,
+        status: -1,
+        detail: (err && err.message) || 'spawn failed',
+      };
+    }
+  },
+};

package/adapters/antigravity/hooks.json

@@ -0,0 +1,39 @@
+{
+  "momentum-brainstorm-gate": {
+    "PreToolUse": [
+      {
+        "matcher": "write_to_file|run_command|.*write.*|.*edit.*|.*replace.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ../scripts/antigravity-hook-adapter.sh pre-tool",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
+  "momentum-history-reminder": {
+    "PostToolUse": [
+      {
+        "matcher": "write_to_file|run_command|.*write.*|.*edit.*|.*replace.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ../scripts/antigravity-hook-adapter.sh post-tool",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
+  "momentum-session-context": {
+    "PreInvocation": [
+      {
+        "type": "command",
+        "command": "bash ../scripts/antigravity-hook-adapter.sh pre-invocation",
+        "timeout": 15
+      }
+    ]
+  }
+}