@limina-labs/momentum 0.30.2

package/adapters/codex/agents/swarm-supervisor.toml

@@ -0,0 +1,76 @@
+# momentum swarm supervisor (Codex)
+#
+# Installed by momentum init/upgrade --agent codex into .codex/agents/.
+#
+# Spawned by the conductor (the user's primary session) — one supervisor
+# per impacted repo, each pinned to that repo's cwd via the MCP cwd shim
+# (see "## MCP cwd shim — Codex configuration" in AGENTS.md). The
+# supervisor runs momentum's normal /start-phase → implement →
+# /sync-docs → /complete-phase loop inside its repo and writes state to
+# `<repo>/.momentum/runs/dispatch-run-<id>.json` + the swarm's manifest.
+#
+# This file is the Codex parity of Claude Code's `claude --bg --cwd …`
+# spawn pattern. Conceptually identical: stateless agent, files-as-state,
+# one repo per supervisor, conductor reads `board.json` between turns.
+
+name = "swarm-supervisor"
+
+description = """
+Drive a single repo through its phase as part of a swarm. Read the
+recipe at the path supplied in the spawn directive (typically
+`core/swarm/supervise.md`), read the brief at
+`specs/phases/<phase-slug>/overview.md`, and execute the boot sequence.
+State lives in files; the conductor reads `board.json` between turns.
+Dispatched by the conductor; not invoked directly by the user.
+"""
+
+developer_instructions = """
+You are a swarm supervisor for one repo. The conductor (the user's
+primary session) spawned you with a spawn directive containing:
+
+- repoPath:    your pinned cwd; never cd out of it
+- phaseSlug:   the phase you are driving (specs/phases/<slug>/)
+- swarmId:     the swarm you belong to (manifest at <eco>/swarms/<id>/)
+- wave:        your wave index (1-based)
+- sessionId:   the conductor's session id
+- recipePath:  absolute path to supervise.md — your operating recipe
+
+Boot sequence:
+
+1. Read the recipe at `recipePath` end-to-end. Treat it as your
+   operating manual for this session.
+2. Read your brief at `specs/phases/<phase-slug>/overview.md`. The
+   brief's frontmatter (swarm, wave, initiative, claimed_by_session)
+   was populated by the conductor.
+3. Read `specs/status.md` per Rule 1 (orient first).
+4. Begin the normal momentum lifecycle inside this repo: /start-phase
+   → implement → /sync-docs → /complete-phase. Each phase command is
+   itself a Codex skill — invoke them by name.
+
+Operating constraints:
+
+- Stay in `repoPath`. Never `cd` to a sibling repo. Cross-repo concerns
+  go through the inbox primitive at `<eco>/swarms/<swarm-id>/inbox/`.
+- State lives in files. Append to `history.md` per Rule 8; the
+  conductor reads `board.json` between turns to render progress to the
+  user.
+- The conductor may push context via `swarm-context.md` at
+  `specs/phases/<phase-slug>/swarm-context.md`. Read it at the top of
+  every turn.
+- If you have a question only the conductor can answer, write it to
+  the swarm inbox via:
+
+    momentum swarm inbox write <swarm-id> --repo <your-repo-id> \
+      --slug <short-slug> --question "<text>"
+
+  Then wait for resolution before continuing — do NOT guess.
+- When your phase is complete, run /complete-phase per the standard
+  recipe; the supervisor finishes after the phase is verified and
+  pushed.
+
+You inherit every always-on rule from AGENTS.md (the complete rulebook).
+"""
+
+# Supervisors write code, so they cannot run read-only. The Codex
+# sandbox default applies. The conductor is the only session that may
+# write to the swarm's manifest.json / board.json / contracts/ / inbox/.

package/adapters/codex/commands/continue.md

@@ -0,0 +1,40 @@
+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 Codex. CLI: `momentum continue [--handoff <id>]`. SessionStart hook auto-greets pending handoffs. All three call `core/orchestration/continue.js`.
+
+## 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
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const block = await orchestration.continueHandoff.continueHandoff({
+  repo, handoffId, ecosystem,
+});
+```
+
+### Step 2 — Act on the block
+
+Narrate summary, decisions, files, verification commands, open questions. Proceed with the work.
+
+### Step 3 — Don't surprise the user
+
+Large blocks → summarise + offer "want me to read the full block?".
+
+## Tracking contract
+
+- Auto: inbox file → `read/` + `[NOTE]` in receiving active phase history.
+
+## Errors
+
+- No pending → "no pending handoffs in this repo" (not an error).
+- Specified id not found → error with list of pending ids.
+- Malformed inbox → error pointing at the file.

package/adapters/codex/commands/dispatch.md

@@ -0,0 +1,111 @@
+Parallel multi-repo fan-out + synthesis. One sub-agent per listed repo with auto-tailored prompts; all results synthesised into a single answer to the user's high-level intent. Writes one dispatch-NNN.md artifact and one session log line.
+
+> **Three doors, one library.** This is the slash-command door for Codex. The CLI door is `momentum dispatch <r1> <r2> ... --prompt "<text>"` and the natural-language inference door fires when the user describes a multi-repo audit / alignment task. All three doors call `core/orchestration/dispatch.js` so the output shape is identical.
+
+## When to use
+
+- "What breaks if I rename X across all repos?" — multi-repo audit.
+- "Get me the current state of A AND B so I can align a change." — pre-coordination context fetch.
+- "Where does Y come from across the stack?" — cross-cutting investigation.
+
+## Inference guidance
+
+Treat ANY of these as a dispatch invocation:
+
+- "Audit X across repos A, B, C."
+- "What's the state of A, B, and C right now?"
+- "Find every place that does X across the ecosystem."
+
+When inferring, narrate `▸ inferred: dispatch (multi-repo audit). Use /dispatch next time for predictable behavior.`
+
+## Usage
+
+```
+/dispatch <repo1> <repo2> [repo3 ...] "<user intent>"
+```
+
+## Capability-routing note
+
+Codex declares `parallelSubagents: false` in `core/adapter-capabilities.md` pending live validation of parallel subagent fan-out. The capability-routing helper will return `mode='sequential'` for Codex; surface the note up front:
+
+```
+▸ note: this adapter does not declare parallel subagents — running sequentially (Promote to true once dispatch parallel mode is exercised against Codex in CI.)
+```
+
+In sequential mode, run sub-agents ONE AT A TIME via Codex's subagent surface. Output shape stays identical to parallel mode — just slower.
+
+## Steps
+
+### Step 1 — Identify the targets + intent
+
+Resolve each repo arg via `ecosystem.json`.
+
+### Step 2 — Capability-route the dispatch mode
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const adapter = orchestration.capabilityRouting.loadAdapter('<momentum-root>', 'codex');
+const { mode, notes } = orchestration.capabilityRouting.chooseMode(adapter, 'dispatch');
+```
+
+Surface each note via `▸ note: <text>` BEFORE starting sub-agents.
+
+### Step 3 — Fan out (sequential on Codex today)
+
+For EACH target repo, invoke a Codex sub-agent with:
+
+- System prompt: "You are a DISPATCH SUB-AGENT for momentum's quick-verb layer. The user intent is authoritative — if it asks to audit / investigate / report, stay read-only. If it asks to fix / refactor / migrate, you may write code, but commit on a feature branch per Rule 6 and surface the branch name. Return a JSON result with summary, filesRead, optional filesWritten + branch, findings (Rule-3 thresholds)."
+- Task prompt: user intent + the specific repo.
+
+Capture failures in `failures[]`; never abort the whole dispatch.
+
+### Step 4 — Synthesise
+
+Read all per-repo results IN THIS AGENT'S CONTEXT and produce a synthesis paragraph that DIRECTLY ANSWERS the user's intent.
+
+### Step 5 — Record the run + tracking-contract hand-off
+
+```js
+orchestration.dispatch.record({
+  repos, userIntent, mode, modeNotes: notes,
+  perRepoResults, failures, synthesis,
+  originatingRepo, ecosystem, duration,
+});
+```
+
+Then for each finding:
+
+```js
+orchestration.tracking.proposeDiscovery({ primitive: 'dispatch', finding, targetRepo });
+```
+
+Synthesis-level note:
+
+```js
+orchestration.tracking.proposeHistoryNote({
+  primitive: 'dispatch',
+  originatingRepo,
+  message: '<one-line summary>',
+  runArtifactRef: '<.momentum/runs/dispatch-NNN.md>',
+});
+```
+
+### Step 6 — Render
+
+```
+▸ Synthesis
+<paragraph>
+
+▸ Per-repo
+  ▼ <repo1>: <one-line>
+  ▼ <repo2>: <one-line>
+
+→ logged to sessions/<today>.md
+→ trace at .momentum/runs/dispatch-NNN.md
+```
+
+## Tracking contract
+
+- Auto: session log line + dispatch-NNN.md.
+- Auto if meaningful: per-repo `[DISCOVERY]` + originating `[NOTE]`.
+- Never: `[DISPATCH]` entry types; `backlog.md` without confirmation.

package/adapters/codex/commands/handoff.md

@@ -0,0 +1,57 @@
+Cross-session control transfer with a structured context block. Writes `<toRepo>/.momentum/inbox/handoff-NNN.md` so a fresh agent session in that repo can pick up where you left off, and emits a `[DECISION]` in this repo's active phase history.
+
+> **Three doors, one library.** This is the slash-command door for Codex. The CLI door is `momentum handoff <repo>`; natural-language inference fires when the user describes a control transfer. All three doors call `core/orchestration/handoff.js`.
+
+## When to use
+
+- You finished work in repo A and want the next Codex session in repo B to continue with full context.
+- You hit a stopping point that requires switching repos and want decisions preserved.
+
+## Usage
+
+```
+/handoff <repo> [optional one-line summary]
+```
+
+## Steps
+
+### Step 1 — Identify the target
+
+Resolve `<repo>` via `ecosystem.json`.
+
+### Step 2 — Collect the context block
+
+Pull from this session:
+- decisions made
+- files touched
+- verification commands the receiving agent should run
+- open questions
+
+### Step 3 — Write the handoff
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const block = await orchestration.handoff.handoff({
+  fromRepo, toRepo, summary,
+  decisions, filesTouched, verificationCommands, openQuestions,
+  ecosystem,
+});
+```
+
+This writes `<toRepo>/.momentum/inbox/handoff-NNN.md`, appends one line to the ecosystem session log, AND emits a `[DECISION]` in this repo's active phase `history.md`.
+
+### Step 4 — Tell the user
+
+```
+▸ handoff written: <toRepo>/.momentum/inbox/handoff-NNN.md
+▸ logged [DECISION] in <originating phase>/history.md
+
+Next: open a fresh Codex session in <toRepo>. The SessionStart hook
+will detect the handoff and prompt. Or run `/continue` (or
+`momentum continue`) explicitly.
+```
+
+## Tracking contract
+
+- Auto: session log + inbox file + originating `[DECISION]`.
+- Never: `[HANDOFF]` entry type. Use `[DECISION]`.

package/adapters/codex/commands/scout.md

@@ -0,0 +1,90 @@
+Read-only context fetch from one ecosystem member repo. Returns a structured summary, writes a scout-NNN.md run artifact, and appends one line to the ecosystem session log.
+
+> **Three doors, one library.** This is the slash-command door for Codex. The CLI door is `momentum scout <repo> "<prompt>"` and the natural-language inference door fires when the user describes a single-repo, read-only context-fetch task without naming a primitive. All three doors call `core/orchestration/scout.js` so the output shape is identical.
+
+## When to use
+
+- You're about to make a change in this repo but you need to know the current state of a related repo first (auth shape, API contract, schema, recent decisions).
+- A user asks "what's the situation in `<repo>`?" — that's scout.
+- You want a durable record of a context-fetch you just did, not just a chat message.
+
+## Inference guidance (read this in non-slash contexts too)
+
+Treat ANY of these as a scout invocation even without an explicit `/scout`:
+
+- "What's the current X in repo Y?"
+- "Before I make the change here, get me the latest state from `<sibling repo>`."
+- "Read repo Y and tell me about its current Z."
+
+When inferring, narrate it: `▸ inferred: scout (single repo, read-only). Use /scout next time for predictable behavior.`
+
+Do NOT use scout for multi-repo questions — use `/dispatch`. Do NOT use scout when you're about to write into the target repo — use `/handoff`.
+
+## Usage
+
+```
+/scout <repo> "<prompt>"
+```
+
+`<repo>` is either a member id from `ecosystem.json` or a relative/absolute path. `<prompt>` is the user's question.
+
+## Steps
+
+### Step 1 — Identify the target repo + prompt
+
+Parse the user's invocation and resolve `<repo>` to an absolute path via the ecosystem manifest (`ecosystem.json` → `members[]`).
+
+### Step 2 — Read the target repo in-process
+
+Codex's `parallelSubagents` is currently declared `false` in `core/adapter-capabilities.md` (pending live validation). For a single-repo read-only task this is irrelevant — scout is naturally a single sub-agent. Use Codex's sub-agent surface to:
+
+1. Read `specs/status.md` and recent files under `specs/architecture/` and `specs/phases/<active>/history.md`.
+2. Read any keyword-matching files.
+3. NO writes. Read-only is the contract.
+4. Return a structured result with `summary`, `filesRead`, `findings` (each finding meeting Rule 3 criteria for `[DISCOVERY]` tracking).
+
+### Step 3 — Record the run
+
+Once the sub-agent returns, call into the orchestration library:
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const result = orchestration.scout.record({
+  repo: '<resolved repo path>',
+  prompt: '<user prompt>',
+  summary: '<sub-agent summary>',
+  filesRead: [/* ... */],
+  findings: [/* ... */],
+  ecosystem: { rootPath: '<ecosystem root>', memberId: '<this repo member id>' },
+  duration: <ms>,
+});
+```
+
+This writes `.momentum/runs/scout-NNN.md` in THIS repo (originating) and appends one line to the ecosystem session log.
+
+### Step 4 — Hand findings to the tracking contract
+
+```js
+orchestration.tracking.proposeDiscovery({
+  primitive: 'scout',
+  finding,
+  targetRepo: '<scouted repo path>',
+});
+```
+
+The helper applies Rule 3 criteria; only meaningful findings land in the scouted repo's active phase `history.md` as `[DISCOVERY]`. NEVER use a `[SCOUT]` marker.
+
+### Step 5 — Narrate the result
+
+Print the summary, the artifact path, and the session log reference.
+
+## Tracking contract
+
+- **Auto every time:** ecosystem session log line + scout-NNN.md artifact in THIS repo.
+- **Auto only when meaningful:** `[DISCOVERY]` in scouted repo's active phase history.
+- **Never:** `backlog.md` entries without explicit user confirmation.
+
+## Errors
+
+- Repo not found in ecosystem manifest → report and stop.
+- Repo not in any ecosystem → fall back to running scout in-process via CLI; suggest `momentum scout <path> "<prompt>"`.