@limina-labs/momentum 0.30.2 → 0.31.1

package/README.md

@@ -1,22 +1,39 @@
 <div align="center">
   <img src="site/src/assets/logo/wordmark.svg" width="280" alt="momentum" />
 
-  ### Spec-driven discipline for agentic AI
+  ### The right context for your coding agent
 
-  Phases. Decisions. History. Backlog. First-class state across any AI IDE.
+  momentum keeps your project's memory and state as Markdown files in the repo —
+  so every session your agent retrieves the right context, hallucinates less,
+  and turns a vague request into a well-grounded plan.
 
   [![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/)
+
+  <sub>Built and maintained by <a href="https://github.com/LiminaLabsAI">Limina Labs</a></sub>
 </div>
 
 ---
 
-## What is momentum?
+## Your agent doesn't need more context. It needs the right context.
+
+**Without it, your agent guesses.** Ask an agent to fix a bug and it greps
+around, fills the gaps with assumptions, and drafts a plan on shaky ground —
+burning tokens rediscovering what your project already knew. And whatever it
+does learn evaporates at the context limit or the next fresh session.
 
-**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 hands the agent your project's real state up front. Phases, decisions,
+history, and backlog live as plain Markdown files in the repo — read at the
+start of every session, updated as the agent works — so it reasons from
+recorded facts instead of guesses, and the *project* persists, not just
+whatever one session shipped.
 
-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.
+| Without momentum | With momentum |
+| --- | --- |
+| Greps the codebase, hopes it found the right files | Reads project state first — oriented in seconds |
+| Fills the gaps with assumptions — hallucinates | Reasons from recorded decisions, not guesses |
+| Plans on shaky ground, burns tokens rediscovering | Produces a well-grounded, actionable plan |
 
 ## Quick install
 
@@ -24,13 +41,16 @@ momentum makes your project's memory durable. Phases, decisions, history, and ba
 npx @limina-labs/momentum@latest init
 ```
 
-That's it. The agent picks up the workflow on next session start.
+momentum asks which coding agent to scaffold for — there is no default. Pass
+`--agent` to answer up front (required in non-interactive shells). 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?
+# Or pick the adapter up front:
+npx @limina-labs/momentum@latest init --agent claude-code  # Claude Code
 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
@@ -39,6 +59,31 @@ npx @limina-labs/momentum@latest init --agent antigravity  # Antigravity
 npx @limina-labs/momentum@latest init --ecosystem my-eco
 ```
 
+## Better context in. Better work out.
+
+- **Less hallucination** — the agent reasons from recorded facts (status,
+  decisions, history) instead of confident guesses. Fewer wrong turns, fewer
+  retries.
+- **Higher-signal context** — the relevant history and prior decisions surface
+  first, not whatever a blind search returned. Less noise in the window, less
+  token waste.
+- **Better-grounded plans** — a vague ask becomes a concrete plan: what to
+  change, where in the codebase, and how to verify it.
+
+Based on hands-on use — momentum reduces guesswork and re-derivation. Your
+mileage will vary by project and agent.
+
+## The phase loop
+
+Work happens in **phases** — one repeatable unit of work, five stages:
+
+**Brainstorm → Plan → Execute → Verify → Release**
+
+Your agent drives all of it: scopes through dialogue (disk writes gated until
+you approve), plans groups + tasks + acceptance criteria, commits per group
+with conventional commits, and marks tasks done only with passing evidence.
+It stops at exactly one hard gate — the merge and release are yours to approve.
+
 ## 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:

package/bin/momentum.js

@@ -1415,7 +1415,8 @@ OKF — specs/ as an Open Knowledge Format bundle (Phase 24, ADR-0005):
   momentum okf index [dir]            Regenerate bundle indexes (root/phases/decisions)
 
 Options:
-  --agent <name>                      Agent to install for (default: claude-code)
+  --agent <name>                      Agent to install for. \`init\` asks when this
+                                      is omitted (and requires it without a TTY)
                                       Available: ${formatAvailableAgents()}
   --dry-run                           init/upgrade: preview the action set; write nothing
   --autostash                         upgrade: stash a dirty tree, upgrade, then restore it
@@ -1627,6 +1628,55 @@ function promptYesNo(question) {
 
 // ── Entry point ───────────────────────────────────────────────────────────────
 
+// ── init agent picker (v0.31.0) ──────────────────────────────────────────────
+//
+// `init` has no default adapter: an install that guesses is worse than one
+// that asks. Interactive shells get a numbered picker; non-interactive
+// callers (CI, agents, pipes) must pass --agent explicitly.
+// MOMENTUM_FORCE_INTERACTIVE=1 lets tests exercise the picker through pipes.
+function promptForAgent() {
+  const agents = listAvailableAgents();
+  const interactive = (process.stdin.isTTY && process.stdout.isTTY)
+    || process.env.MOMENTUM_FORCE_INTERACTIVE === '1';
+  if (!interactive) {
+    console.error('Error: --agent is required when init runs non-interactively.');
+    console.error(`Available: ${agents.join(', ')}`);
+    console.error(`Example: npx @limina-labs/momentum@latest init --agent ${agents[0] || 'claude-code'}`);
+    process.exit(1);
+  }
+  console.log('\nWhich coding agent should momentum install for?\n');
+  agents.forEach((name, i) => console.log(`  ${i + 1}. ${name}`));
+  console.log('');
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    let resolved = false;
+    // Piped stdin can end before an answer arrives — treat EOF as "no pick".
+    rl.on('close', () => {
+      if (!resolved) {
+        console.error('\nError: no agent selected.');
+        process.exit(1);
+      }
+    });
+    const ask = () => {
+      rl.question(`Agent [1-${agents.length}]: `, (answer) => {
+        const input = answer.trim();
+        // Accept the agent name itself or its 1-based list number.
+        const pick = agents.includes(input) ? input : agents[Number(input) - 1];
+        if (pick) {
+          resolved = true;
+          rl.close();
+          resolve(pick);
+          return;
+        }
+        console.log(`  Enter 1-${agents.length} or an agent name.`);
+        ask();
+      });
+    };
+    ask();
+  });
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -1642,6 +1692,10 @@ async function main() {
   // root command surface, upgrade's sweep override — ENH-049), so an
   // explicit flag is re-injected at that dispatch rather than silently
   // swallowed here.
+  //
+  // The claude-code fallback below serves upgrade/ecosystem paths only —
+  // `init` never uses it: since v0.31.0 an omitted --agent makes init ask
+  // interactively (or fail fast when there is no TTY to ask on).
   let agent = 'claude-code';
   let agentExplicit = false;
   const agentFlagIdx = args.indexOf('--agent');
@@ -1670,6 +1724,10 @@ async function main() {
     const initOpts = extractInitFlags(args.filter((a) => a !== '--dry-run'));
     const targetDir = initOpts.target || process.cwd();
     try {
+      // v0.31.0: no silent default agent — momentum is multi-adapter, and a
+      // hidden claude-code default scaffolds the wrong surface for every
+      // other agent's users. Ask when we can, fail fast when we can't.
+      if (!agentExplicit) agent = await promptForAgent();
       init(targetDir, agent, { dryRun });
       // Ecosystem auto-detect/scaffold mutates state — skip it on a dry run.
       if (!dryRun) await postInitEcosystem(targetDir, initOpts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limina-labs/momentum",
-  "version": "0.30.2",
+  "version": "0.31.1",
   "description": "Agent-agnostic, specs-driven development framework — single project or multi-project ecosystem",
   "homepage": "https://trymomentum.github.io",
   "bin": {