@massa-ai/cursor-plugin 1.27.0 → 1.30.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.27.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/agent-profiles/balanced/massa-ai-judge.md

@@ -1,8 +1,7 @@
 ---
 name: massa-ai-judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 model: inherit
-readonly: true
 ---
 # Judge Agent Skill
 

package/agent-profiles/cheap/massa-ai-judge.md

@@ -1,8 +1,7 @@
 ---
 name: massa-ai-judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 model: inherit
-readonly: true
 ---
 # Judge Agent Skill
 

package/agent-profiles/heavy/massa-ai-judge.md

@@ -1,8 +1,7 @@
 ---
 name: massa-ai-judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 model: inherit
-readonly: true
 ---
 # Judge Agent Skill
 

package/agent-profiles/home/massa-ai-judge.md

@@ -1,8 +1,7 @@
 ---
 name: massa-ai-judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 model: inherit
-readonly: true
 ---
 # Judge Agent Skill
 

package/agent-profiles/work/massa-ai-judge.md

@@ -1,8 +1,7 @@
 ---
 name: massa-ai-judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 model: inherit
-readonly: true
 ---
 # Judge Agent Skill
 

package/agents/massa-ai-judge.md

@@ -1,8 +1,7 @@
 ---
 name: massa-ai-judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 model: inherit
-readonly: true
 ---
 # Judge Agent Skill
 

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)
@@ -51,26 +62,121 @@ done
 source "$SCRIPT_DIR/../../scripts/banner.sh"
 massa_ai_banner
 
+# ── Generated-bundle contract (T7, design Component 4 / UGB-05..07) ─────────
+# Why: apps/*-plugin generated subtrees (skills/, agents/, agent-profiles/,
+#      hooks/massa-ai-hook, lib/opencode-config.cjs) are gitignored build
+#      output (UGB-01) — a repo checkout must regenerate them before this
+#      installer copies or registers anything; a published tarball ships them
+#      pre-generated and has no generator sources to run at all. Runs before
+#      any host-config mutation (before CURSOR_DIR resolution below). Cursor
+#      has no PLUGIN_SOURCE_ROOT (no marketplace registration path), so
+#      REPO_ROOT — already the checkout root this script lives in — is the
+#      detection root, exactly mirroring $SCRIPT_DIR/../.. for the other hosts.
+# Impacts: UGB-05 checkout generates, UGB-06 tarball skips, UGB-07 loud
+#          failure before mutation, UGB-08 (skip-env honored for harness runs).
+# Test: apps/cursor-plugin/__tests__/install.test.ts (skip-branch + loud-failure cases)
+if [[ -f "$REPO_ROOT/scripts/generate-skill-artifacts.ts" ]]; then
+  if [[ "${MASSA_AI_SKIP_ARTIFACT_GENERATION:-0}" != "1" ]]; then
+    if ! command -v bun &>/dev/null; then
+      echo "Error: bun required to generate plugin bundles in a repo checkout (scripts/generate-*.ts)" >&2
+      exit 3
+    fi
+    bun "$REPO_ROOT/scripts/generate-skill-artifacts.ts"
+    bun "$REPO_ROOT/scripts/generate-subagent-artifacts.ts"
+  fi
+fi
+# Tarball installs (generator sources absent) skip the block above entirely
+# and fall straight through to this sentinel, which every context must pass:
+# the bundle this installer is about to copy/register has to actually exist.
+if [[ ! -f "$SCRIPT_DIR/skills/massa-ai/SKILL.md" ]]; then
+  echo "Error: missing $SCRIPT_DIR/skills/massa-ai/SKILL.md — run 'bun run generate:artifacts' first" >&2
+  exit 1
+fi
+if [[ ! -d "$SCRIPT_DIR/agents" ]] || [[ -z "$(ls -A "$SCRIPT_DIR/agents" 2>/dev/null)" ]]; then
+  echo "Error: missing or empty $SCRIPT_DIR/agents — run 'bun run generate:artifacts' first" >&2
+  exit 1
+fi
+
 # Resolve target base dir
 if [[ "$SCOPE" == "project" ]]; then
   CURSOR_DIR="$(pwd)/.cursor"
 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>": [...] } }
@@ -342,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
@@ -394,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"
@@ -409,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
+
+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)"
+  # 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
@@ -469,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
@@ -517,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.27.0",
+  "version": "1.30.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/agents/judge/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: judge
-description: Read-only debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
+description: Debate-panel evaluator for judge-with-debate. Score an artifact against the meta-judge's evaluation specification with quoted evidence, then defend or revise scores across up to 3 debate rounds until the panel reaches consensus. Writes only its own judge-N report file per dispatch. Never judges outside the specification, never revises without quoted evidence.
 license: MIT
 metadata:
   author: S1LV4, luizgmassa
-  version: "1.1.0"
+  version: "1.2.0"
   model_tier: deep
-  permission: read-only
+  permission: write
 ---
 
 # Judge Agent Skill

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
@@ -80,6 +80,8 @@ Before reading any massa-ai file:
   requirement meaning, scope boundaries, destructive/irreversible choices,
   contradictory evidence — ask the user rather than choose silently. Facts
   are looked up; decisions are asked.
+- Before writing or changing implementation code, load
+  `references/coding-guidelines.md` if not already loaded.
 - Complete Evidence Gate before claiming done.
 
 Use internal references only when needed:
@@ -164,6 +166,9 @@ 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` |
 | `general` | coding work with no more specific workflow | `workflows/general.md` |
 
@@ -176,8 +181,8 @@ match or no match is resolved deterministically without asking.
 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, or FURPS refinement report.
-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`.
+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`; 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/agent-orchestration.md

@@ -148,7 +148,7 @@ only, never a dispatch target.
 
 ## Capability Packet
 
-**This section is the sole canonical Capability Packet definition.** `references/subagent-design.md` and the root `skills/AGENTS.md` registry defer to or mirror this list; `scripts/__tests__/capability-packet-parity.test.ts` fails when the `skills/AGENTS.md` mirror diverges. Bespoke packets (judge panel, FURPS analyst, phase-batch worker) are declared specializations that map onto these fields in their own workflow files.
+**This section is the sole canonical Capability Packet definition.** `references/subagent-design.md` mirrors this list and the root `skills/AGENTS.md` registry points here without restating it. Bespoke packets (judge panel, FURPS analyst, phase-batch worker) are declared specializations that map onto these fields in their own workflow files.
 
 **A subagent inherits nothing from the parent session** — no skills, no personas, no loaded references, no conversation history. Everything the subagent needs is named explicitly in the packet, including the exact reference file paths it must read itself.