@limina-labs/momentum 0.30.2

package/adapters/antigravity/instructions/surfaces.md

@@ -0,0 +1,153 @@
+## Antigravity-native layout under `.agents/`
+
+Momentum installs every Antigravity-discoverable asset under the ONE
+canonical customization root, `.agents/`, at the project root (ADR-0006;
+Antigravity accepts four root spellings, and `.agents/` is the one all
+vendor examples and reference docs use):
+
+| Path | Purpose |
+|---|---|
+| `.agents/workflows/` | Step-by-step workflow recipes — each `<name>.md` auto-registers as `/<name>` slash command. Includes all momentum phase + orchestration commands. |
+| `.agents/engines/` | Execution engines (subagent dispatch playbook). |
+| `.agents/skills/` | On-demand persona/capability skills — each `<name>/SKILL.md` is discovered by name+description and loads on activation. Momentum ships `momentum-orient` + three reviewers + `swarm-supervisor`. |
+| `.agents/hooks.json` | Lifecycle hooks (five events: PreToolUse, PostToolUse, PreInvocation, PostInvocation, Stop). |
+
+## Workflows = momentum recipes (native slash commands)
+
+When the user types `/<name>` (e.g. `/brainstorm-phase`, `/start-phase`,
+`/sync-docs`, `/complete-phase`, `/dispatch`, `/handoff`, `/continue`,
+`/review-code`), `agy` reads the matching workflow file from
+`.agents/workflows/<name>.md` and follows its numbered steps.
+
+Workflows ship in two layers:
+
+1. **Core workflows** — momentum's cross-adapter phase + ecosystem commands. Installed from `core/commands/*.md` to `.agentss/workflows/*.md`. Examples: `brainstorm-phase`, `start-phase`, `sync-docs`, `complete-phase`, `track`, `validate`, `ecosystem`, `initiative`, `session`, `systematic-debug`.
+2. **Antigravity-specific workflows** — orchestration primitives with native parallel subagent fan-out. Installed from `adapters/antigravity/workflows/*.md`. Examples: `scout`, `dispatch`, `handoff`, `continue`, `review-code`.
+
+To add a project-specific workflow, drop a Markdown file into
+`.agents/workflows/<name>.md` with YAML frontmatter:
+
+```markdown
+---
+description: One-line summary used for auto-detection
+---
+
+### 1. First step
+...
+
+### 2. Second step
+...
+```
+
+Max 12,000 characters per workflow file. Use `// run workflow: <name>`
+to compose workflows.
+
+## Skills = personas the agent loads to BECOME
+
+Momentum installs five skills at `.agents/skills/`:
+
+- **`momentum-orient`** — Read `specs/status.md` first. Codifies Rule 1.
+- **`momentum-reviewer-security`** — OWASP/STRIDE security review persona.
+- **`momentum-reviewer-qa`** — Test coverage / edge cases / regression risk.
+- **`momentum-reviewer-architecture`** — Rule compliance / pattern consistency.
+- **`swarm-supervisor`** — Phase 18 / v0.20.4. Per-repo supervisor persona spawned by `/swarm start`. Drives one repo's phase to completion under a pinned cwd. See `## Swarm — Lookup Pattern` below.
+
+The three reviewer skills are loaded by the `/review-code` workflow,
+which dispatches them in parallel via Antigravity's native subagent
+fan-out, then consolidates findings. The swarm-supervisor skill is
+loaded by each Wave-N supervisor on spawn; it is not invoked directly
+by the user.
+
+Add project-specific skills under `.agents/skills/<name>/SKILL.md` with
+YAML frontmatter (`name`, `description`).
+
+## Swarm — Lookup Pattern
+
+> Phase 18 / v0.20.4 — Antigravity parity of the Phase 17 + 17.5
+> swarm primitive.
+
+Momentum's swarm primitive — sustained parallel multi-project feature
+delivery — ships on Antigravity as of v0.20.4. The user-facing
+workflow lives at `.agents/workflows/swarm.md`; `agy` auto-registers it
+as `/swarm`. The per-repo supervisor persona lives at
+`.agents/skills/swarm-supervisor/SKILL.md`.
+
+The CLI floor is `momentum swarm <sub> [args]`. The slash command and
+the CLI produce the same on-disk artifacts.
+
+| Subcommand | What it does |
+|---|---|
+| `start` | Plan + spawn Wave 1. Presents wave plan for approval before any spawn. |
+| `status` | Render the materialized board cache. Read-only. |
+| `tell` | Push a one-shot context note to one supervisor (`swarm-context.md`). |
+| `broadcast` | Push context to every supervisor in the swarm. |
+| `verify` | Contract verifier + manifest+brief drift check. |
+| `complete` | Synthesize the cross-repo changeset and finalize the swarm. |
+| `resume` | Re-attach this session to a swarm; renews owned leases. |
+| `cancel` | Graceful halt; preserves all artifacts for forensics. |
+| `budget` | Adjust a per-repo token budget. |
+| `claim` | Multi-session ownership primitive (Phase 17.5). |
+| `release` | Release ownership; idempotent. |
+| `focus` | Issue a single-use focus token to hand a repo to a side session. |
+| `join` | Register a second session as co-conductor; optionally consume a token. |
+| `absorb` | Converge two swarms back into one (forensic-preserving). |
+| `inbox` | Supervisor → conductor questions (`list` / `write` / `resolve`). |
+| `preview-merge` | Dry-run `git merge --no-commit` per supervisor branch. |
+
+**Spawn dispatch**: the conductor (this user session) dispatches spawns
+through `adapters/antigravity/adapter.js::spawn(directive)` — which
+shells `agy` with the supervisor skill as the persona and the
+directive's `repoPath` as the cwd. Each supervisor BECOMES the
+`swarm-supervisor` skill on boot.
+
+**`agy` not on PATH**: `momentum swarm start --spawn` degrades to
+dry-run and prints spawn directives the user can launch manually.
+
+## Plugins — global momentum skills (opt-in)
+
+Antigravity plugins bundle skills into one namespaced, enable/disable-able
+unit (`plugins/<name>/plugin.json` + `skills/`). Momentum can pack its five
+skills as a native plugin:
+
+```bash
+momentum antigravity plugin-pack            # → .agents/plugins/momentum/ (this project)
+momentum antigravity plugin-pack --global   # → ~/.gemini/config/plugins/momentum/ (all workspaces)
+```
+
+The `--global` form is the explicit opt-in way to make momentum's skills
+available in every Antigravity workspace on this machine; a per-project
+momentum install always takes priority (workspace beats global in the
+discovery order). Hooks are deliberately not packed — they are
+project-relative and ship via `momentum init`/`upgrade` only. Momentum never
+installs the `agy` binary itself; `momentum doctor` points at the official
+installer when it is missing.
+
+## Antigravity Native Artifacts Integration
+
+When in planning mode or executing a phase, keep Antigravity's native artifacts in sync with momentum's spec files:
+
+- **Durable Checklist**: Map `specs/phases/phase-N-*/tasks.md` directly into your native `task.md` artifact. Update both simultaneously as work proceeds.
+- **Implementation Alignment**: Ensure that the `implementation_plan.md` artifact mirrors the scope and groups declared in `specs/phases/phase-N-*/plan.md`.
+- **Walkthrough Evidence**: Append the verification evidence gathered for `/complete-phase` into your native `walkthrough.md` artifact.
+
+## Hooks
+
+Antigravity hook wiring lives in `.agents/hooks.json` (named-group schema,
+five lifecycle events — there is NO SessionStart event on Antigravity).
+Hook commands run with CWD = `.agents/`, so momentum wires them through the
+boundary shim `scripts/antigravity-hook-adapter.sh` (ADR-0006), which
+translates Antigravity's camelCase payloads and response contract and
+delegates to the same shared scripts every adapter uses:
+
+| Named hook | Event | Matcher | Behavior |
+|---|---|---|---|
+| `momentum-brainstorm-gate` | `PreToolUse` | `write_to_file\|run_command\|.*write.*\|.*edit.*\|.*replace.*` | Blocks writes to `specs/` while a `/brainstorm-*` session is active (sentinel `.momentum/brainstorm-active`) — responds `{"decision":"deny","reason":…}`. |
+| `momentum-history-reminder` | `PostToolUse` | same write-family matcher | Runs `check-history-reminder.sh`; reminders are QUEUED (PostToolUse has no message channel) and injected on the next model invocation (Rule 8). |
+| `momentum-session-context` | `PreInvocation` | (flat — no matcher) | At `invocationNum 0`, runs `sessionstart-handoff.sh` and injects the pending-handoff banner + ecosystem context as an `ephemeralMessage`; every invocation also drains queued reminders. |
+
+### Session-start fallback
+
+Injection depends on the vendor hook runner. The handoff pickup hint also
+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.

package/adapters/antigravity/instructions/vars.json

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

package/adapters/antigravity/scripts/antigravity-hook-adapter.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# antigravity-hook-adapter.sh — Antigravity 2.x payload/response boundary shim.
+#
+# Phase 22b (ADR-0006). Antigravity's hook contract differs from Claude
+# Code/Codex in payload shape (camelCase protojson, toolCall.args.*), response
+# channel (stdout decision JSON, ALWAYS exit 0), hook CWD (the directory
+# containing hooks.json — i.e. .agents/), and event set (five events, no
+# SessionStart; PreInvocation injectSteps is the session-start mechanism).
+# Contract source: specs/phases/phase-22b-antigravity-2-adoption/evidence/
+# fact-sheet.md §5 (locked live against agy 1.0.16).
+#
+# This shim translates at the boundary and delegates to the shared core
+# scripts UNCHANGED, so Claude Code + Codex behavior stays byte-identical:
+#
+#   pre-tool        → brainstorm-gate.sh        exit 2/stderr → {"decision":"deny",...}
+#   post-tool       → check-history-reminder.sh stdout → queued (PostToolUse
+#                     has no message channel), respond {}
+#   pre-invocation  → sessionstart-handoff.sh at invocationNum 0 + drain the
+#                     queue → {"injectSteps":[{"ephemeralMessage": ...}]}
+#
+# Every failure path fails OPEN (allow / {}), and the script always exits 0 —
+# non-zero is treated as hook infrastructure failure by the vendor runner.
+
+set -u
+
+MODE="${1:-}"
+INPUT=$(cat 2>/dev/null || true)
+
+respond_neutral() {
+  case "$MODE" in
+    pre-tool) printf '{"decision":"allow"}' ;;
+    *)        printf '{}' ;;
+  esac
+  exit 0
+}
+
+[ -n "$MODE" ] || respond_neutral
+command -v python3 >/dev/null 2>&1 || respond_neutral
+
+# ── Parse the camelCase payload once ────────────────────────────────────────
+eval "$(printf '%s' "$INPUT" | python3 -c '
+import sys, json, shlex
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    d = {}
+ws = (d.get("workspacePaths") or [""])[0] or ""
+tc = d.get("toolCall") or {}
+args = tc.get("args") or {}
+path = args.get("TargetFile") or args.get("AbsolutePath") or args.get("FilePath") or ""
+cmd = args.get("CommandLine") or ""
+print("AG_ROOT=%s" % shlex.quote(ws))
+print("AG_TOOL=%s" % shlex.quote(tc.get("name") or ""))
+print("AG_PATH=%s" % shlex.quote(path))
+print("AG_CMD=%s" % shlex.quote(cmd))
+print("AG_INVOCATION=%s" % shlex.quote(str(d.get("invocationNum", ""))))
+' 2>/dev/null)" 2>/dev/null || respond_neutral
+
+# Hook CWD is .agents/ — fall back to its parent when the payload lacks
+# workspacePaths (fail-open if neither resolves to a directory).
+if [ -z "${AG_ROOT:-}" ] || [ ! -d "${AG_ROOT:-}" ]; then
+  AG_ROOT=$(cd .. 2>/dev/null && pwd || true)
+fi
+[ -n "${AG_ROOT:-}" ] && [ -d "$AG_ROOT" ] || respond_neutral
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+NOTICES="$AG_ROOT/.momentum/antigravity-notices"
+
+# Relativize the tool path against the project root — the shared scripts
+# match relative patterns like specs/status.md.
+rel_path="${AG_PATH:-}"
+case "$rel_path" in
+  "$AG_ROOT"/*) rel_path="${rel_path#"$AG_ROOT"/}" ;;
+esac
+
+# Legacy-shape payload for the shared scripts. run_command maps to Bash so
+# the reminder script's session-append branch (git commit detection) works.
+legacy_payload() {
+  python3 -c '
+import json, sys
+tool, path, cmd = sys.argv[1], sys.argv[2], sys.argv[3]
+if tool == "run_command":
+    tool = "Bash"
+elif tool and any(k in tool for k in ("write", "edit", "replace")):
+    # Normalize the whole Antigravity write-tool family to the canonical
+    # name the shared scripts already match — keeps core scripts untouched
+    # (byte-identical for Claude Code/Codex, ADR-0006).
+    tool = "write_to_file"
+ti = {}
+if path:
+    ti["file_path"] = path
+if cmd:
+    ti["command"] = cmd
+print(json.dumps({"tool_name": tool, "tool_input": ti}))
+' "${AG_TOOL:-}" "$rel_path" "${AG_CMD:-}"
+}
+
+case "$MODE" in
+  pre-tool)
+    err=$( { legacy_payload | MOMENTUM_PROJECT_DIR="$AG_ROOT" \
+        bash "$SCRIPT_DIR/brainstorm-gate.sh" >/dev/null; } 2>&1 )
+    rc=$?
+    if [ "$rc" -eq 2 ]; then
+      printf '%s' "$err" | python3 -c \
+        'import json,sys; print(json.dumps({"decision":"deny","reason":sys.stdin.read()[:1000]}))'
+    else
+      printf '{"decision":"allow"}'
+    fi
+    ;;
+
+  post-tool)
+    out=$( { legacy_payload | ( cd "$AG_ROOT" && \
+        bash "$SCRIPT_DIR/check-history-reminder.sh" ); } 2>/dev/null || true )
+    if [ -n "$out" ]; then
+      mkdir -p "$AG_ROOT/.momentum" 2>/dev/null || true
+      printf '%s\n' "$out" >> "$NOTICES" 2>/dev/null || true
+    fi
+    printf '{}'
+    ;;
+
+  pre-invocation)
+    banner=""
+    if [ "${AG_INVOCATION:-}" = "0" ]; then
+      # Banner mode: non-TTY stdin → the handoff script prints to stderr and
+      # exits 0 without the interactive prompt.
+      banner=$( ( cd "$AG_ROOT" && \
+        bash "$SCRIPT_DIR/sessionstart-handoff.sh" </dev/null ) 2>&1 >/dev/null || true )
+    fi
+    notices=""
+    if [ -s "$NOTICES" ]; then
+      notices=$(cat "$NOTICES" 2>/dev/null || true)
+      : > "$NOTICES" 2>/dev/null || true
+    fi
+    python3 -c '
+import json, sys
+banner, notices = sys.argv[1], sys.argv[2]
+msg = "\n".join(x for x in (banner.strip(), notices.strip()) if x)
+print(json.dumps({"injectSteps": [{"ephemeralMessage": msg}]}) if msg else "{}")
+' "$banner" "$notices"
+    ;;
+
+  *)
+    respond_neutral
+    ;;
+esac
+
+exit 0

package/adapters/antigravity/skills/momentum-orient/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: momentum-orient
+description: Read specs/status.md before starting any work in a momentum-managed project. Activates at the start of every new task to ensure the agent has current phase context. Codifies Rule 1 (Orient First).
+---
+
+# momentum-orient
+
+When this skill activates (at session start or when the user asks you to
+work on something new), read these files in order before any other action:
+
+1. `specs/status.md` — current phase, blockers, P0 items, next actions
+2. `specs/backlog/backlog.md` — P0/P1 items that may block the current task
+3. `specs/phases/<active-phase>/tasks.md` — what's done / in flight / blocked
+4. `AGENTS.md` — project rules and constraints (the complete rulebook)
+
+Then proceed with the user's request, framing any output in terms of:
+- which phase is active
+- whether the requested work belongs in the active phase or is a side track
+- any existing tasks or history entries that already cover the request
+
+This skill is shipped by the momentum toolkit. It codifies Rule 1 (Orient
+First) from the project rules. See `AGENTS.md` for the full set of rules.
+
+## When NOT to apply this skill
+
+- If the user's message is purely conversational ("what is X?") and doesn't
+  require touching the codebase, you don't need to orient.
+- If you've already oriented this session and nothing on disk has changed
+  since, don't re-orient.

package/adapters/antigravity/skills/momentum-reviewer-architecture/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: momentum-reviewer-architecture
+description: Review a code diff for architectural fit, rule compliance, and pattern consistency. Returns Critical/Important/Minor findings only — does not modify code, does not refactor. Loaded by the review-code workflow alongside the security and QA reviewers.
+---
+
+# momentum-reviewer-architecture
+
+You are an architecture-focused code reviewer dispatched by the momentum
+toolkit. You will receive a code diff and the project's full rules
+(AGENTS.md — the complete rulebook).
+
+**YOUR LENS**: architectural fit, rule compliance, pattern consistency.
+
+## What to ask for each change
+
+- Does it violate any of the 12 autonomous rules (orient first, update tracking, auto-track discoveries, pre-phase bug check, phase boundary awareness, git lifecycle, plan before implementing, record history, doc sync protocol, architecture stability, evaluator discipline, verify before claim)?
+- Does it match the patterns established elsewhere in the codebase? Read 2-3 nearby files for convention.
+- Does it create hidden coupling, a leaky abstraction, or an adapter/contract violation? (For momentum specifically: every capability declaration uniform-boolean; overlay subdirs use the destinations contract; adapter-specific code stays in adapters/, generic in core/.)
+- Is it documented where rules say it should be (history.md entry, ADR for decisional changes, backlog entry for discovered issues)?
+- Does the commit message convention match (feat / fix / docs / etc.)?
+
+## Output format — return EXACTLY this structure
+
+```
+## Architecture 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 refactor yourself — flag the issue.
+Do NOT modify any files.

package/adapters/antigravity/skills/momentum-reviewer-qa/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: momentum-reviewer-qa
+description: Review a code diff for test coverage, edge cases, and regression risk. Returns Critical/Important/Minor findings only — does not modify code, does not write tests. Loaded by the review-code workflow alongside the security and architecture reviewers.
+---
+
+# momentum-reviewer-qa
+
+You are a QA-focused code reviewer dispatched by the momentum toolkit.
+You will receive a code diff and a project-rules excerpt (especially
+Rule 12 — Verify Before Claim).
+
+**YOUR LENS**: test coverage, edge cases, regression risk.
+
+## What to ask for each meaningful behavior change
+
+- Is there a test that exercises it? If yes, does it test the happy path AND at least one edge case?
+- What edge cases are uncovered? Consider: empty input, large input, concurrent access, error paths, network/IO failures, malformed data, Unicode / non-ASCII, very long strings, off-by-one boundaries.
+- Could this change break an existing test or production path? Look for callers of any modified function.
+- Does the change add a verification command, or rely on "should work now" — Rule 12 territory.
+
+## Output format — return EXACTLY this structure
+
+```
+## QA 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 write tests yourself — flag the gap.
+Do NOT modify any files.

package/adapters/antigravity/skills/momentum-reviewer-security/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: momentum-reviewer-security
+description: Review a code diff through a security lens (OWASP Top 10, STRIDE threat categories). Returns Critical/Important/Minor findings only — does not modify code, does not propose fixes. Loaded by the review-code workflow alongside the QA and architecture reviewers.
+---
+
+# momentum-reviewer-security
+
+You are a security-focused code reviewer dispatched by the momentum
+toolkit. You will receive a code diff and a project-rules excerpt.
+
+**YOUR LENS**: OWASP Top 10 + STRIDE threat categories.
+
+## What to look for
+
+- Hard-coded secrets, credentials, API keys
+- SQL/NoSQL injection vectors, unparameterized queries
+- XSS / SSRF / CSRF surfaces in any user-controlled input path
+- Authentication / authorization gaps in newly added endpoints
+- Insecure deserialization, prototype pollution
+- Logging of sensitive data (PII, tokens)
+- Race conditions / TOCTOU in security-relevant code paths
+- Cryptographic anti-patterns (weak algorithms, fixed IVs, MD5/SHA1 for security, broken random sources)
+- Dependency additions of known-vulnerable packages
+
+## Output format — return EXACTLY this structure
+
+```
+## 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 — flag only.
+Do NOT modify any files. Do NOT run any code-modifying commands.

package/adapters/antigravity/skills/swarm-supervisor/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: swarm-supervisor
+description: Drive a single repo through its phase as part of a swarm. Activates when spawned by the conductor (the user's primary session) with a spawn directive. State lives in files; the conductor reads board.json between turns. Loads on the swarm-supervisor invocation only — not invoked directly by the user.
+---
+
+# swarm-supervisor
+
+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
+   a workflow at `.agents/workflows/<name>.md` — 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:
+
+    ```bash
+    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 workflow; the supervisor finishes after the phase is
+  verified and pushed.
+
+## Native artifacts integration
+
+While supervising, keep Antigravity's native artifacts in sync with
+momentum's spec files (same contract as standalone phase work):
+
+- **Durable Checklist**: Map `specs/phases/phase-N-*/tasks.md` into
+  your native `task.md` artifact. Update both simultaneously.
+- **Implementation Alignment**: Mirror `specs/phases/phase-N-*/plan.md`
+  into `implementation_plan.md`.
+- **Walkthrough Evidence**: Append `/complete-phase` verification
+  evidence to `walkthrough.md`.
+
+## You are NOT the conductor
+
+You do not own `<eco>/swarms/<id>/manifest.json`, `board.json`,
+`contracts/`, or `inbox/INDEX.md`. The conductor session owns those
+files. You own:
+
+- `specs/phases/phase-N-<slug>/*` (your phase scope inside this repo)
+- `.momentum/runs/dispatch-run-<id>.json` (your status emitter)
+
+You inherit every always-on rule from `AGENTS.md` (the complete rulebook).

package/adapters/antigravity/workflows/continue.md

@@ -0,0 +1,39 @@
+---
+description: Pick up a pending handoff in this repo. Reads .momentum/inbox/handoff-NNN.md, parses the structured context, acknowledges, moves the artifact to inbox/read/. Use when the user mentions a handoff or when the SessionStart hook indicates one is pending.
+---
+
+# continue
+
+### 1. Find the handoff
+
+List files in `.momentum/inbox/` matching `handoff-*.md`. If none, tell the user "no pending handoff" and stop.
+
+If multiple, pick the oldest (lowest N) unless the user named a specific one.
+
+### 2. Read and parse
+
+Read the chosen handoff file. Extract:
+
+- **From**: source repo
+- **Why**: the handoff reason
+- **State at handoff**: phase + last action
+- **What's next**: first action to take
+- **References**: files to read first
+
+### 3. Acknowledge to user
+
+Print a one-line acknowledgement: `picking up handoff-NNN from <source>` followed by the "What's next" content. Read the referenced files before proceeding.
+
+### 4. Move the artifact
+
+Move the file from `.momentum/inbox/handoff-NNN.md` to `.momentum/inbox/read/handoff-NNN.md` so the next session doesn't re-pick-up the same handoff. Create the `read/` subdir if missing.
+
+### 5. Proceed with the work
+
+Continue with the action described in "What's next". Honor the project's Rule 1 — read `specs/status.md` before any work, even after a handoff.
+
+## Constraints
+
+- Never delete a handoff — move to `read/` for audit history.
+- If the handoff references files that don't exist, surface the gap to the user; don't silently proceed.
+- If the source repo's "What's next" conflicts with the active phase here, ask the user before acting.

package/adapters/antigravity/workflows/dispatch.md

@@ -0,0 +1,49 @@
+---
+description: Parallel multi-repo fan-out + synthesis. Spawns one subagent per listed repo with auto-tailored prompts, waits for all, synthesizes their findings into a single consolidated report. Use for cross-repo investigations or audits.
+---
+
+# dispatch
+
+### 1. Resolve targets and the dispatch prompt
+
+Identify the list of target ecosystem members (member ids or `--all` for every member) and the dispatch prompt from the user's input. If either is missing, ask for it and stop until they answer.
+
+### 2. Tailor the prompt per target
+
+For each target, build a per-repo prompt that:
+
+- States the dispatch question explicitly
+- Tells the subagent to read `specs/status.md` + relevant rules first
+- Asks for a structured response: findings, blockers, recommended action
+- Names the repo so the subagent knows its context
+
+### 3. Fan out subagents in parallel
+
+Use Antigravity's native parallel subagent capability to spawn one subagent per target in a single turn. Each subagent receives its tailored prompt and the target repo path as the working directory.
+
+### 4. Wait + collect
+
+Wait until all subagents return. If any subagent errors or times out, record the failure but do not block the synthesis on the survivors.
+
+### 5. Synthesize
+
+Produce a single consolidated report with these sections:
+
+- **Mode**: parallel (N targets)
+- **Findings**: per-target structured summary, with consistent fields per repo
+- **Cross-cutting patterns**: themes that appeared in ≥2 targets
+- **Recommended next action**: 1–3 concrete proposals, ranked
+
+### 6. Write the dispatch artifact
+
+Append the full synthesis to `.momentum/runs/dispatch-<NNN>.md` so the result is durable across sessions.
+
+### 7. Return to user
+
+Present the synthesis. Note any subagent failures explicitly. If the user wants to act on a finding, route them to `/initiative create` (for cross-repo work) or to file a per-repo backlog item.
+
+## Constraints
+
+- Subagents are dispatched in PARALLEL, not sequentially.
+- If only one target is given, suggest `/scout` instead and ask the user to confirm.
+- Synthesis must clearly attribute findings to source repos (one repo can't speak for the others).

package/adapters/antigravity/workflows/handoff.md

@@ -0,0 +1,38 @@
+---
+description: Cross-session control transfer with a structured context block. Writes a handoff artifact to the target repo's .momentum/inbox/ so the receiving session can pick up where this one left off. Use when the work must continue in a different repo or after a session boundary.
+---
+
+# handoff
+
+### 1. Resolve target
+
+Identify the target repo (ecosystem member id or path) and the handoff summary from the user's input. The summary should be 1–3 sentences describing what the receiver should continue.
+
+### 2. Build the context block
+
+Compose a handoff message with these sections:
+
+- **From**: this repo id
+- **To**: target repo id
+- **Why**: 1–3 sentence summary (the user's input)
+- **State at handoff**: active phase, last meaningful action, any open decisions
+- **What's next**: what the receiver should do first
+- **References**: file paths the receiver should read first (status.md, the active phase tasks.md, any open initiative)
+
+### 3. Write the handoff artifact
+
+Write the composed handoff to `<target-repo>/.momentum/inbox/handoff-<NNN>.md` where N is the next sequential number. Create the inbox directory if missing.
+
+### 4. Log to session log
+
+Append a one-line entry to the ecosystem session log noting `handoff: from <source> → <target>` so cross-repo coordination is visible.
+
+### 5. Confirm to user
+
+Tell the user the handoff was written, name the artifact path, and remind them to acknowledge in the receiving session via `/continue`.
+
+## Constraints
+
+- Handoffs are write-once — never overwrite an existing `handoff-<NNN>.md`. Increment N.
+- The target repo's `.momentum/inbox/` must exist (create if missing).
+- A handoff is NOT a synchronous transfer — the receiver picks it up on next session start (via the SessionStart hook) or by explicit `/continue`.