@massa-ai/cursor-plugin 1.29.0 → 1.30.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "massa-ai — semantic code search, memory, and context compression for Cursor"
 }

package/README.md

@@ -62,7 +62,7 @@ If you are building a VS Code extension for Cursor, you can register the plugin
 vscode.cursor.plugins.registerPath("/abs/path/to/apps/cursor-plugin");
 ```
 
-Cursor auto-discovers `skills/`, `hooks/hooks.json`, and `agents/` inside the registered directory. MCP is not bundled — Cursor reads `~/.cursor/mcp.json`, which `scripts/install-agents.sh` owns. The `.cursor-plugin/plugin.json` manifest is optional — Cursor discovers the subdirectories without it, but including one aids marketplace submission later.
+Cursor 3.14 loads user-local plugins from `~/.cursor/plugins/local/<name>/` and also bridges Claude marketplace plugins from `~/.claude`, but subagents are discovered only from the flat `~/.cursor/agents/*.md` (or project `.cursor/agents/`) directory — never from a plugin's `agents/` subtree. `install.sh` therefore copies the specialists to `~/.cursor/agents/`; `hooks/hooks.json` entries are merged into `~/.cursor/hooks.json` pointing at the installed hook binary. Cursor reads no global rules file: the AGENTS.md bootstrap must be pasted into Cursor Settings → Rules or provided per project root. MCP is not bundled — Cursor reads `~/.cursor/mcp.json`, which `scripts/install-agents.sh` owns. The `.cursor-plugin/plugin.json` manifest is optional — Cursor discovers the subdirectories without it, but including one aids marketplace submission later.
 
 Use `unregisterPath` to remove:
 

package/install.sh

@@ -11,8 +11,19 @@
 # MCP registration is delegated to scripts/install-agents.sh, the single writer
 # of host MCP config. This installer no longer ships a plugin-local mcp.json.
 #
+# Cursor 3.14 also bridges the Claude marketplace registry from ~/.claude and
+# loads any plugin listed there IN ADDITION to a local install — a machine
+# with both would load massa-ai twice and fire every hook twice (AD-017). At
+# USER scope, this installer prefers the bridge: when ~/.claude lists massa-ai
+# as installed and enabled, it skips its own local plugin copy and hook
+# wiring (removing a pre-existing local copy so one run converges), while
+# still writing the flat subagents, harness skills, and MCP registration this
+# installer always owns. Project-scope installs are unaffected — ~/.claude is
+# a user surface, never a project one.
+#
 # Idempotent: re-running is a no-op when owned entries already present.
-# Uninstall removes only ownership-marked entries + the plugin directory.
+# Uninstall removes only ownership-marked entries + the plugin directory,
+# regardless of which route (bridge or local) installed them.
 #
 # Usage:
 #   apps/cursor-plugin/install.sh             # install at user scope (~/.cursor)
@@ -92,20 +103,80 @@ if [[ "$SCOPE" == "project" ]]; then
 else
   CURSOR_DIR="$HOME/.cursor"
 fi
-# Cursor discovers locally-installed plugins under plugins/local/<name>/, not
-# plugins/<name>/. Installing to the latter is why massa-ai never appeared in
-# Cursor's plugin list even though every file was written correctly.
-#
-# UNVERIFIED against a running Cursor.app — this path comes from Cursor's
-# plugin documentation, not from an observed load, because Cursor is not
-# installed on the machine this was developed on. Treat it as lower confidence
-# than the Claude/Codex routes, which were verified end-to-end.
+# Two verified Cursor 3.14 load surfaces (observed live in "Cursor Plugins"
+# exthost logs, 2026-08-05): user-local plugins ARE loaded from
+# plugins/local/<name>/ ("loadUserLocalPlugin massa-ai loaded"), and Cursor
+# additionally bridges Claude marketplace plugins from ~/.claude
+# ("loadClaudePlugin massa-ai@massa-ai") — so a machine with the Claude
+# plugin installed loads massa-ai twice. Subagents, however, are discovered
+# only from the flat .cursor/agents/*.md directory (cursor.com/docs/subagents
+# — no subdirectories), and there is no global rules file. So: PLUGIN_DIR
+# carries the manifest, hook binary, and command skills; everything else
+# Cursor must SEE goes to its dedicated read paths — $CURSOR_AGENTS_DIR
+# (subagents), $CURSOR_DIR/skills/ (harness skills), $CURSOR_DIR/hooks.json,
+# and $CURSOR_DIR/mcp.json (install-agents.sh).
 PLUGIN_DIR="$CURSOR_DIR/plugins/local/massa-ai"
+# The only directory Cursor discovers subagents from (project scope:
+# ./.cursor/agents/). Flat .md files, real copies, massa-ai- prefix owned.
+CURSOR_AGENTS_DIR="$CURSOR_DIR/agents"
 # Pre-fix installs wrote here; removed on install so the two cannot both be
 # discovered and register duplicate hooks.
 LEGACY_PLUGIN_DIR="$CURSOR_DIR/plugins/massa-ai"
 HOOKS_JSON="$CURSOR_DIR/hooks.json"
 
+# ── Claude-bridge detection (PAU-08/09/10) ──────────────────────────────────
+# Probe contract pinned against a read-only capture of this machine's live
+# ~/.claude registry files (2026-08-05) — never invented:
+#   - $CLAUDE_PLUGIN_REGISTRY must parse and list a non-empty
+#     plugins["massa-ai@massa-ai"] array
+#   - $CLAUDE_SETTINGS_JSON's enabledPlugins["massa-ai@massa-ai"] must not be
+#     literal false — an absent settings.json, or an absent key, is treated
+#     as enabled (matching Claude's own default)
+#   - any parse failure on either file → NOT detected (local fallback)
+# User-scope only: ~/.claude is a per-user surface, so a --project plugin
+# install always keeps the local branch regardless of what ~/.claude holds.
+CLAUDE_PLUGIN_REGISTRY="$HOME/.claude/plugins/installed_plugins.json"
+CLAUDE_SETTINGS_JSON="$HOME/.claude/settings.json"
+
+claude_bridge_detected() {
+  [[ "$SCOPE" == "project" ]] && return 1
+  [[ -f "$CLAUDE_PLUGIN_REGISTRY" ]] || return 1
+
+  local runner=""
+  if command -v node &>/dev/null; then runner="node"
+  elif command -v bun &>/dev/null; then runner="bun"
+  else return 1
+  fi
+
+  "$runner" - "$CLAUDE_PLUGIN_REGISTRY" "$CLAUDE_SETTINGS_JSON" <<'NODE'
+const fs = require("fs");
+const [, , registryFile, settingsFile] = process.argv;
+
+try {
+  const registry = JSON.parse(fs.readFileSync(registryFile, "utf8"));
+  const listed = registry && registry.plugins && registry.plugins["massa-ai@massa-ai"];
+  if (!Array.isArray(listed) || listed.length === 0) process.exit(1);
+} catch {
+  process.exit(1);
+}
+
+try {
+  const raw = fs.readFileSync(settingsFile, "utf8");
+  if (raw.trim()) {
+    const settings = JSON.parse(raw);
+    const enabled = settings && settings.enabledPlugins && settings.enabledPlugins["massa-ai@massa-ai"];
+    if (enabled === false) process.exit(1);
+  }
+} catch (e) {
+  // Absent settings.json is treated as enabled (Claude's own default); any
+  // other read/parse failure means the probe cannot trust this surface.
+  if (e.code !== "ENOENT") process.exit(1);
+}
+
+process.exit(0);
+NODE
+}
+
 # The 7 Cursor events → binary subcommands. The command path uses the
 # INSTALLED plugin dir (not the placeholder), so Cursor invokes the copy.
 # Cursor hooks.json shape: { "version": 1, "hooks": { "<event>": [...] } }
@@ -377,13 +448,15 @@ record_plugin_version() {
   local version installed_at route
   version="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$SCRIPT_DIR/package.json" | head -n 1)"
   installed_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  # installRoute (T9, design F1): installer-owned, engine-read-only. Cursor
-  # has one install shape (file copy) and no marketplace distinction, so this
-  # is unconditionally "file" — recorded for data-model consistency with the
-  # other three hosts even though the switch engine never reads it for Cursor
-  # (hosts.ts skips Cursor unconditionally: every tier resolves to inherit).
-  # Written on EVERY install path.
-  route="file"
+  # installRoute (T6, design Component 4): installer-owned, engine-read-only.
+  # "bridge" when ~/.claude's Claude marketplace plugin is what Cursor
+  # actually loads (this run skipped its own local copy); "local" otherwise.
+  # The switch engine still never reads it for Cursor (hosts.ts skips Cursor
+  # unconditionally: every tier resolves to inherit) — recorded for
+  # data-model consistency with the other three hosts, and now also read by
+  # the harness sentinel probe (T4/T5), which treats both routes alike (same
+  # flat-agents glob). Written on EVERY install path.
+  if [[ "$IS_BRIDGE" -eq 1 ]]; then route="bridge"; else route="local"; fi
 
   # Tolerant of a corrupt/missing state file (rewrites a minimal valid one —
   # AC-8). A record-write failure warns but never fails the install: the next
@@ -429,6 +502,19 @@ if [[ "$UNINSTALL" -eq 1 ]]; then
     merge_hooks_json "$HOOKS_JSON" "uninstall"
     echo "  - removed massa-ai hook entries from $HOOKS_JSON"
   fi
+  # Remove the massa-ai-owned subagents from Cursor's discovery directory.
+  # Prefix glob only: user-authored agents in the same flat dir survive.
+  if [[ -d "$CURSOR_AGENTS_DIR" ]]; then
+    removed_agents=0
+    for agent in "$CURSOR_AGENTS_DIR/"massa-ai-*.md; do
+      [[ -f "$agent" ]] || continue
+      rm -f "$agent"
+      removed_agents=$((removed_agents + 1))
+    done
+    if [[ "$removed_agents" -gt 0 ]]; then
+      echo "  - removed $removed_agents massa-ai subagents from $CURSOR_AGENTS_DIR"
+    fi
+  fi
   # Remove plugin directory
   if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
     rm -rf "$LEGACY_PLUGIN_DIR"
@@ -444,59 +530,101 @@ if [[ "$UNINSTALL" -eq 1 ]]; then
 fi
 
 # ── Install ──────────────────────────────────────────────────────────────────
-vecho "Installing massa-ai Cursor plugin to: $PLUGIN_DIR"
-# Migration: a pre-fix install left a copy at plugins/massa-ai. Leaving it in
-# place risks Cursor discovering both and firing every hook twice, so it goes
-# before the new location is written.
-if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
-  rm -rf "$LEGACY_PLUGIN_DIR"
-  echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
+# PAU-08/09: bridge-preferred, local-fallback. Computed once, used to decide
+# both which artifacts this run writes and what installRoute gets recorded.
+IS_BRIDGE=0
+if claude_bridge_detected; then
+  IS_BRIDGE=1
 fi
-mkdir -p "$PLUGIN_DIR/.cursor-plugin" "$PLUGIN_DIR/skills" "$PLUGIN_DIR/hooks" "$PLUGIN_DIR/agents"
-
-# Copy manifest
-cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
-vecho "  + .cursor-plugin/plugin.json"
 
-# Copy the 6 host-command skills (each in a subdirectory: skills/<name>/SKILL.md).
-# massa-ai/, persona-router/, and agents/ are the PDO-06 harness bundle, not a
-# Cursor command skill — they are installed separately, into the shared
-# harness skills directory (see "Skills bundling" below), not into this
-# plugin-cache skills/ tree.
 skill_count=0
-for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
-  name="$(basename "$(dirname "$src")")"
-  case "$name" in
-    massa-ai|persona-router|agents) continue ;;
-  esac
-  mkdir -p "$PLUGIN_DIR/skills/$name"
-  cp "$src" "$PLUGIN_DIR/skills/$name/SKILL.md"
-  vecho "  + skills/$name/SKILL.md"
-  skill_count=$((skill_count + 1))
-done
+specialist_count=0
 
-# Copy hooks.json (the placeholder version — installer replaces paths)
-cp "$SCRIPT_DIR/hooks/hooks.json" "$PLUGIN_DIR/hooks/hooks.json"
-vecho "  + hooks/hooks.json"
-
-# Older installs shipped a plugin-local mcp.json here. Cursor reads
-# ~/.cursor/mcp.json, not the plugin dir, and MCP is now owned by
-# scripts/install-agents.sh — drop the residue so upgraders converge.
-if [[ -f "$PLUGIN_DIR/mcp.json" ]]; then
-  rm -f "$PLUGIN_DIR/mcp.json"
-  # Not gated by --quiet: this deletes a file in the user's home, so it is a
-  # mutation notice rather than per-file chatter.
-  echo -e "  - removed stale mcp.json (MCP is now registered in ~/.cursor/mcp.json)"
+if [[ "$IS_BRIDGE" -eq 1 ]]; then
+  vecho "Installing massa-ai Cursor plugin (Claude-bridge route): ~/.claude already lists massa-ai as installed and enabled, so Cursor loads it via the bridge."
+  # Converge (PAU-08, spec edge case): a pre-existing local install (current
+  # or pre-fix legacy location) must not double-load alongside the bridge, so
+  # one run here ends with exactly one load path. Owned hook entries are
+  # stripped with the SAME filter merge_hooks_json's "uninstall" mode already
+  # uses — the bridge delivers hooks instead.
+  if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
+    rm -rf "$LEGACY_PLUGIN_DIR"
+    echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
+  fi
+  if [[ -d "$PLUGIN_DIR" ]]; then
+    rm -rf "$PLUGIN_DIR"
+    echo -e "  - removed local plugin copy at $PLUGIN_DIR (Claude bridge already loads massa-ai)"
+  fi
+  if [[ -f "$HOOKS_JSON" ]]; then
+    merge_hooks_json "$HOOKS_JSON" "uninstall"
+    echo -e "  - removed massa-ai hook entries from $HOOKS_JSON (the bridge delivers hooks instead)"
+  fi
+else
+  vecho "Installing massa-ai Cursor plugin to: $PLUGIN_DIR"
+  # Migration: a pre-fix install left a copy at plugins/massa-ai. Leaving it in
+  # place risks Cursor discovering both and firing every hook twice, so it goes
+  # before the new location is written.
+  if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
+    rm -rf "$LEGACY_PLUGIN_DIR"
+    echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
+  fi
+  mkdir -p "$PLUGIN_DIR/.cursor-plugin" "$PLUGIN_DIR/skills" "$PLUGIN_DIR/hooks"
+  # Migration: pre-fix installs bundled agents inside the plugin dir, which
+  # Cursor never reads. Drop that copy so upgraders converge on the one real
+  # discovery surface and a future Cursor plugin scan cannot double-register.
+  if [[ -d "$PLUGIN_DIR/agents" ]]; then
+    rm -rf "$PLUGIN_DIR/agents"
+    echo -e "  - removed pre-fix agents copy at $PLUGIN_DIR/agents (Cursor reads $CURSOR_AGENTS_DIR)"
+  fi
+
+  # Copy manifest
+  cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
+  vecho "  + .cursor-plugin/plugin.json"
+
+  # Copy the 6 host-command skills (each in a subdirectory: skills/<name>/SKILL.md).
+  # massa-ai/, persona-router/, and agents/ are the PDO-06 harness bundle, not a
+  # Cursor command skill — they are installed separately, into the shared
+  # harness skills directory (see "Skills bundling" below), not into this
+  # plugin-cache skills/ tree.
+  for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
+    name="$(basename "$(dirname "$src")")"
+    case "$name" in
+      massa-ai|persona-router|agents) continue ;;
+    esac
+    mkdir -p "$PLUGIN_DIR/skills/$name"
+    cp "$src" "$PLUGIN_DIR/skills/$name/SKILL.md"
+    vecho "  + skills/$name/SKILL.md"
+    skill_count=$((skill_count + 1))
+  done
+
+  # Copy hooks.json (the placeholder version — installer replaces paths)
+  cp "$SCRIPT_DIR/hooks/hooks.json" "$PLUGIN_DIR/hooks/hooks.json"
+  vecho "  + hooks/hooks.json"
+
+  # Older installs shipped a plugin-local mcp.json here. Cursor reads
+  # ~/.cursor/mcp.json, not the plugin dir, and MCP is now owned by
+  # scripts/install-agents.sh — drop the residue so upgraders converge.
+  if [[ -f "$PLUGIN_DIR/mcp.json" ]]; then
+    rm -f "$PLUGIN_DIR/mcp.json"
+    # Not gated by --quiet: this deletes a file in the user's home, so it is a
+    # mutation notice rather than per-file chatter.
+    echo -e "  - removed stale mcp.json (MCP is now registered in ~/.cursor/mcp.json)"
+  fi
 fi
 
-# Copy agents — every generated subagent specialist (auto-discovered by Cursor
-# from the plugin's agents/ dir). All of them, navigator included, are generated
-# from skills/agents/*/SKILL.md and owned by the massa-ai- name prefix (CRS-04).
-specialist_count=0
+# Flat agents and harness skills are written in BOTH branches (PAU-08/09):
+# Cursor discovers subagents only from the flat directory regardless of which
+# plugin-load path is active, and MCP/harness-skills ownership is independent
+# of it too. Prune-then-copy so a specialist deleted from the bundle cannot
+# linger installed. All of them, navigator included, are generated from
+# skills/agents/*/SKILL.md and owned by the massa-ai- name prefix (CRS-04) —
+# user-authored agents are untouched.
+mkdir -p "$CURSOR_AGENTS_DIR"
+rm -f "$CURSOR_AGENTS_DIR/"massa-ai-*.md
 for src in "$SCRIPT_DIR/agents/"massa-ai-*.md; do
   [[ -f "$src" ]] || continue
   name="$(basename "$src")"
-  cp "$src" "$PLUGIN_DIR/agents/$name"
+  cp "$src" "$CURSOR_AGENTS_DIR/$name"
   vecho "  + $name"
   specialist_count=$((specialist_count + 1))
 done
@@ -504,31 +632,33 @@ vecho "  + ${specialist_count} subagent specialists (generated from skills/agent
 
 # Skills bundling (PDO-08, 09): install massa-ai/persona-router into the
 # shared harness skills directory, unless scripts/install-skills.sh already
-# owns it for this platform.
+# owns it for this platform. Runs in both branches (same reasoning as above).
 vecho ""
 install_bundled_skills
 
-# Copy the real hooks/massa-ai-hook this plugin already ships (T14/PDO-14: a
-# generated real file, no longer a symlink into apps/claude-plugin/ — that
-# path does not exist in a registry tarball install, where $REPO_ROOT is not
-# this monorepo. $CLAUDE_PLUGIN_BIN is kept only as a repo-checkout fallback.
-if [[ -f "$SCRIPT_DIR/hooks/massa-ai-hook" ]]; then
-  cp "$SCRIPT_DIR/hooks/massa-ai-hook" "$PLUGIN_DIR/hooks/massa-ai-hook"
-  chmod +x "$PLUGIN_DIR/hooks/massa-ai-hook"
-  vecho "  + hooks/massa-ai-hook"
-elif [[ -f "$CLAUDE_PLUGIN_BIN" ]]; then
-  ln -sfn "$CLAUDE_PLUGIN_BIN" "$PLUGIN_DIR/hooks/massa-ai-hook"
-  vecho "  + hooks/massa-ai-hook → $CLAUDE_PLUGIN_BIN"
-else
-  echo "  ⚠ Warning: no massa-ai-hook binary found" >&2
-  echo "    Hooks will not fire until the binary is available." >&2
-fi
+if [[ "$IS_BRIDGE" -ne 1 ]]; then
+  # Copy the real hooks/massa-ai-hook this plugin already ships (T14/PDO-14: a
+  # generated real file, no longer a symlink into apps/claude-plugin/ — that
+  # path does not exist in a registry tarball install, where $REPO_ROOT is not
+  # this monorepo. $CLAUDE_PLUGIN_BIN is kept only as a repo-checkout fallback.
+  if [[ -f "$SCRIPT_DIR/hooks/massa-ai-hook" ]]; then
+    cp "$SCRIPT_DIR/hooks/massa-ai-hook" "$PLUGIN_DIR/hooks/massa-ai-hook"
+    chmod +x "$PLUGIN_DIR/hooks/massa-ai-hook"
+    vecho "  + hooks/massa-ai-hook"
+  elif [[ -f "$CLAUDE_PLUGIN_BIN" ]]; then
+    ln -sfn "$CLAUDE_PLUGIN_BIN" "$PLUGIN_DIR/hooks/massa-ai-hook"
+    vecho "  + hooks/massa-ai-hook → $CLAUDE_PLUGIN_BIN"
+  else
+    echo "  ⚠ Warning: no massa-ai-hook binary found" >&2
+    echo "    Hooks will not fire until the binary is available." >&2
+  fi
 
-# Merge hooks.json (array-append, backup, idempotent)
-vecho ""
-vecho "Merging hooks into $HOOKS_JSON..."
-merge_hooks_json "$HOOKS_JSON" "install"
-vecho "  + 7 massa-ai hook events wired (array-append, user hooks preserved)"
+  # Merge hooks.json (array-append, backup, idempotent)
+  vecho ""
+  vecho "Merging hooks into $HOOKS_JSON..."
+  merge_hooks_json "$HOOKS_JSON" "install"
+  vecho "  + 7 massa-ai hook events wired (array-append, user hooks preserved)"
+fi
 
 # ── MCP registration (delegated) ─────────────────────────────────────────────
 # scripts/install-agents.sh is the single writer of host MCP config. It writes
@@ -552,10 +682,17 @@ fi
 
 # Summary line in quiet mode
 if [ "${MASSA_AI_VERBOSE:-0}" != "1" ]; then
-  ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists, 7 hooks)"
+  if [[ "$IS_BRIDGE" -eq 1 ]]; then
+    ok "cursor plugin: using the Claude bridge (${specialist_count} specialists) — hooks delivered by the bridge, not installed locally"
+  else
+    ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists, 7 hooks)"
+  fi
 else
   vecho ""
   vecho "Done. Restart Cursor to pick up the plugin."
+  if [[ "$IS_BRIDGE" -eq 1 ]]; then
+    vecho "💡 massa-ai loads via the Claude bridge (~/.claude) — local plugin/hook install skipped."
+  fi
   vecho "💡 MCP is registered in ~/.cursor/mcp.json by scripts/install-agents.sh (single writer)."
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/massa-ai/SKILL.md

@@ -46,7 +46,7 @@ Before reading any massa-ai file:
   Never pass `workflowSessionId` in that field. Use `synapse_task_begin`/`synapse_task_end`
   for task envelopes and `synapse_prefetch` to warm the buffer on file open.
 - Prefer the shared v2 retrieval order; fall back gracefully if the massa-ai
-  server or Synapse is unavailable. The full tool surface includes 52 tools
+  server or Synapse is unavailable. The full tool surface includes 54 tools
   (see `references/mcp-tools.md`): indexing, search, symbol graph
   (`trace_path`, `impact_analysis`, `get_architecture`), memory CRUD
   (`remember`, `recall`, `memory_update`, `memory_delete`), checkpoints
@@ -166,6 +166,7 @@ current context already contains it.
 | `commit` | draft or create safe Conventional Commits with Jira branch prefixes and audit report exclusions | `workflows/commit.md` |
 | `the-fool` | direct challenge, red-team, pre-mortem, evidence audit | `workflows/the-fool.md` |
 | `judge-with-debate` | standalone multi-judge debate evaluation of user-supplied artifacts | `workflows/judge-with-debate.md` |
+| `pr-review` | review a hosted GitHub PR / GitLab MR and post findings via `gh`/`glab` | `workflows/pr-review.md` |
 | `to-prd` | turn the current conversation into a PRD without a new interview | `workflows/to-prd.md` |
 | `skill-architect` | design and build a new skill through structured conversation | `workflows/skill-architect.md` |
 | `furps-refinement` | FURPS+ refinement of a PRD and/or ADR before implementation, with The Fool pre-validation and DoR coverage | `workflows/refinement/furps-refinement.md` |
@@ -181,7 +182,7 @@ Deterministic routing precedence, first match wins:
 
 1. **Explicit route:** user names a massa-ai workflow, report family, saved finding type, or asks for a direct challenge.
 2. **Requested artifact:** ADR, RFC, TDD, Jira ticket, commit, session guide, audit report, implementation audit report, mobile Figma report, FURPS refinement report, PRD synthesized from the current conversation -> `to-prd` (explicit request only; refining an existing PRD stays `furps-refinement`), or new SKILL.md / skill design -> `skill-architect`.
-3. **Target type:** broken behavior/error -> `debug`; saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; Maestro E2E/device automation target -> `maestro`, `maestro-audit`, or child-only `maestro-fix` before generic tests workflows; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
+3. **Target type:** broken behavior/error -> `debug`; hosted PR/MR reference (number or URL) to review with posted findings -> `pr-review` (local working diff stays with audit routes); saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; Maestro E2E/device automation target -> `maestro`, `maestro-audit`, or child-only `maestro-fix` before generic tests workflows; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
 4. **Primary verb:** create/add/implement -> `feature` unless the concrete target is new Maestro flow work, which routes to `maestro`; restructure without behavior change -> `refactor`; inspect/understand only -> `exploration`; record selected decision -> `adr`; compare open options -> `rfc`; design settled implementation -> `tdd`; refine/quality-check an existing PRD or ADR document (not implementation auditing) -> `furps-refinement`.
 5. **Risk domain escalation:** migrations, irreversible operations, auth/privacy, cross-service contracts, public compatibility, or work over 10 files routes to `spec-driven` unless the user explicitly requests a narrower workflow and accepts the containment.
 6. **General fallback:** use `general` only after a one-line General fallback preflight names the specialized workflow considered, rejected reason, and why fallback does not change verification or mutation behavior.

package/skills/massa-ai/references/installation.md

@@ -100,9 +100,9 @@ behavior through MCP declarations and non-destructive runtime probes.
 - Preferred: `bash scripts/install-agents.sh --agent <host>` — the single writer
   of host MCP config (Claude Code, Claude Desktop, Codex, Cursor, OpenCode).
   Plugin installers call it; nothing else writes an MCP entry.
-- OpenCode: local MCP package via `bunx @massa-ai/mcp-client`, or
-  `@massa-ai/opencode-plugin` (which registers tools in-process, so
-  `install-agents.sh` skips the MCP entry when that plugin is present).
+- OpenCode: `@massa-ai/opencode-plugin` is hooks-only (AD-017) and delegates
+  MCP registration to `install-agents.sh --agent opencode` on every install,
+  same as every other host — no separate MCP step needed.
 - VS Code/Antigravity: `.vscode/mcp.json` or `./scripts/setup-vscode.sh`.
 - Docker: run the `mcp` service through `docker compose run --rm -i mcp`.
 

package/skills/massa-ai/references/mcp-tools.md

@@ -1,4 +1,4 @@
-# massa-ai Tool Contracts (52 Tools)
+# massa-ai Tool Contracts (54 Tools)
 
 Load when exact MCP schemas, REST fallbacks, response modes, or
 polling rules are needed. Prefer the active tool declaration over copied
@@ -138,6 +138,8 @@ depends on exact content.
 |---|---|---|
 | `rename_project` | Rename a project identity transactionally | Req: `sourceProjectId`, `targetProjectId`. Default `dryRun=true`; apply with `dryRun=false` + `operationId` + `expectedPlanHash`. Administrative, not workflow-recurring. |
 | `merge_projects` | Merge one project identity into another | Req: `sourceProjectId`, `targetProjectId`. Same dryRun/planHash contract as `rename_project`. Administrative, not workflow-recurring. |
+| `profile_list` | List shipped model profiles and each detected host's current profile + bundle version | No required args; optional `host` to scope to one. Offline — reads on-disk variant directories only, never the registry. |
+| `profile_set` | Switch the installed massa-ai agents to a registry model profile | Req: `profile`. Optional `host` (default: every detected, supported host), `dryRun` (default `false`) to preview without writing. Local trust model — mutates installed agent files on the machine the MCP server runs on; a host session restart is required to take effect. |
 
 ## Retrieval Order
 

package/skills/massa-ai/workflows/pr-review.md

@@ -0,0 +1,246 @@
+---
+name: pr-review
+description: "Explicit-route workflow to review a hosted GitHub Pull Request or GitLab Merge Request across six dimensions — security, requirements, test coverage, architecture, regression, performance — using massa-ai roster subagents, then post inline comments plus one consolidated summary through the host CLI (gh or glab). Use when the user says review PR 128, review this MR, or code review this pull request. Do NOT use for local working-diff review (audit workflows), creating PRs, replying to review comments, or fixing CI."
+license: CC-BY-4.0
+metadata:
+  version: "1.0.0"
+---
+
+Attribution: adapted from the `pr-review` skill by github.com/augusto-dmh
+(TLC skills catalog), licensed CC-BY-4.0. Host abstraction (GitLab support),
+massa-ai roster dispatches, memory/index/`.specs/` integration, and channel
+discipline are this repository's additions; repository contracts win on any
+conflict with the base.
+
+### PR Review
+
+Use when the user explicitly asks to review a hosted PR (Pull Request, GitHub) or
+MR (Merge Request, GitLab) — "review PR 128", "review this MR", "check pull request
+42". Explicit route only: never auto-trigger during coding. Local working-tree diff
+review stays with the audit workflows and `massa-ai-reviewer`; this workflow exists
+to **post findings back to the host**.
+
+Load `references/project-context.md` (intake sweep) before the first substantive
+read. Resolve `projectId` and `workflowSessionId` = `pr-review-<number>` per the
+Core Contract, and run a budgeted `recall` (limit ≤ 3, minImportance ≥ 0.7) for
+prior review conventions and known regression patterns.
+
+## Execution Contract (non-negotiable)
+
+1. **Orchestration-only.** The main agent never authors a review finding. It
+   gathers context, dispatches the review subagents, dedupes their returned
+   findings, and posts. Doing the review inline — even for a small diff — is a
+   failure of this workflow.
+2. **Comment-only, never destructive.** Forbidden in every circumstance:
+   `gh pr review --approve`, `gh pr review --request-changes`, `gh pr merge`,
+   `glab mr approve`, `glab mr revoke`, `glab mr merge`, and the raw
+   `POST …/approve` / `POST …/unapprove` endpoints. Posting notes or discussions
+   never approves — keep it that way. Never modify repository files.
+3. **Subagents never touch the host.** Review subagents are read-only and
+   host-agnostic: they receive the diff and context in their packet and return
+   findings in their reply block. Only the orchestrator executes `gh`/`glab`.
+4. **File-body posting.** Every multiline body is written to a temp file and
+   posted with the host's file-body mechanism (`--body-file` / `-F body=@file`).
+   Inlining a multiline `--body` string is the protocol's most common failure.
+5. **Ask, never guess.** No PR/MR reference in the request → ask for it. Host CLI
+   cannot resolve the reference → stop and surface the CLI error output.
+
+## Step 1 — Initialize
+
+### 1a. Resolve the host
+
+Order: explicit user statement > CLI probe > git remote host. Probe with
+`gh repo view` / `glab repo view` **exit status** (glab's no-remote error text is
+not a documented stable string — never match on the message). Both probes fail →
+stop and report which CLI is missing or unauthenticated (`gh auth status` /
+`glab auth status`). Both succeed (mirrored repo) → ask the user which host to
+review on; a posted comment is outward-facing. Record `HOST ∈ {github, gitlab}`.
+
+### 1b. PR/MR context (via the command map below)
+
+Resolve repository identity, then fetch: title + body/description + source
+branch, the head anchor (`{SHA}` on GitHub; the full `diff_refs`
+`{base_sha, head_sha, start_sha}` triple on GitLab), the full diff, and the
+changed-file list. Then load the existing inline-comment inventory as
+`{id, path, line, body}` records — **page to completion** (GitLab discussions
+default to 20 per page; pin `per_page=100` and loop) — used for dedupe,
+`[RESOLVED]` replies, and threading.
+
+### 1c. Project discovery (the adaptive spine)
+
+Probe the repository once and record a DISCOVERY MAP passed verbatim to every
+subagent. Prefer evidence the project states over guesses; mark absences `none`.
+
+```
+TEST:          <command CI actually runs> | globs: <...> | unit vs e2e: <split | none>
+REQS:          tracker=<GH #42 | Jira KEY-123 | GitLab #42 | none> ; specs=<paths | none>
+CONVENTIONS:   <doc/skill paths that state rules | none-found>
+REVIEW_SKILLS: <project-local review skill paths | none>
+INDEX:         <massa-ai retrieval state: fresh | stale | unavailable — CLI fallback>
+```
+
+- **TEST**: the CI workflow config is authoritative; manifests are fallback.
+- **REQS Track A (tracker)**: ticket key from branch name or PR/MR body —
+  `gh issue view {N} --json title,body` / `glab issue view {N} --output json`;
+  Jira only through an already-configured Atlassian MCP (never invent a host).
+- **REQS Track B (in-repo)**: `.specs/project/FEATURES.json` and
+  `.specs/features/<slug>/{spec,tasks}.md` acceptance criteria matched by branch,
+  ticket, or feature stem; then `docs/`, ADR/RFC directories, `*-spec.md`.
+- **CONVENTIONS/REVIEW_SKILLS**: `CONTRIBUTING*`, `ARCHITECTURE*`, `AGENTS.md`,
+  `CLAUDE.md`, `docs/**` convention files, `.claude/skills/`, `.cursor/skills/`.
+- **INDEX**: `list_projects` freshness first; when fresh, `project_map` or
+  `get_architecture` for orientation and `impact_analysis` over the PR/MR diff
+  for centrality-ranked hotspots; `search` under `references/synapse-policy.md`
+  when two or more related searches are planned. Index results are leads until
+  confirmed against the diff — never evidence on their own. Server or index
+  unavailable → record it and continue per `references/graceful-degradation.md`.
+
+## Host Command Map
+
+The orchestrator reads every host operation from this table. `{REPO}`/`{PR}` are
+GitHub coordinates; `{MR}` is the GitLab IID; `:id` is glab's project placeholder
+(resolved from the current repo's remote — 8 placeholders are documented:
+`:branch :fullpath :group :id :namespace :repo :user :username`).
+
+| Operation | GitHub (`gh`) | GitLab (`glab`) |
+| --- | --- | --- |
+| Identity | `gh repo view --json nameWithOwner -q .nameWithOwner` → `{REPO}` | `glab repo view --output json --jq .path_with_namespace` (project id: `--jq .id`) |
+| Metadata | `gh pr view {PR} --json title,body,headRefName,headRefOid` → `{SHA}` | `glab mr view {MR} --output json` → `title`, `description`, `source_branch`, `sha`, `diff_refs.{base_sha,head_sha,start_sha}` |
+| Full diff | `gh pr diff {PR}` | `glab mr diff {MR} --raw` |
+| Changed files | `gh pr diff {PR} --name-only` | `glab api "projects/:id/merge_requests/{MR}/diffs?per_page=100&page={N}"` → `new_path`/`old_path`, page to completion |
+| Existing comments | `gh api repos/{REPO}/pulls/{PR}/comments` | `glab api "projects/:id/merge_requests/{MR}/discussions?per_page=100&page={N}"` → note `id`, `position.new_path`, `position.new_line`, `body` |
+| Inline comment | `gh api repos/{REPO}/pulls/{PR}/comments -F body=@body.md -f commit_id={SHA} -f path={path} -F line={N} -f side=RIGHT` | `glab api --method POST "projects/:id/merge_requests/{MR}/discussions" -F body=@body.md -f "position[position_type]=text" -f "position[base_sha]={base}" -f "position[head_sha]={head}" -f "position[start_sha]={start}" -f "position[new_path]={path}" -f "position[old_path]={old}" -F "position[new_line]={N}"` |
+| Thread reply | `gh api repos/{REPO}/pulls/{PR}/comments/{COMMENT_ID}/replies -F body=@body.md` | `glab api --method POST "projects/:id/merge_requests/{MR}/discussions/{DISCUSSION_ID}/notes" -F body=@body.md` |
+| Summary | `gh pr review {PR} --comment --body-file summary.md` | `glab api --method POST "projects/:id/merge_requests/{MR}/notes" -F body=@summary.md` |
+
+Anchoring and flag semantics (load-bearing, verified against official docs):
+
+- **GitHub `line={N}`** is the 1-based line number in the **head file** on side
+  `RIGHT` — count from the hunk header across added and context lines. A
+  diff-relative offset returns 422 or lands on the wrong line.
+- **GitLab added line** ⇒ send `position[new_line]` and **omit** `old_line`
+  (removed line: the reverse; context line: both). `new_path` **and** `old_path`
+  are both required for `position_type=text` — take `old_path` from the `/diffs`
+  inventory, never assume it equals `new_path` (renames break that).
+- **`-F`/`--field` expands `@file` and infers types on both CLIs; `-f`/
+  `--raw-field` does neither** — `-f body=@body.md` posts the literal string
+  `@body.md`. Use `-F` for bodies and line numbers, `-f` for plain strings.
+  glab's `-F` also switches the default method to POST.
+- `glab mr note create` has experimental inline flags (`--file`, `--line`,
+  `--reply`) — GitLab marks them "might be unstable or removed at any time"; the
+  stable `glab api` paths above are the contract. A plain summary may also use
+  `glab mr note create {MR} < summary.md` (body from stdin).
+
+## Step 2 — Dispatch the review (two waves)
+
+Six dimensions run as read-only roster dispatches under
+`references/agent-orchestration.md` (wave cap 4 → wave 1 = rows 1–4, wave 2 =
+rows 5–6). Each packet carries: the dimension row below, the DISCOVERY MAP, the
+PR/MR intent (title/body/branch), the existing-comment inventory, the diff
+trimmed to hunks relevant to the dimension per `references/context-firewall.md`,
+the severity labels, and the reply contract.
+
+| # | Dimension | Agent | Packet delta (lens / scope) | Marker `{type}` |
+| --- | --- | --- | --- | --- |
+| 1 | Security | `massa-ai-audit-specialist` | `lens: security` — secrets, authn/authz on new endpoints, injection, unsafe deserialization, PII in logs, permissive CORS, leaking payload fields | `security` |
+| 2 | Requirements & DoD (Definition of Done) | `massa-ai-audit-specialist` | `lens: requirements` — score merged Track A + Track B criteria against the diff, evidence-or-zero: ✅ implemented (`path:line`) / 🟡 partial / ❌ missing; no source ⇒ report "requirements verification skipped" | `requirements` |
+| 3 | Architecture & conventions | `massa-ai-audit-specialist` | `lens: architecture` — extract every explicit rule from the profile's CONVENTIONS/REVIEW_SKILLS docs into a numbered matrix, grade each changed file PASS/VIOLATION/N/A; no docs ⇒ minimal generic boundary sweep, stated | `architecture` |
+| 4 | Performance | `massa-ai-audit-specialist` | `lens: performance` — only issues clearly visible in the diff: N+1 queries, unbounded fetches, per-row lazy I/O, sequential awaits of independent calls, loop-invariant recomputation, unbatched writes | `performance` |
+| 5 | Test coverage | `massa-ai-audit-specialist` | `lens: performance`, scope: test coverage (the charter's lens set has no `tests` lens; `tests-audit.md` precedent) — new/changed behavior with no test, wrong level (unit vs integration), placement/naming vs profile TEST row, missing negative case, assertions that exercise but never assert | `tests` |
+| 6 | Regression & hallucination | `massa-ai-reviewer` | diff review — unrelated deletions, references to symbols absent from the repo, wrong signature/arity, duplicated existing logic, weakened error handling or assertions, leftover TODO/stub, dead code | `regression` |
+
+Consolidation check (≥ 5 subagents): recorded in the feature design — rows 4 and 5
+share only the lens label, not a knowledge domain; they stay separate dispatches.
+
+> **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
+> - trigger: pr-review Step 2, dimension rows 1–5 (one dispatch per row)
+> - scope: the PR/MR diff and surrounding context for one dimension row; never the whole repository
+> - permissions: read-only; no host CLI calls, no posting
+> - inputs: exact `projectId`, parent `workflowSessionId`, dimension row (lens + scope), DISCOVERY MAP, PR/MR intent, trimmed diff, existing-comment inventory, severity labels, reply contract
+> - sensors: second-pass sweep — re-read the full trimmed diff, list every file/hunk not commented on, and state per file why it is clean for this dimension before returning
+> - output: structured reply block — findings rows `{path, head-line, severity, marker type, title, body ≤ 6 lines, recommendation}` + exactly one positive highlight + files-swept-clean list; when uncertain a finding is real, withhold it (the source protocol's high-confidence bar, applied qualitatively)
+> - firewall: raw diff/log/search output summarized, never returned raw
+> - memory: suggest-only; the main agent persists durable outcomes
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: pr-review Step 2, dimension row 6 (regression & hallucination)
+> - scope: the full PR/MR diff against the repository's real symbol surface
+> - permissions: read-only; no host CLI calls, no posting
+> - inputs: exact `projectId`, parent `workflowSessionId`, dimension row 6, DISCOVERY MAP, PR/MR intent, full diff, existing-comment inventory, severity labels, reply contract
+> - sensors: verify referenced symbols exist (`search_definitions`/`get_references` when INDEX is fresh, else grep); second-pass sweep as above
+> - output: structured reply block — findings rows tagged `{unrelated-deletion | phantom-reference | wrong-signature | duplicate | weakened-check | dead-code}` + one positive highlight + files-swept-clean list; withhold uncertain findings
+> - firewall: raw diff/log/search output summarized, never returned raw
+> - memory: suggest-only; the main agent persists durable outcomes
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+Severity labels (all dimensions): 🚨 Critical (bugs/logic errors that will fail) ·
+🔒 Security · ⚡ Performance · ⚠️ Warning (smells/maintainability) ·
+💡 Suggestion. A failed or unavailable dispatch is reported in the summary as a
+skipped dimension with its reason — never silently dropped.
+
+## Step 3 — Post inline findings (orchestrator only)
+
+For every returned finding, in order:
+
+1. **Dedupe**: drop it when an existing comment sits within ±3 lines of the same
+   path/line (inventory from 1b) or another dimension already produced the same
+   `{path, line}` finding (keep the higher severity; note both markers).
+2. **Resolve check**: when an existing comment's issue is fixed by this diff,
+   reply `[RESOLVED] This appears resolved by the recent changes.` on that thread
+   via the reply command (GitHub: the comment's `id`; GitLab: its
+   `discussion_id`).
+3. **Anchor**: only added (`+`) diff lines on the head revision, per the
+   anchoring semantics above. A finding with no `+` line to stand on goes to the
+   summary instead.
+4. **Body**: temp file, starting with the invisible marker
+   `<!-- pr-review:{type} -->`, then `[severity emoji] — [short title]`, the
+   evidence-grounded body, and a `**Recommendation:**` line. No AI/assistant/
+   tool attribution anywhere — write as a reviewer. Specific, actionable,
+   collegial; always explain why.
+5. **Post** with the inline-comment command for `HOST`.
+
+## Step 4 — Consolidated summary
+
+Assemble from the reply blocks (no extra subagent) and post one summary via the
+summary command:
+
+```markdown
+## 📋 PR Review Summary
+
+| | |
+|---|---|
+| **Host / target** | {github PR #N | gitlab MR !N} @ {head sha} |
+| **Dimensions** | 6 (Security · Requirements & DoD · Tests · Architecture · Regression · Performance) |
+| **Detected runner** | {TEST row | none found} |
+| **Requirements source** | {tracker / spec paths / none} |
+| **Project refs loaded** | {CONVENTIONS + REVIEW_SKILLS rows} |
+| **Findings** | {N} across {M} files |
+
+### 🔒 Security ({N}) / 🚨 Critical ({N}) / ⚡ Performance ({N}) / ⚠️ Warnings ({N}) / 💡 Suggestions ({N})
+- [`path/file:L42`] Finding title — one line each, grouped by severity
+
+### 📋 Requirements
+{✅/🟡/❌ rows from dimension 2, with `path:line` evidence}
+
+### 🔍 Files with no findings
+- `path` — swept clean by {dimensions} (omit section when every logic file got a comment; config/lock/declaration files excluded)
+
+### ✅ Highlights
+- one per dimension
+
+> See inline comments for details. {Skipped dimensions/sensors with reasons, if any.}
+```
+
+Zero findings overall → post "✅ No issues found across all review dimensions."
+with the metadata table intact.
+
+## Completion
+
+- Emit Conversation Feedback status updates at wave boundaries when that policy
+  is active; expand every abbreviation on first use in user-facing output.
+- Persist durable outcomes only (recurring review pattern, confirmed project
+  convention) with the required memory tags; do not fabricate memories.
+- Close with `references/evidence-gate.md`: counts posted vs deduped vs withheld,
+  skipped dimensions/sensors with reasons, and the summary URL/reference.
+<!-- validator anchors: comment-only | added (+) diff lines | page to completion | two waves -->