@limina-labs/momentum 0.30.2

package/adapters/opencode/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 opencode. 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/opencode/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 opencode. 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
+
+opencode 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 opencode; surface the note up front:
+
+```
+▸ note: this adapter does not declare parallel subagents — running sequentially (Promote to true once dispatch parallel mode is exercised live against opencode (Phase 22 G5).)
+```
+
+In sequential mode, run sub-agents ONE AT A TIME via opencode's task tool. 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>', 'opencode');
+const { mode, notes } = orchestration.capabilityRouting.chooseMode(adapter, 'dispatch');
+```
+
+Surface each note via `▸ note: <text>` BEFORE starting sub-agents.
+
+### Step 3 — Fan out (sequential on opencode today)
+
+For EACH target repo, invoke an opencode subagent (task tool) 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/opencode/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 opencode. 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 opencode 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 opencode 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/opencode/commands/review-code.md

@@ -0,0 +1,194 @@
+Run a multi-perspective code review of the pending changes on the current branch.
+
+> **This is the opencode variant of review-code.** It uses the task tool to dispatch
+> role-based subagents (`.opencode/agents/momentum-reviewer-*`). Equivalent functionality for other agents
+> would live in their respective `adapters/<agent>/commands/` overlay (e.g.,
+> Cursor would ship a prompt-based variant). Do not generalize this into
+> `core/commands/` — generalization would lose the parallel-subagent value.
+
+## When to use
+
+- Before `/sync-docs` and `/complete-phase` at the end of a phase
+- After a non-trivial commit on a feature branch, before opening a PR
+- Whenever you want a fresh, independent read on what was just built
+
+This command does NOT modify code. It produces a consolidated review and asks
+you which findings to act on.
+
+## Steps
+
+### Step 1 — Determine review scope
+
+Default scope: the diff between the current branch and `main`. Run:
+```bash
+git diff main...HEAD --stat
+git diff main...HEAD
+```
+
+If the user passed an argument, honor it:
+- `staged` → `git diff --cached`
+- `working` → `git diff` (unstaged changes)
+- `<commit-sha>` → `git diff <commit-sha>...HEAD`
+- `<file-path>` → restrict review to that path within the default scope
+
+If no diff exists, report "no changes to review" and stop.
+
+### Step 2 — Read the rules of the project
+
+Before dispatching reviewers, read:
+- `AGENTS.md` (rules and constraints — the complete rulebook)
+- `specs/status.md` (current phase context)
+
+This ensures every reviewer scores the diff against THIS project's rules,
+not generic best practices alone.
+
+### Step 3 — Dispatch reviewers in parallel
+
+Use the task tool to spawn three subagents in **a single message with three
+parallel tool calls** (do NOT serialize). Each subagent gets the same diff
+and the same rules context, but a different role.
+
+#### Reviewer A — Security (OWASP / STRIDE)
+
+Prompt template:
+> You are reviewing a code diff for **security only**. Use the OWASP Top 10
+> and STRIDE threat categories as your lens.
+>
+> Diff:
+> ```
+> <paste the diff from Step 1>
+> ```
+>
+> Project rules excerpt:
+> ```
+> <paste the relevant constraints from AGENTS.md — especially "No secrets in code">
+> ```
+>
+> Return findings in this exact format:
+>
+> ```
+> ## Security review
+>
+> ### Critical
+> - [finding] (file:line) — [why it's critical]
+>
+> ### Important
+> - [finding] (file:line) — [explanation]
+>
+> ### Minor
+> - [finding] (file:line) — [explanation]
+> ```
+>
+> If no findings at a severity level, write "(none)". Do NOT speculate beyond
+> what the diff shows. Do NOT propose code fixes — only flag the issue.
+
+#### Reviewer B — QA (test coverage, edge cases, regressions)
+
+Prompt template:
+> You are reviewing a code diff for **test coverage and edge cases only**.
+>
+> Diff:
+> ```
+> <paste the diff from Step 1>
+> ```
+>
+> Project rules excerpt:
+> ```
+> <paste Rule 12 (Verify Before Claim) from AGENTS.md>
+> ```
+>
+> For each meaningful behavior change in the diff, ask:
+> - Is there a test that exercises it?
+> - What edge cases are uncovered (empty input, large input, concurrent
+>   access, error paths)?
+> - Could this break an existing test or production path?
+>
+> Return findings in the same Critical/Important/Minor format as the security
+> reviewer. "(none)" when applicable.
+
+#### Reviewer C — Architecture (rule compliance, pattern consistency)
+
+Prompt template:
+> You are reviewing a code diff for **architectural fit and rule compliance**.
+>
+> Diff:
+> ```
+> <paste the diff from Step 1>
+> ```
+>
+> Full rules:
+> ```
+> <paste AGENTS.md (rules section)>
+> ```
+>
+> For each change, ask:
+> - Does it violate any of the 12 autonomous rules?
+> - Does it match the patterns established elsewhere in the codebase?
+>   (Check 2-3 nearby files for convention.)
+> - Does it create a hidden coupling, a leaky abstraction, or an
+>   adapter/contract violation?
+> - Is it documented where rules say it should be (history.md, ADR, etc.)?
+>
+> Return findings in the Critical/Important/Minor format. "(none)" when
+> applicable.
+
+### Step 4 — Consolidate
+
+Once all three subagents return:
+
+1. Merge findings into a single report ordered:
+   ```
+   ## Code Review
+
+   ### Critical (N)
+   - [security] finding (file:line)
+   - [arch] finding (file:line)
+
+   ### Important (N)
+   - [qa] finding (file:line)
+   - [security] finding (file:line)
+
+   ### Minor (N)
+   - [arch] finding (file:line)
+   ```
+2. Tag each finding with its reviewer (`[security]`, `[qa]`, `[arch]`).
+3. De-duplicate findings that multiple reviewers raised — combine into one
+   line and tag with all reviewers (`[security][arch]`).
+4. If a finding is at Critical and conflicts with a Minor finding from a
+   different reviewer, surface BOTH and note the disagreement.
+
+### Step 5 — Present to user, ask what to act on
+
+Show the consolidated report. Then ask:
+> "Which findings should I act on now? Options:
+>   1. All Critical
+>   2. All Critical + Important
+>   3. Specific items (list IDs)
+>   4. None — log all findings to backlog only
+>   5. Cancel"
+
+For findings the user wants to act on now: implement them as separate commits
+on the current branch (each commit ≤ one finding).
+
+For findings the user wants to defer: add each as a backlog item via the
+`/track` flow with appropriate priority (Critical → P0/P1, Important → P1/P2,
+Minor → P2/P3).
+
+### Step 6 — Honor Rule 12 on any fixes
+
+If you implement any fix in Step 5, run the relevant verification (test,
+lint, typecheck) BEFORE marking it done — per Rule 12 (Verify Before Claim).
+
+## Constraints
+
+- Subagents are **read-only**: they MUST NOT edit files, run code-modifying
+  commands, or commit. They return findings as text only.
+- Dispatch all three subagents in a **single message with parallel tool
+  calls** — do not sequence them.
+- The review NEVER auto-fixes findings. The user always decides what to act
+  on (Step 5).
+- Findings tied to specific lines should include `file:line` so the user can
+  navigate quickly.
+- If a reviewer's output is malformed (missing severity headers), re-dispatch
+  that single reviewer with a stricter format reminder. Do not silently
+  reformat — that hides reviewer mistakes.

package/adapters/opencode/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 opencode. 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
+
+opencode'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 opencode's task tool (a subagent) 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>"`.