@massa-ai/cursor-plugin 1.24.0 → 1.26.0

package/skills/persona-router/references/routing-details.md

@@ -0,0 +1,98 @@
+# Persona Routing Details
+
+Load this reference from `SKILL.md` only when one of its load conditions fires:
+a failure needs reporting, ambiguity needs a user question, a mid-conversation
+reroute is in doubt, or the user requests multiple personas. Routing itself
+runs from `SKILL.md` alone.
+
+## Persona ↔ Sub-Agent Overlap
+
+Four catalog entries deliberately overlap an agent charter. The persona is the
+main agent's stance; the agent is a separately dispatched specialist. Applying
+one never implies the other ran.
+
+| Persona | Overlapping agent |
+|---|---|
+| `senior-mobile-engineer` | `massa-ai-mobile-specialist` |
+| `senior-mobile-qa-automation-engineer` | `massa-ai-test-engineer` |
+| `context-skill-harness-engineer-architect` | `massa-ai-architecture-specialist` |
+| `product-manager` | `massa-ai-requirements-analyst` |
+
+## Multi-Persona Requests
+
+If multiple personas are explicitly requested, the persona owning the primary
+deliverable leads and at most one other becomes a review lens. Apply the
+ambiguity policy if ownership remains unclear. The review lens contributes only
+checks that reduce a concrete risk; never produce independent persona answers,
+simulate a debate, or merge full voices.
+
+## Ambiguity And No-Match Behavior
+
+When two or more candidates remain genuinely plausible:
+
+- `ambiguity: ask` — ask one concise question listing the plausible persona
+  display names and `No persona`. Use an interactive user-input tool when
+  available; otherwise ask in plain text.
+- `ambiguity: best_match` — choose the strongest current-deliverable owner,
+  then project-specific evidence, then recent valid memory.
+- `ambiguity: no_persona` — continue without a persona.
+
+When no catalog entry fits:
+
+- `no_match: no_persona` — continue silently unless the user explicitly
+  requested routing.
+- `no_match: ask` — ask about the weakly supported candidate versus
+  `No persona`; with no supported candidate, ask only about `No persona`
+  versus an explicitly named catalog choice.
+
+Do not ask when the request confidently falls outside every cataloged persona —
+that is a successful no-persona route, not ambiguity.
+
+## Route Lifetime Detail
+
+With `mid_conversation: task_change`, re-evaluate only when the user explicitly
+switches, the primary deliverable changes ownership, a new task begins after
+completion, or the selected catalog entry becomes invalid. With
+`explicit_only`, re-evaluate only on explicit request. Do not reroute because a
+follow-up adds a supporting concern, asks for verification, or mentions another
+persona's terminology. If a task change creates genuine ambiguity and policy
+says `ask`, ask before substantive work continues. After resume or compaction,
+restore any route still present in conversation context without re-announcing
+it or repeating a resolved question; if unavailable, run the normal workflow
+again — no separate route database exists.
+
+## Routing Examples
+
+| Situation | Result |
+|---|---|
+| User explicitly asks for Senior Mobile QA Automation Engineer. | Apply that entry; explicit choice wins. |
+| Project `AGENTS.md` pins a valid catalog id. | Pin fast path: read only that prompt; no recall, docs, signals, or classification. |
+| Pin names an id absent from the catalog. | One-line invalid-pin report; continue with the normal workflow. |
+| Memory recalls a successful route, current prompt asks to fix flaky Maestro CI. | Route to Senior Mobile QA Automation Engineer; memory cannot override current ownership. |
+| Memory empty; docs describe a cross-platform app; prompt asks to implement offline sync. | Route to Senior Mobile Engineer from docs plus current deliverable. |
+| Prompt asks for both app architecture and an automation suite, no primary outcome. | Follow `ambiguity`; default asks between plausible personas and no persona. |
+| Prompt asks to draft a billing RFC. | Confident no-match; continue silently without a persona. |
+| `enabled: off` and prompt names no persona. | Skip inference; continue without a persona. |
+| Memory names a removed persona id. | Discard stale memory; continue to docs and classification. |
+| Mobile implementation finishes; user starts a flake-reduction task. | With `task_change`, re-evaluate and announce the new route once. |
+
+## Failure Handling Table
+
+- **Catalog missing or invalid:** report `Persona routing unavailable:
+  <reason>.` Continue without a persona.
+- **Unsupported schema version:** report found and supported versions.
+  Continue without a persona.
+- **massa-ai unavailable or empty:** continue with targeted workspace
+  documentation and the current prompt; skip route-memory reads and writes.
+- **Workspace documentation unavailable:** route from explicit choice, pin,
+  and current prompt; apply the ambiguity or no-match policy.
+- **Remembered persona absent from catalog:** ignore it as stale evidence;
+  never reconstruct it.
+- **Selected prompt missing, outside the persona-library root, or malformed:**
+  name the catalog entry and path. Continue without a persona; never silently
+  substitute another persona.
+- **Signals file missing during classification:** report the entry and path;
+  the candidate stays matchable by summary and aliases.
+- **User cannot be asked interactively:** ask one concise plain-text question
+  when policy requires a choice; otherwise use the configured non-interactive
+  behavior.

package/skills/profile/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: profile
+description: Switch the installed massa-ai agents to a registry model profile (e.g. "work", "cheap", "home") or report the currently active profile per host. Use when the user asks to change/switch the model profile, asks which models the agents currently use, or asks to preview a profile switch. Do NOT use for editing the model registry itself (a registry edit is a massa-ai repository change, not a runtime switch) and do NOT claim the new profile is active before the user restarts the host session.
+license: MIT
+metadata:
+  author: Luiz Massa
+  version: 1.0.0
+---
+
+# Profile Switch Skill
+
+## Mission
+Drive the one massa-ai model-profile switch engine and relay its report — never a second implementation.
+
+## When To Use
+- The user asks to switch, change, or set the model profile (by name, e.g. "work", "cheap", "home", "balanced").
+- The user asks what profile is currently active, or which profiles are shipped.
+- The user asks to preview a switch without applying it.
+
+## How To Drive It
+There is exactly one switch implementation (`@massa-ai/shared`'s switch engine); every front — this skill, the MCP tools, and both `massa-ai-config` CLIs — calls the same engine and returns the same per-host report shape. Prefer whichever front is already available in the session:
+
+- **MCP tools** (preferred when the massa-ai MCP server is connected): call `profile_list` to report shipped profiles + per-host active profile + bundle version, and `profile_set` to switch (`{profile, host?, dryRun?}`).
+- **CLI fallback**: `massa-ai-config profile list` / `massa-ai-config profile show` / `massa-ai-config profile set <name> [--host <h>] [--dry-run]`.
+
+Default to a dry run first when the user has not explicitly asked to apply the switch immediately — `dryRun: true` (MCP) or `--dry-run` (CLI) previews the per-host plan and changes nothing.
+
+## Relaying The Result
+Always relay the per-host outcome and the restart notice verbatim in substance, not just "done":
+
+- Report each host as switched / skipped (with its reason) / unsupported (with its reason) / failed (with its reason). Cursor is always reported skipped — every tier resolves to inherit, so switching it is a no-op by design, not an error.
+- When at least one host switched (non-dry-run), state explicitly that a session restart of that host is required before the new models take effect — hosts load agent definitions at session start; there is no live in-session switch.
+- On a dry run, say so and that no files changed.
+- On a fully failed request (e.g. unknown profile name), relay the named error and the list of profiles the report says are actually available — never guess a profile name.
+
+## Restrictions
+- Never invent a profile name; only use names the engine's own report lists as shipped/available.
+- Never claim a profile switch is "live" before the affected host's session restarts.
+- Never edit the model-profile registry (`skills/model-profiles.json`) to satisfy a switch request — that is a build-time registry change owned by a different workflow, not a runtime switch.