@limina-labs/momentum 0.35.0 → 0.36.0

package/adapters/antigravity/instructions/AGENTS.md

@@ -176,6 +176,10 @@ lives in this AGENTS.md primary-instruction text as a belt-and-braces
 fallback: if a `.momentum/inbox/handoff-NNN.md` file exists at session
 start, read it and acknowledge before continuing.
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), Antigravity's task tool is the native **task list** artifact (task.md) — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -197,7 +201,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the native **task list** artifact (task.md) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -215,7 +219,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "The task-list artifact is enough" — The task-list artifact is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries

package/adapters/antigravity/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "antigravity",
+  "displayName": "Antigravity",
+  "surface": "agents-md",
+  "taskTool": "the native **task list** artifact (task.md)",
+  "taskToolName": "The task-list artifact",
+  "hasSurfaceDelta": true
+}

package/adapters/claude-code/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "claude-code",
+  "displayName": "Claude Code",
+  "surface": "claude-md",
+  "taskTool": "the built-in **TodoWrite** tool",
+  "taskToolName": "TodoWrite",
+  "hasSurfaceDelta": false
+}

package/adapters/codex/instructions/AGENTS.md

@@ -230,6 +230,10 @@ 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.
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), Codex's task tool is the built-in **plan** tool — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -251,7 +255,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the built-in **plan** tool to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -269,7 +273,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "The plan tool is enough" — The plan tool is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries

package/adapters/codex/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "codex",
+  "displayName": "Codex",
+  "surface": "agents-md",
+  "taskTool": "the built-in **plan** tool",
+  "taskToolName": "The plan tool",
+  "hasSurfaceDelta": true
+}

package/adapters/opencode/instructions/AGENTS.md

@@ -143,6 +143,10 @@ skill paths (`.claude/skills/`, `.agents/skills/`); momentum's opencode
 surfaces live under `.opencode/` so multi-adapter installs stay
 side-by-side without collisions.
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), opencode's task tool is the built-in **task** tool (subagent fan-out) — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -164,7 +168,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the built-in **task** tool (subagent fan-out) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -182,7 +186,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "The task tool is enough" — The task tool is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries

package/adapters/opencode/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "opencode",
+  "displayName": "opencode",
+  "surface": "agents-md",
+  "taskTool": "the built-in **task** tool (subagent fan-out)",
+  "taskToolName": "The task tool",
+  "hasSurfaceDelta": true
+}

package/bin/ecosystem.js

@@ -777,9 +777,18 @@ function detectMemberAgent(repoPath) {
     const m = JSON.parse(
       fs.readFileSync(path.join(repoPath, '.momentum', 'installed.json'), 'utf8'),
     );
-    if (m && m.agent) return m.agent;
+    // ADR-0007: the lock is `{ agents: { <id>: … } }`; the pre-0007 lock was
+    // `{ agent }`. Read the map first (else every AGENTS.md agent — opencode,
+    // Antigravity, Codex — falls through to the `AGENTS.md ⇒ codex` heuristic
+    // below and is misidentified). ADR-0011.
+    if (m && m.agents && typeof m.agents === 'object') {
+      const ids = Object.keys(m.agents);
+      if (ids.length) return ids.includes('claude-code') ? 'claude-code' : ids.sort()[0];
+    }
+    if (m && m.agent) return m.agent; // legacy single-agent lock
   } catch (_e) { /* fall through to heuristic */ }
   if (fs.existsSync(path.join(repoPath, '.codex'))) return 'codex';
+  if (fs.existsSync(path.join(repoPath, '.opencode'))) return 'opencode';
   if (fs.existsSync(path.join(repoPath, '.claude'))) return 'claude-code';
   if (
     fs.existsSync(path.join(repoPath, '.agents', 'hooks.json')) ||
@@ -1297,6 +1306,7 @@ module.exports = {
   ensurePointerInjected,
   stripPointer,
   findPrimaryInstructionFile,
+  detectMemberAgent,
   sanitizeId,
   POINTER_BEGIN,
   POINTER_END,

package/bin/momentum.js

@@ -719,7 +719,46 @@ function resolveAdapterSource(srcRoot, adapterDir, fileSpec) {
   return path.join(base, ...fileSpec.source);
 }
 
-function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction) {
+/**
+ * ADR-0011 — the raw primary-instruction template content for `agent`.
+ * A claude-md agent (and a lone installed agents-md agent) gets the static
+ * committed template. When MORE THAN ONE agents-md agent is installed, AGENTS.md
+ * is COMPOSED — the neutral spine once + one integration section per installed
+ * AGENTS.md agent — so switching or running several agents never drops an
+ * integration (fixes the same-path collision). Project name is not yet rendered.
+ */
+function resolvePrimaryInstructionContent(srcRoot, targetDir, agent, srcPath) {
+  const readStatic = () => fs.readFileSync(srcPath, 'utf8');
+  let compose;
+  try {
+    compose = require('../core/lib/instruction-compose');
+  } catch (_e) {
+    return readStatic();
+  }
+  let manifest;
+  try {
+    manifest = compose.readManifest(srcRoot, agent);
+  } catch (_e) {
+    return readStatic(); // unknown / manifest-less agent → static template
+  }
+  if (manifest.surface !== 'agents-md') return readStatic(); // claude-md → static
+
+  // The set of installed AGENTS.md agents ∪ the one being (re)installed.
+  const valid = new Set(compose.discoverAgents(srcRoot));
+  const ids = new Set(valid.has(agent) ? [agent] : []);
+  const state = loadInstalledState(targetDir);
+  for (const id of Object.keys(state.agents || {})) {
+    if (!valid.has(id)) continue;
+    try {
+      if (compose.readManifest(srcRoot, id).surface === 'agents-md') ids.add(id);
+    } catch (_e) { /* skip an agent we can't read */ }
+  }
+  const sorted = [...ids].sort();
+  if (sorted.length <= 1) return readStatic(); // N=1 → static committed template
+  return compose.composeInstruction(srcRoot, sorted); // N>1 → composed
+}
+
+function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction, agent) {
   if (!primaryInstruction) return null;
   const srcPath = resolveAdapterSource(srcRoot, adapterDir, primaryInstruction);
   const destPath = path.join(targetDir, ...primaryInstruction.destination);
@@ -733,7 +772,7 @@ function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstru
       return 'added';
     }
     const rendered = renderProjectName(
-      fs.readFileSync(srcPath, 'utf8'),
+      resolvePrimaryInstructionContent(srcRoot, targetDir, agent, srcPath),
       getProjectName(targetDir)
     );
     fs.mkdirSync(path.dirname(destPath), { recursive: true });
@@ -745,7 +784,7 @@ function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstru
   return 'skipped';
 }
 
-function upgradePrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction) {
+function upgradePrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction, agent) {
   if (!primaryInstruction) return null;
   const srcPath = resolveAdapterSource(srcRoot, adapterDir, primaryInstruction);
   const destPath = path.join(targetDir, ...primaryInstruction.destination);
@@ -753,12 +792,15 @@ function upgradePrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstru
   const projectName = getProjectName(targetDir);
   recordManaged(destPath); // managed (marker-owned)
 
+  // ADR-0011: compose AGENTS.md across all installed AGENTS.md agents.
+  const rawContent = resolvePrimaryInstructionContent(srcRoot, targetDir, agent, srcPath);
+
   console.log(`→ Upgrading ${label}...`);
   if (primaryInstruction.markerAware) {
-    return upgradeMarkedFile(srcPath, destPath, label, targetDir, projectName);
+    return upgradeMarkedFile(srcPath, destPath, label, targetDir, projectName, rawContent);
   }
 
-  const srcContent = renderProjectName(fs.readFileSync(srcPath, 'utf8'), projectName);
+  const srcContent = renderProjectName(rawContent, projectName);
   const relDest = path.relative(targetDir, destPath);
   if (!fileExists(destPath)) {
     if (_dryRun) {
@@ -895,11 +937,14 @@ function partitionByMarker(content) {
  *
  * Returns one of: 'added', 'updated', 'unchanged', 'migrated'.
  */
-function upgradeMarkedFile(srcPath, destPath, label, root, projectName) {
+function upgradeMarkedFile(srcPath, destPath, label, root, projectName, srcContentRaw) {
   const rel = path.relative(root || process.cwd(), destPath);
   recordManaged(destPath); // managed (marker-owned) in all branches
   const render = (content) =>
     projectName ? renderProjectName(content, projectName) : content;
+  // ADR-0011: callers may pass composed content (multi-agent AGENTS.md); else
+  // read the static committed template.
+  const rawSrc = srcContentRaw != null ? srcContentRaw : fs.readFileSync(srcPath, 'utf8');
 
   if (!fileExists(destPath)) {
     if (_dryRun) {
@@ -907,12 +952,12 @@ function upgradeMarkedFile(srcPath, destPath, label, root, projectName) {
       return 'added';
     }
     fs.mkdirSync(path.dirname(destPath), { recursive: true });
-    fs.writeFileSync(destPath, render(fs.readFileSync(srcPath, 'utf8')));
+    fs.writeFileSync(destPath, render(rawSrc));
     console.log(`  + added:    ${rel}`);
     return 'added';
   }
 
-  const srcContent = render(fs.readFileSync(srcPath, 'utf8'));
+  const srcContent = render(rawSrc);
   const destContent = fs.readFileSync(destPath, 'utf8');
   const destParts = partitionByMarker(destContent);
 
@@ -1215,7 +1260,7 @@ function init(targetDir, agent, opts = {}) {
   console.log('→ Inferring project config...');
   installConfig(target, { dryRun: _dryRun });
 
-  installPrimaryInstruction(src, target, adapterDir, adapter.primaryInstruction);
+  installPrimaryInstruction(src, target, adapterDir, adapter.primaryInstruction, agent);
 
   // Adapter overlay — per-agent commands/agent-rules/scripts (additive)
   applyOverlay(adapterDir, target, dests, { backup: true, root: target });
@@ -1381,7 +1426,8 @@ function upgrade(targetDir, agent, opts = {}) {
     src,
     target,
     adapterDir,
-    adapter.primaryInstruction
+    adapter.primaryInstruction,
+    agent
   );
 
   if (hadPointerBlock && !_dryRun) {

package/core/instructions/README.md

@@ -0,0 +1,69 @@
+# Instruction sources — the three-tier variation model (ADR-0011)
+
+The primary instruction file each agent auto-loads (`CLAUDE.md` for Claude Code,
+`AGENTS.md` for every AGENTS.md-standard agent) is **generated**, never
+hand-edited. It is a projection of **(principal constants × per-agent variation
+manifest)**. Regenerate with `npm run generate-instructions`; the suite's drift
+guard fails if a committed template diverges from its sources.
+
+## The three tiers
+
+| Tier | What | Where | Rule |
+|------|------|-------|------|
+| **1 — Principal constants** (the neutral spine) | Navigation table, Rules 1–15, Naming, Constraints, Project Extensions pointer | `core/instructions/navigation.md`, `core/instructions/rules-body.md` | **Byte-identical** across every agent + surface (`CLAUDE.md` ≡ `AGENTS.md` body) |
+| **2 — Variation manifest** | Everything that varies per agent | `adapters/<agent>/instructions/manifest.json` | One declarative record; generator auto-discovers it (OCP) |
+| **3 — Surface delta** | Irreducibly agent-specific integration prose + the task-tool mapping line | `adapters/<agent>/instructions/surfaces.md` (optional) | A scoped delta, never the file's whole identity (SRP) |
+
+The rules body carries **no agent-specific token** — the task tool is named only
+in the Tier-3 delta, which every agent still loads. That is what makes the spine
+byte-identical (and therefore a testable invariant, not a claim).
+
+## `manifest.json` schema
+
+```json
+{
+  "id": "opencode",
+  "displayName": "opencode",
+  "surface": "agents-md",
+  "taskTool": "the built-in **task** tool (subagent fan-out)",
+  "taskToolName": "The task tool",
+  "hasSurfaceDelta": true
+}
+```
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `id` | string | Adapter id — must match the `adapters/<id>/` directory name |
+| `displayName` | string | Human name used in the header scaffold + integration heading |
+| `surface` | `"claude-md"` \| `"agents-md"` | Which instruction file this agent reads; drives the install destination |
+| `taskTool` | string | Rendered into the Tier-3 task-tool mapping line (may contain markdown) |
+| `taskToolName` | string | Capitalized short form for prose references |
+| `hasSurfaceDelta` | boolean | Whether a `surfaces.md` integration delta exists for this agent |
+
+## Assembly order
+
+```
+header (scaffold, display name from manifest)
+  → navigation (Tier 1)
+  → surfaces delta (Tier 3, if hasSurfaceDelta)
+  → rules body (Tier 1, agent-neutral)
+  → Project Extensions pointer tail (ADR-0010)
+```
+
+## Adding a new agent (the OCP path)
+
+1. Create `adapters/<id>/instructions/manifest.json`.
+2. Optionally add `adapters/<id>/instructions/surfaces.md` (integration delta).
+3. Run `npm run generate-instructions`.
+
+No edit to `scripts/generate-instructions.js` is required — it discovers
+adapters by scanning `adapters/*/instructions/`. A suite test proves this by
+generating for a synthetic adapter with zero generator edits.
+
+## AGENTS.md when multiple AGENTS.md agents are installed
+
+`AGENTS.md` is a shared standard, so one repo can host several AGENTS.md agents.
+The committed per-agent template is the single-agent (N=1) projection. At
+install/upgrade, when `installed.json.agents` holds more than one `agents-md`
+agent, `AGENTS.md` is **composed**: the neutral spine once, plus one integration
+section per installed AGENTS.md agent. `CLAUDE.md` is unaffected (Claude-only).

package/core/instructions/rules-body.md

@@ -19,7 +19,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use {{TASK_TOOL}} to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -37,7 +37,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "{{TASK_TOOL_NAME}} is enough" — {{TASK_TOOL_NAME}} is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries

package/core/lib/instruction-compose.js

@@ -0,0 +1,175 @@
+'use strict';
+
+// ADR-0011 — the instruction file is a projection of
+// (principal constants × per-agent variation manifest).
+//
+// Pure assembly logic, shipped in core/ so BOTH build-time generation
+// (scripts/generate-instructions.js) and install-time multi-agent AGENTS.md
+// composition (bin/momentum.js) use ONE code path. Every function takes
+// `root` = the momentum package/repo root that holds core/ + adapters/.
+//
+// Three tiers:
+//   1. Principal constants (neutral spine): core/instructions/navigation.md +
+//      rules-body.md — byte-identical across every agent + surface.
+//   2. Variation manifest: adapters/<id>/instructions/manifest.json.
+//   3. Surface delta: adapters/<id>/instructions/surfaces.md (optional).
+//
+// Assembly:
+//   marker → header → navigation → (per agent: surfaces? + task-tool note)
+//     → neutral rules body → Project Extensions pointer tail (ADR-0010)
+
+const fs = require('fs');
+const path = require('path');
+
+const MARKER_COMMENT = [
+  '<!-- momentum-managed (generated) — regenerate with `npm run generate-instructions`',
+  '     in the momentum repo; sources: core/instructions/ + adapters/<agent>/instructions/.',
+  "     Everything above '## Project Extensions' may be replaced by `momentum upgrade`. -->",
+].join('\n');
+
+// ADR-0010: `## Project Extensions` is a managed POINTER to specs/project-rules.md,
+// not an authoring surface. Kept byte-identical to core/lib/project-rules.js.
+const EXTENSIONS_TAIL = [
+  '---',
+  '',
+  '## Project Extensions',
+  '',
+  '<!-- momentum:project-rules-pointer -->',
+  '> **Project-specific rules live in `specs/project-rules.md`** — read it now.',
+  '> Session-start self-audits, project constraints, and any project-specific',
+  '> guidance are there, shared identically by every agent (ADR-0010). This',
+  '> section is a momentum-managed pointer; edit `specs/project-rules.md`, not',
+  '> this file.',
+].join('\n');
+
+function readFragment(root, rel) {
+  return fs.readFileSync(path.join(root, ...rel), 'utf8');
+}
+
+/** Discover every adapter that ships an instruction manifest (OCP: add a dir, no edits). */
+function discoverAgents(root) {
+  const dir = path.join(root, 'adapters');
+  return fs
+    .readdirSync(dir)
+    .filter((id) => fs.existsSync(path.join(dir, id, 'instructions', 'manifest.json')))
+    .sort();
+}
+
+function readManifest(root, id) {
+  const m = JSON.parse(readFragment(root, ['adapters', id, 'instructions', 'manifest.json']));
+  for (const key of ['id', 'displayName', 'surface', 'taskTool', 'taskToolName']) {
+    if (typeof m[key] !== 'string' || !m[key]) {
+      throw new Error(`adapters/${id}/instructions/manifest.json: missing/invalid "${key}"`);
+    }
+  }
+  if (m.id !== id) throw new Error(`manifest id "${m.id}" != adapter dir "${id}"`);
+  if (m.surface !== 'claude-md' && m.surface !== 'agents-md') {
+    throw new Error(`adapters/${id}: surface "${m.surface}" — expected claude-md | agents-md`);
+  }
+  return m;
+}
+
+/** The install destination filename implied by the surface. */
+function surfaceDestination(surface) {
+  if (surface === 'claude-md') return 'CLAUDE.md';
+  if (surface === 'agents-md') return 'AGENTS.md';
+  throw new Error(`unknown surface "${surface}"`);
+}
+
+/** Where this agent's committed (N=1) template lives, derived from its surface. */
+function templatePath(id, surface) {
+  if (surface === 'claude-md') return ['core', 'specs-templates', 'CLAUDE.md'];
+  if (surface === 'agents-md') return ['adapters', id, 'instructions', 'AGENTS.md'];
+  throw new Error(`unknown surface "${surface}" for adapter "${id}"`);
+}
+
+/** Header: single scaffold constant, agent display name(s) the only variable. */
+function renderHeader(manifests) {
+  const title = '# Project Rules: <Project Name>';
+  if (manifests.length === 1) {
+    return `${title}\n\n> ${manifests[0].displayName} configuration for this momentum-managed project.`;
+  }
+  const names = manifests.map((m) => m.displayName).join(', ');
+  return (
+    `${title}\n\n> Configuration for this momentum-managed project. This shared ` +
+    `AGENTS.md serves ${manifests.length} agents (${names}); each has its own ` +
+    `integration section below.`
+  );
+}
+
+/** The one agent-specific line lifted out of the neutral spine (SRP). */
+function renderTaskToolNote(m) {
+  return [
+    '## In-Session Task Tool',
+    '',
+    `When a rule mentions tracking in-session progress (Rule 2), ${m.displayName}'s ` +
+      `task tool is ${m.taskTool} — in-session only; the durable record is ` +
+      '`specs/phases/<phase>/tasks.md`.',
+  ].join('\n');
+}
+
+function readSurfaces(root, m) {
+  if (!m.hasSurfaceDelta) return null;
+  const p = path.join(root, 'adapters', m.id, 'instructions', 'surfaces.md');
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+}
+
+function finalize(parts) {
+  const content = parts.map((p) => p.replace(/\s+$/, '')).join('\n\n') + '\n';
+  const leftover = content.match(/\{\{[A-Z_]+\}\}/);
+  if (leftover) throw new Error(`unrendered placeholder ${leftover[0]}`);
+  return content;
+}
+
+/**
+ * Compose an instruction file for one or more agents.
+ * - Single id → the committed N=1 projection (a static template).
+ * - Multiple ids → neutral spine + one integration section per agent
+ *   (install-time AGENTS.md when several AGENTS.md agents are installed).
+ */
+function composeInstruction(root, ids) {
+  if (!ids.length) throw new Error('composeInstruction: no agents');
+  const manifests = ids.map((id) => readManifest(root, id));
+  const navigation = readFragment(root, ['core', 'instructions', 'navigation.md']);
+  const body = readFragment(root, ['core', 'instructions', 'rules-body.md']);
+
+  const parts = [MARKER_COMMENT, renderHeader(manifests), navigation];
+  for (const m of manifests) {
+    const surfaces = readSurfaces(root, m);
+    if (surfaces) parts.push(surfaces);
+    parts.push(renderTaskToolNote(m));
+  }
+  parts.push(body, EXTENSIONS_TAIL);
+  return finalize(parts);
+}
+
+/** One committed template descriptor for a single agent. */
+function generateFor(root, id) {
+  const m = readManifest(root, id);
+  const target = templatePath(id, m.surface);
+  return {
+    agent: id,
+    targetRel: target.join('/'),
+    targetPath: path.join(root, ...target),
+    content: composeInstruction(root, [id]),
+    manifest: m,
+  };
+}
+
+function generateAll(root) {
+  return discoverAgents(root).map((id) => generateFor(root, id));
+}
+
+module.exports = {
+  MARKER_COMMENT,
+  EXTENSIONS_TAIL,
+  discoverAgents,
+  readManifest,
+  surfaceDestination,
+  templatePath,
+  renderHeader,
+  renderTaskToolNote,
+  composeInstruction,
+  generateFor,
+  generateAll,
+};

package/core/specs-templates/CLAUDE.md

@@ -4,7 +4,7 @@
 
 # Project Rules: <Project Name>
 
-> Claude Code configuration for this project.
+> Claude Code configuration for this momentum-managed project.
 
 ## Navigation (Where to Find Things)
 
@@ -22,6 +22,10 @@
 
 ---
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), Claude Code's task tool is the built-in **TodoWrite** tool — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -43,7 +47,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the built-in **TodoWrite** tool to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -61,7 +65,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "TodoWrite is enough" — TodoWrite is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries

package/package.json

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

package/adapters/antigravity/instructions/header.md

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

package/adapters/antigravity/instructions/vars.json

@@ -1 +0,0 @@
-{ "TASK_TOOL": "the native **task list** artifact (task.md)", "TASK_TOOL_NAME": "The task-list artifact" }

package/adapters/claude-code/instructions/header.md

@@ -1,3 +0,0 @@
-# Project Rules: <Project Name>
-
-> Claude Code configuration for this project.

package/adapters/claude-code/instructions/vars.json

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

package/adapters/codex/instructions/header.md

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

package/adapters/codex/instructions/vars.json

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

package/adapters/opencode/instructions/header.md

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

package/adapters/opencode/instructions/vars.json

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