@massa-ai/cursor-plugin 1.6.0

package/install.sh

@@ -0,0 +1,413 @@
+#!/usr/bin/env bash
+#
+# massa-ai Cursor plugin installer
+#
+# Copies the plugin bundle (skills, hooks.json, agents, optional manifest,
+# binary symlink) into the user's or project's Cursor config directory and
+# merges the 7 massa-ai hook events into ~/.cursor/hooks.json (or
+# ./.cursor/hooks.json) using an array-append merge that preserves existing
+# user hooks.
+#
+# 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.
+#
+# Idempotent: re-running is a no-op when owned entries already present.
+# Uninstall removes only ownership-marked entries + the plugin directory.
+#
+# Usage:
+#   apps/cursor-plugin/install.sh             # install at user scope (~/.cursor)
+#   apps/cursor-plugin/install.sh --user      #   (same)
+#   apps/cursor-plugin/install.sh --project  # install at project scope (./.cursor)
+#   apps/cursor-plugin/install.sh --uninstall # remove owned entries + plugin dir
+#   apps/cursor-plugin/install.sh -h|--help   # show this help
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CLAUDE_PLUGIN_BIN="$REPO_ROOT/apps/claude-plugin/hooks/massa-ai-hook.ts"
+
+SCOPE="user"
+UNINSTALL=0
+DRY_RUN=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --user) SCOPE="user" ;;
+    --project) SCOPE="project" ;;
+    --uninstall) UNINSTALL=1 ;;
+    --quiet) MASSA_AI_VERBOSE=0 ;;
+    --verbose) MASSA_AI_VERBOSE=1 ;;
+    --dry-run) DRY_RUN=1; MASSA_AI_VERBOSE=1 ;;
+    -h|--help)
+      sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *) echo "Unknown flag: $arg" >&2; exit 2 ;;
+  esac
+done
+
+# Banner
+source "$SCRIPT_DIR/../../scripts/banner.sh"
+massa_ai_banner
+
+# Resolve target base dir
+if [[ "$SCOPE" == "project" ]]; then
+  CURSOR_DIR="$(pwd)/.cursor"
+else
+  CURSOR_DIR="$HOME/.cursor"
+fi
+PLUGIN_DIR="$CURSOR_DIR/plugins/massa-ai"
+HOOKS_JSON="$CURSOR_DIR/hooks.json"
+
+# 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>": [...] } }
+massa_ai_event_entry() {
+  local subcommand="$1"
+  cat <<JSON
+{ "command": "$PLUGIN_DIR/hooks/massa-ai-hook $subcommand", "_massaAiOwned": true }
+JSON
+}
+
+# Array-append merge (F5 mitigation): for each of the 7 events, append the
+# massa-ai hook entry to the event's array inside the nested "hooks"
+# object if no entry with _massaAiOwned: true already exists. Preserves
+# the top-level "version" field (defaults to 1). Backup before first write.
+# Uses node (preferred) or bun for safe JSON manipulation.
+merge_hooks_json() {
+  local file="$1"
+  local mode="$2" # "install" or "uninstall"
+  local ts
+  ts="$(date +%Y%m%d%H%M%S)"
+
+  local runner=""
+  if command -v node &>/dev/null; then
+    runner="node"
+  elif command -v bun &>/dev/null; then
+    runner="bun"
+  else
+    echo "Error: node or bun required to merge hooks.json (JSON manipulation)" >&2
+    exit 3
+  fi
+
+  "$runner" - "$file" "$mode" "$ts" "$PLUGIN_DIR" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+
+const file = process.argv[2];
+const mode = process.argv[3];
+const ts = process.argv[4];
+const pluginDir = process.argv[5];
+
+const EVENTS = [
+  ["sessionStart", "session-start"],
+  ["sessionEnd", "stop"],
+  ["beforeSubmitPrompt", "user-prompt-submit"],
+  ["preToolUse", "pre-tool-use"],
+  ["postToolUse", "post-tool-use"],
+  ["preCompact", "pre-compact"],
+  ["stop", "stop"],
+];
+
+let cfg = {};
+let existed = false;
+try {
+  const raw = fs.readFileSync(file, "utf8");
+  if (raw.trim()) {
+    cfg = JSON.parse(raw);
+    existed = true;
+  }
+} catch (e) {
+  if (e.code === "ENOENT") {
+    // no file — start empty
+  } else {
+    throw e;
+  }
+}
+
+// Ensure the nested hooks object + version field
+if (typeof cfg.version !== "number") cfg.version = 1;
+if (typeof cfg.hooks !== "object" || cfg.hooks === null) cfg.hooks = {};
+
+const hooks = cfg.hooks;
+
+function hasOwned(arr) {
+  return Array.isArray(arr) && arr.some((e) => e && e._massaAiOwned === true);
+}
+
+if (mode === "uninstall") {
+  for (const [evt] of EVENTS) {
+    if (Array.isArray(hooks[evt])) {
+      hooks[evt] = hooks[evt].filter((e) => !(e && e._massaAiOwned === true));
+      if (hooks[evt].length === 0) delete hooks[evt];
+    }
+  }
+} else {
+  // install: backup before first write if file existed
+  if (existed) {
+    const bak = `${file}.massa-ai.bak-${ts}`;
+    fs.copyFileSync(file, bak);
+  }
+  for (const [evt, sub] of EVENTS) {
+    if (!Array.isArray(hooks[evt])) hooks[evt] = [];
+    if (!hasOwned(hooks[evt])) {
+      hooks[evt].push({
+        command: `${pluginDir}/hooks/massa-ai-hook ${sub}`,
+        _massaAiOwned: true,
+      });
+    }
+  }
+}
+
+fs.mkdirSync(path.dirname(file), { recursive: true });
+fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+NODE
+}
+
+# ── Skills bundling (PDO-08, 09 / D3 two-writer ownership) ──────────────────
+# scripts/install-skills.sh remains the single writer once it has already
+# claimed this platform (skillsOwner: "repo" in the shared install-state.json).
+# This plugin installs its bundled massa-ai/persona-router skills into the
+# SAME harness skills directory ($CURSOR_DIR/skills — NOT $PLUGIN_DIR/skills,
+# which is this plugin's own registerPath-discovered skill cache) only when
+# that has not happened, mirroring the MCP single-writer precedent
+# (test-mcp-single-writer.sh). A repo checkout's own --apply always takes
+# precedence over a prior plugin install — see install-skills.sh.
+HARNESS_STATE_FILE="$HOME/.config/massa-ai/install-state.json"
+HARNESS_SKILLS_DIR="$CURSOR_DIR/skills"
+HARNESS_HOST="cursor"
+
+harness_skills_owner() {
+  local runner="$1"
+  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" <<'NODE'
+const fs = require("fs");
+const [, , file, host] = process.argv;
+try {
+  const data = JSON.parse(fs.readFileSync(file, "utf8"));
+  const rec = data && data.platforms && data.platforms[host];
+  process.stdout.write(rec && rec.skillsOwner === "repo" ? "repo" : "none");
+} catch {
+  process.stdout.write("none");
+}
+NODE
+}
+
+install_bundled_skills() {
+  local runner=""
+  if command -v node &>/dev/null; then runner="node"
+  elif command -v bun &>/dev/null; then runner="bun"
+  else
+    echo "  ⚠ node or bun required to install bundled skills — skipping" >&2
+    return 0
+  fi
+
+  if [[ "$(harness_skills_owner "$runner")" == "repo" ]]; then
+    vecho "  ↷ skills already installed by scripts/install-skills.sh (repo-owned) — skipping bundled copy"
+    return 0
+  fi
+
+  local installed=0 name src dest
+  for name in massa-ai persona-router; do
+    src="$SCRIPT_DIR/skills/$name"
+    [[ -d "$src" ]] || continue
+    dest="$HARNESS_SKILLS_DIR/$name"
+    if [[ -e "$dest" && ! -d "$dest" ]]; then
+      echo "  ⚠ $dest exists and is not a directory — skipping" >&2
+      continue
+    fi
+    mkdir -p "$HARNESS_SKILLS_DIR"
+    rm -rf "$dest"
+    cp -R "$src" "$dest"
+    installed=$((installed + 1))
+  done
+  vecho "  + ${installed} harness skills installed to $HARNESS_SKILLS_DIR (plugin-owned)"
+
+  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" "$CURSOR_DIR" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+const [, , file, host, root] = process.argv;
+let data = { version: 2, platforms: {} };
+try {
+  const existing = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) data = existing;
+} catch { /* fresh */ }
+if (typeof data.platforms !== "object" || data.platforms === null || Array.isArray(data.platforms)) {
+  data.platforms = {};
+}
+data.version = 2;
+data.platforms[host] = { root, skillsOwner: "plugin", skills: ["massa-ai", "persona-router"] };
+fs.mkdirSync(path.dirname(file), { recursive: true });
+fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+NODE
+}
+
+uninstall_bundled_skills() {
+  local runner=""
+  if command -v node &>/dev/null; then runner="node"
+  elif command -v bun &>/dev/null; then runner="bun"
+  else return 0
+  fi
+
+  local raw_owner
+  raw_owner="$("$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" <<'NODE'
+const fs = require("fs");
+const [, , file, host] = process.argv;
+try {
+  const data = JSON.parse(fs.readFileSync(file, "utf8"));
+  const rec = data && data.platforms && data.platforms[host];
+  process.stdout.write(rec ? String(rec.skillsOwner) : "none");
+} catch {
+  process.stdout.write("none");
+}
+NODE
+  )"
+  [[ "$raw_owner" == "plugin" ]] || return 0
+
+  local name
+  for name in massa-ai persona-router; do
+    rm -rf "$HARNESS_SKILLS_DIR/$name"
+  done
+  rmdir "$HARNESS_SKILLS_DIR" 2>/dev/null || true
+  echo "  - removed plugin-owned harness skills from $HARNESS_SKILLS_DIR"
+
+  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" <<'NODE'
+const fs = require("fs");
+const [, , file, host] = process.argv;
+try {
+  const data = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (data && data.platforms && data.platforms[host] && data.platforms[host].skillsOwner === "plugin") {
+    delete data.platforms[host];
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+  }
+} catch { /* nothing to clean up */ }
+NODE
+}
+
+# ── Uninstall ───────────────────────────────────────────────────────────────
+if [[ "$UNINSTALL" -eq 1 ]]; then
+  echo "Uninstalling massa-ai Cursor plugin (scope: $SCOPE)..."
+  uninstall_bundled_skills
+  # Remove owned hook entries (preserves user hooks)
+  if [[ -f "$HOOKS_JSON" ]]; then
+    merge_hooks_json "$HOOKS_JSON" "uninstall"
+    echo "  - removed massa-ai hook entries from $HOOKS_JSON"
+  fi
+  # Remove plugin directory
+  if [[ -d "$PLUGIN_DIR" ]]; then
+    rm -rf "$PLUGIN_DIR"
+    echo "  - removed $PLUGIN_DIR"
+  fi
+  echo ""
+  echo "Done. User hooks preserved."
+  exit 0
+fi
+
+# ── Install ──────────────────────────────────────────────────────────────────
+vecho "Installing massa-ai Cursor plugin to: $PLUGIN_DIR"
+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
+
+# 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
+
+# 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
+for src in "$SCRIPT_DIR/agents/"massa-ai-*.md; do
+  [[ -f "$src" ]] || continue
+  name="$(basename "$src")"
+  cp "$src" "$PLUGIN_DIR/agents/$name"
+  vecho "  + $name"
+  specialist_count=$((specialist_count + 1))
+done
+vecho "  + ${specialist_count} subagent specialists (generated from skills/agents/*/SKILL.md)"
+
+# 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.
+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
+
+# 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)"
+
+# ── MCP registration (delegated) ─────────────────────────────────────────────
+# scripts/install-agents.sh is the single writer of host MCP config. It writes
+# the massa-ai entry into ~/.cursor/mcp.json at USER scope — a --project plugin
+# install still registers MCP for the whole user.
+vecho ""
+vecho "Registering MCP server (user scope) via scripts/install-agents.sh..."
+if [[ -f "$REPO_ROOT/scripts/install-agents.sh" ]]; then
+  # On success the delegated output is detail (usually "up to date"), so it is
+  # gated. On failure it is never gated: a silently-failed MCP registration is
+  # exactly the bug this change set exists to fix.
+  if agents_out="$(MASSA_AI_SUPPRESS_SPECIALIST_HINT=1 bash "$REPO_ROOT/scripts/install-agents.sh" --agent cursor --yes 2>&1)"; then
+    vecho "$agents_out"
+  else
+    echo "$agents_out" >&2
+    echo "  ⚠ MCP wiring failed — run: bash scripts/install-agents.sh --agent cursor --yes" >&2
+  fi
+else
+  echo "  ⚠ scripts/install-agents.sh not found — register MCP with: bash scripts/install-agents.sh --agent cursor --yes" >&2
+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)"
+else
+  vecho ""
+  vecho "Done. Restart Cursor to pick up the plugin."
+  vecho "💡 MCP is registered in ~/.cursor/mcp.json by scripts/install-agents.sh (single writer)."
+fi

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@massa-ai/cursor-plugin",
+  "version": "1.6.0",
+  "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
+  "files": [
+    "agents",
+    "hooks",
+    "skills",
+    "install.sh",
+    "README.md",
+    ".cursor-plugin/plugin.json"
+  ],
+  "author": "luizgmassa",
+  "keywords": [
+    "cursor",
+    "plugin",
+    "massa-ai",
+    "semantic-search",
+    "code-search",
+    "memory",
+    "context-compression",
+    "ai",
+    "llm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luizgmassa/massa-ai"
+  }
+}

package/skills/agents/architecture-specialist/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: architecture-specialist
+description: Read-only architecture guidance agent. Evaluate architecture, suggest boundaries, recommend abstractions, evaluate trade-offs, and suggest modularization. Folds the existing domain-mapper, coupling-auditor, and deepening-architect roles into one specialist. Triggers when a workflow needs architectural guidance before or during design. Never implements or rewrites code.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: MiniMax M3
+  permission: read-only
+---
+
+# Architecture Specialist Agent Skill
+
+## Mission
+Provide architectural guidance by evaluating structure, suggesting boundaries, and weighing trade-offs.
+
+## Responsibilities
+- Evaluate architecture (layering, boundaries, coupling, depth).
+- Suggest module boundaries and seams.
+- Recommend abstractions where duplication or volatility warrants them.
+- Evaluate trade-offs between approaches.
+- Suggest modularization for shallow or over-coupled modules.
+
+## Restrictions
+- Never implement.
+- Never rewrite code.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: the module, service, or area under evaluation.
+- `inputs`: recalled facts, source pointers, existing architecture docs.
+- `sensors`: static coupling/depth metrics when available.
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: modules and boundaries evaluated
+- Evidence: `path:line` pointers, coupling/depth metrics, source locations
+- Findings: boundary suggestions, abstraction recommendations, trade-off analysis, modularization plan
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow needs architectural guidance before or during design.
+- The work crosses module or service boundaries.
+- The user asks for architecture evaluation, coupling analysis, or modularization.
+
+### Do not use when
+- The work is a single-file fix with no architectural surface.
+- The task needs a concrete implementation (route to builder).
+- An audit-specific lens is needed (route to audit-specialist with `lens: architecture`).
+
+## massa-ai Integration
+- Context Firewall: summarize source reads; return findings and metrics, not raw code.
+- Verification Ladder: static (coupling, depth, boundary) checks; no behavioral changes.
+- Massa-ai Memory: suggest durable architecture-decision memories only when a boundary or abstraction is recommended; main agent persists.
+- Synapse: own ephemeral session when evaluation spans multiple modules with repeated searches.
+- References: `references/architecture-lenses.md`, `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, `references/architecture-deepening-lens.md`.
+
+## Model Hint
+MiniMax M3 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every finding has a `path:line` or metric pointer.
+- Trade-offs name at least two alternatives.
+- Boundary suggestions reference concrete modules.
+
+## Memory Boundary
+Suggest durable memories only when an architectural boundary or abstraction is recommended and accepted. The main agent persists. Do not persist one-off evaluation chatter.

package/skills/agents/audit-specialist/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: audit-specialist
+description: Configurable read-only audit agent. Execute specialized audits through six lenses — bugs, architecture, security, requirements, code-quality, performance — selected via the lens field in the capability packet. Triggers when a workflow needs a findings-only audit. Never modifies implementation.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: GLM-5.2
+  permission: read-only
+---
+
+# Audit Specialist Agent Skill
+
+## Mission
+Execute a specialized audit through one configurable lens and return findings-only output.
+
+## Responsibilities
+- Execute the audit checklist for the selected lens.
+- Tie every finding to a `path:line` source location.
+- Rank findings by severity.
+- Produce a findings report following the project audit-report format.
+
+## Restrictions
+- Never modify implementation.
+- One lens per dispatch; do not mix lenses in one run.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Lenses
+
+The `lens` field in the capability packet selects the audit behavior:
+
+| Lens | Focus | Per-lens references |
+|---|---|---|
+| `bugs` | Bug discovery: null paths, error handling, race conditions, logic errors | `workflows/bugs/bugs-audit.md` |
+| `architecture` | DDD, boundaries, coupling, module depth, seams | `references/architecture-lenses.md`, `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, `references/architecture-deepening-lens.md` |
+| `security` | Security, privacy, auth, validation, secret handling | `workflows/security/security-audit.md` |
+| `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
+| `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
+| `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+
+All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
+
+## Inputs
+- `scope`: the target area, diff, or module to audit.
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `inputs`: recalled facts, existing audit reports, source pointers.
+- `sensors`: static checks available for the lens (lint, typecheck, security scanners).
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: area audited + lens used
+- Evidence: `path:line` pointers, static-check results, source locations
+- Findings: ranked list (severity, location, problem, suggestion) in the project audit-report format
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow needs a findings-only audit of an implementation target.
+- The user asks for a bug, architecture, security, requirements, code-quality, or performance audit.
+- A high/critical finding needs independent verification.
+
+### Do not use when
+- The task needs a fix (route to the matching `*-fix` workflow or builder).
+- No concrete target exists to audit.
+- The lens is ambiguous (ask the user to pick one).
+
+## massa-ai Integration
+- Context Firewall: summarize the audit scope; return findings, not raw source dumps.
+- Verification Ladder: static checks per lens; no behavioral changes (findings-only).
+- Massa-ai Memory: suggest durable audit-pattern memories only when a lens reveals a recurring issue class; main agent persists.
+- Synapse: own ephemeral session when the audit spans multiple modules with repeated searches.
+- References: `references/audit-scope.md`, `references/audit-report-io.md`, plus the per-lens references above.
+
+## Model Hint
+GLM-5.2 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every finding has a `path:line` pointer.
+- Findings follow the project audit-report format (`references/audit-report-io.md`).
+- Severity is assigned per the lens rubric.
+- No fix actions taken (findings-only).
+
+## Memory Boundary
+Suggest durable memories only when a lens reveals a recurring issue class worth remembering. The main agent persists. Do not persist the audit report itself (it lives in `.specs/`).

package/skills/agents/builder/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: builder
+description: Write-permitted implementation agent. Implement approved plans by modifying source code, creating files, and updating existing code while following project conventions. Triggers when a workflow has an approved plan or task with a disjoint write set. Never redesigns architecture, performs reviews, or generates implementation plans.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: GLM-5.2
+  permission: write
+---
+
+# Builder Agent Skill
+
+## Mission
+Implement an approved plan or task by modifying source code with a disjoint write set.
+
+## Responsibilities
+- Modify source code per the approved plan.
+- Create new files when the plan requires them.
+- Update existing code following project conventions.
+- Run the task's verification sensors before claiming completion.
+
+## Restrictions
+- Never redesign architecture.
+- Never perform reviews.
+- Never generate implementation plans.
+- Never write outside the assigned disjoint write set.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: exact files and modules to modify (disjoint write set).
+- `inputs`: the approved plan or task, recalled facts, source pointers.
+- `permissions`: write with disjoint write set.
+- `sensors`: verification commands (tests, build, typecheck, lint).
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: files changed
+- Evidence: command results (tests, build, typecheck), diff summary
+- Findings: implementation summary
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow has an approved plan or task.
+- The write set is disjoint from other active agents.
+- The task has concrete verification sensors.
+
+### Do not use when
+- No plan or task is approved.
+- The write set overlaps another active agent.
+- The task needs architectural decisions (route to architecture-specialist or planner first).
+
+## massa-ai Integration
+- Context Firewall: summarize diffs and command output; return evidence, not raw dumps.
+- Verification Ladder: run the task's sensors (static + behavioral) before claiming Complete.
+- Massa-ai Memory: suggest durable code-pattern memories only when the implementation establishes a reusable convention; main agent persists.
+- Synapse: none (implementation is not a repeated-search task).
+- References: `references/agent-orchestration.md`, `references/naming-standards.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
+
+## Model Hint
+GLM-5.2 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Verification commands from the plan pass (tests, build, typecheck, lint).
+- Diff stays within the assigned write set.
+- No validation assets weakened (tests, specs, fixtures, snapshots).
+
+## Memory Boundary
+Suggest durable memories only when the implementation establishes a reusable code pattern or convention. The main agent persists. Do not persist one-off implementation details.