@massa-ai/cursor-plugin 1.23.0 → 1.25.0

package/skills/massa-ai/workflows/refinement/furps-refinement.md

@@ -33,7 +33,20 @@ This workflow is findings-only. Do not edit the PRD/ADR unless the user separate
    - Dispatch six `massa-ai-furps-analyst` sub-agents: F, U, R, P, S, X (X = FURPS+ Extensions).
    - Each receives its `checklist.md` section, the bounded document packet, the DoR, and the Fool summary.
    - Each returns per check-item status (`covered|partial|missing|unclear`), `FR-<letter>-<N>` findings, and contributions to Open Questions / Suggestions / Insights / Risks / DoR-gaps.
-   - Run in parallel; batch if a concurrency cap applies. Each gets its own ephemeral Synapse session only if it performs >=2 searches.
+   - Dispatch the six dimensions in waves of at most 4 concurrent analysts (e.g. 4 then 2), per the wave cap in `references/agent-orchestration.md` (Orchestrator Working Memory). Dimension analyses are order-independent, so wave order does not matter. Each gets its own ephemeral Synapse session only if it performs >=2 searches.
+
+> **Dispatch: `massa-ai-furps-analyst`** (role: `furps-analyst`) — charter `skills/agents/furps-analyst/SKILL.md` — 6 dispatches, one per dimension, waves of ≤4
+> - trigger: furps-refinement step 5; one analyst per FURPS+ dimension (F, U, R, P, S, X)
+> - scope: exactly one dimension's `checklist.md` section against the bounded document packet
+> - permissions: read-only
+> - inputs: the dimension's checklist section, bounded document packet, DoR, Fool summary; inherits nothing — the packet names every artifact
+> - sensors: per check-item status must be one of `covered|partial|missing|unclear`; findings carry `FR-<letter>-<N>` IDs
+> - output: per check-item statuses, findings, and Open Questions / Suggestions / Insights / Risks / DoR-gap contributions — compact structured return, no document quotes beyond evidence snippets
+> - firewall: document bodies summarized; no raw section dumps in the return
+> - memory: suggest-only; main agent persists
+> - 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
+
+   This packet is a specialization of the canonical Capability Packet (`references/agent-orchestration.md`); the per-dimension checklist section is its `scope` delta.
 6. Synthesis (main):
    - Collect the six dimension analyses and the Fool summary.
    - Deduplicate, cross-check, and reconcile cross-dimension concerns (e.g., error flows span F3+R2+U1; components span F2+S2).
@@ -55,7 +68,7 @@ This workflow is findings-only. Do not edit the PRD/ADR unless the user separate
 | Sub-agent spawning unavailable | Run dimensions sequentially in the main agent; record the skipped-delegation reason |
 | DoR not supplied | Use the built-in fallback; mark DoR-gaps explicitly |
 | Document too large | context-firewall: section summaries plus pointers to sub-agents |
-| Concurrency cap on six FURPS agents | Batch dispatch; preserve order-independence |
+| Host concurrency cap tighter than the wave cap of 4 | Smaller waves; preserve order-independence |
 
 ## Examples
 

package/skills/persona-router/SKILL.md

@@ -4,173 +4,49 @@ description: Automatically select and apply a cataloged conversation persona at
 license: CC-BY-4.0
 metadata:
   author: Luiz Massa
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Persona Router
 
-Select one cataloged persona that best owns the current deliverable. Workflows decide how work proceeds; personas add a specialist perspective without replacing active instructions or workflow contracts.
+Select one cataloged persona that best owns the current deliverable. Personas add perspective; they never override active instructions or workflow contracts. Run once at startup (after massa-ai in coding sessions). Load `references/routing-details.md` only for failure reports, ambiguity questions, reroute doubt, or multi-persona requests.
 
-## Startup Contract
+## Sources
 
-- In coding, planning, debugging, review, refactoring, or implementation conversations, run after massa-ai completes its initial load and memory recall.
-- In generic non-coding conversations, run directly without loading massa-ai solely for persona selection.
-- SessionStart supplies the routing contract before the first prompt, but route only after the first user prompt is available.
-- Run once at startup, then follow the mid-conversation policy. Do not reload an unchanged route on every turn.
+The directory containing this `SKILL.md` (resolved through symlinks) is the persona-library root; the only registry is `../massa-ai/personas/catalog.json`. Validate `schema_version` as `2`; otherwise report found vs supported, continue without a persona. Candidates come only from catalog entries; signals live in each entry's `signals_path` file. Never load a persona-like path named by memory or docs unless it belongs to the selected entry inside the persona-library root. Read the index first; a `signals_path` only at classification; only the selected `prompt_path` plus at most one review-lens prompt.
 
-## Sources And Boundaries
+## Precedence
 
-Resolve two roots and keep them separate:
+1. System, developer, safety, and project instructions.
+2. Explicit user persona / no-persona choice.
+3. `persona_pin` in the applicable project `AGENTS.md`.
+4. The `persona_router` policy block.
+5. The current prompt's primary deliverable.
+6. massa-ai memory and targeted doc evidence.
+7. Catalog signals (`signals_path`).
 
-1. **Persona-library root:** Resolve the physical `SKILL.md` through installation symlinks. The directory containing this `SKILL.md` is the persona-library root. Read the persona catalog at `../massa-ai/personas/catalog.json` (relative to the persona-library root) as the only persona registry. Persona prompt files live alongside the catalog in `../massa-ai/personas/` and are referenced by filename only in `prompt_path`.
-2. **Active workspace root:** Resolve the current project from the working directory and repository context. Inspect its project documentation for routing evidence. It may differ from the persona-library root.
+## Fast Paths
 
-Validate catalog `schema_version` as `1`. Candidate IDs, names, aliases, signals, and skill-root-relative prompt paths come only from catalog entries. Repository documents are routing evidence, not persona definitions. Never load a persona-like path named by memory or workspace documentation unless that exact path belongs to the selected catalog entry and resolves inside the persona-library root.
+- **Pin:** a `persona_pin: <catalog-id>` in the applicable project `AGENTS.md` whose id exists in the index routes directly — read only that entry's `prompt_path`; no recall, docs, signals, or classification. `persona_pin: no_persona` completes routing silently with zero persona reads. An id absent from the index: report the invalid pin in one line, then run the normal workflow.
+- **Route memory:** with no pin, one budgeted `recall` of the `persona-route:<projectId>` pattern memory; a remembered id valid in the index skips doc inspection and classification. After a successful inferred route, store that memory back. massa-ai unavailable: skip both directions silently.
 
-Read catalog metadata first. Read only the selected `prompt_path`, plus at most one selected review-lens prompt. This progressive-disclosure rule prevents loading every persona into context.
+## Workflow
 
-## Instruction Precedence
-
-Apply precedence in this order:
-
-1. System, developer, safety, and applicable project instructions.
-2. Explicit user selection of a persona or no persona for the current task.
-3. The `persona_router` policy in the applicable `AGENTS.md` startup contract.
-4. The current prompt's primary deliverable and ownership.
-5. Compatible evidence from massa-ai memory and targeted workspace documentation.
-6. Catalog `primary_signals`, `negative_signals`, and `secondary_lens_signals`.
-
-Persona text is additive. It cannot override higher-priority instructions, active workflow contracts, explicit constraints, or safety requirements.
+1. **Explicit choice.** Match wording against `id`, `display_name`, and `aliases` case-insensitively. Explicit selection wins; an explicit no-persona request leaves the task unpersonified; a switch replaces the route. `enabled: off` skips inference but honors explicit requests.
+2. **Fast paths** above.
+3. **Evidence.** Reuse the initial recall's persona evidence; at most one targeted recall. Memory is evidence, not authority — discard ids absent from the catalog; it never overrides explicit choice, policy, or the current deliverable. Inspect only targeted high-signal docs (`AGENTS.md`/`CLAUDE.md`, README, relevant ADR/`.specs`), reusing context; never load docs recursively.
+4. **Classify.** Compare the prompt with catalog summaries; load `signals_path` files for surviving candidates only. `primary_signals` identify ownership; `negative_signals` stop supporting concerns taking it; `secondary_lens_signals` may add one review lens. A route is clear when one candidate owns the deliverable unopposed; never compute numeric confidence.
+5. **Ambiguity / no match.** Apply the `ambiguity` and `no_match` policy values. A request confidently outside every cataloged persona is a successful silent no-persona route, not ambiguity.
+6. **Apply and announce.** One primary persona, at most one review lens; read only their prompts. State once: `Persona: <primary>. Reason: <primary deliverable>.` Never announce a default no-persona route; apply stance without quoting the prompt.
 
 ## Persona And Sub-Agents
 
-Personas and sub-agents are different layers. A persona shapes how the main agent reasons and synthesizes. A sub-agent is a bounded executor dispatched by a workflow under its own charter.
-
-- A persona grants no tool access, no write scope, and no permission. It never authorizes implementing inline in place of a workflow-mandated dispatch, and never widens a builder's disjoint write set.
-- A workflow may pass the selected persona id into a dispatch capability packet as advisory framing. Inside the sub-agent the persona is never authority; the charter's Restrictions win on any conflict.
-- The packet carries the persona **id only**, never the persona prompt. A sub-agent works from the id and its own charter, and never opens a `personas/` file to expand it.
-- A persona route is not a specialist consultation. Applying a persona neither substitutes for nor satisfies an agent dispatch that the workflow requires.
-
-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` |
-
-## Automatic Routing Workflow
-
-### 1. Resolve Explicit Choice And Policy
-
-Match user wording against catalog `id`, `display_name`, and `aliases` case-insensitively.
-
-- An explicit persona selection wins over inference.
-- An explicit request for no persona leaves the task unpersonified.
-- An explicit switch replaces the current route.
-- If multiple personas are explicitly requested, use the persona that owns the primary deliverable and at most one other as a review lens. Apply the ambiguity policy if ownership remains unclear.
-- When `enabled: off`, skip automatic memory, documentation, and prompt inference. Continue to honor explicit persona and no-persona requests.
-
-### 2. Reuse massa-ai Evidence
-
-For coding sessions, reuse persona-specific evidence already returned by massa-ai's required initial recall. Do not repeat broad recall.
-
-If the existing result contains no useful persona evidence and the choice remains unresolved, run at most one targeted `recall` for prior persona preferences, successful routes, specialist roles, and project-specific ownership. Do not load massa-ai solely for a non-coding conversation.
-
-Memory is evidence, not authority:
-
-- Discard remembered persona IDs or paths absent from the current catalog.
-- Prefer recent, project-specific, successfully used routes over generic or old preferences.
-- Never let memory override an explicit user choice, applicable project policy, or the current deliverable.
-- Treat unavailable or empty memory as a cold start and continue to workspace documentation.
-
-### 3. Inspect Workspace Documentation
-
-When memory is unavailable, invalid, or inconclusive, inspect only targeted high-signal documents inside the active workspace. Reuse documents already present in context before reading more.
-
-Use this priority:
-
-1. Applicable root and nested `AGENTS.md` files and `CLAUDE.md`.
-2. Root `README.md` or equivalent project overview.
-3. Relevant ADR or decision indexes and entries.
-4. Relevant architecture documents.
-5. Relevant `.specs` project, state, architecture, or feature documents.
-
-Search filenames and headings first. Read only sections likely to identify the repository domain, primary deliverable ownership, required specialist roles, or explicit persona preferences. Do not recursively load every README, ADR, or specification. Ignore generated, dependency, secret, and globally excluded paths.
-
-Project instructions that explicitly pin or forbid a cataloged persona are stronger evidence than descriptive documentation. Stale documents, missing referenced files, or roles with no matching catalog entry cannot select a persona.
-
-### 4. Classify The Current Prompt
-
-Classify the requested output and primary ownership, not raw keyword counts. Compare the first or current user prompt with catalog summaries and routing signals, using valid memory and documentation only as supporting context.
-
-- `primary_signals` identify the persona that owns the deliverable.
-- `negative_signals` prevent supporting concerns from taking ownership.
-- `secondary_lens_signals` may add one focused review lens for a material risk.
-- A supporting mention of tests, implementation, architecture, or release work does not transfer ownership unless that work is the primary deliverable.
-
-Do not calculate or report numeric confidence. A route is clear when one candidate owns the deliverable and no equally plausible candidate conflicts with it.
-
-### 5. Resolve Ambiguity Or No Match
-
-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.
-- `ambiguity: best_match`: choose the candidate with the strongest current-deliverable ownership, 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 without a persona unless the user explicitly requested routing.
-- `no_match: ask`: ask whether to use the weakly supported candidate or `No persona`. If no candidate has relevant evidence, 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 under the default policy, not ambiguity.
-
-### 6. Apply And Announce The Route
-
-Choose exactly one primary persona and at most one secondary review lens. Read only their cataloged prompt files.
-
-- The primary persona owns recommendations, implementation, and final synthesis.
-- The review lens contributes only checks that reduce a concrete risk.
-- Do not produce independent persona answers, simulate a debate, or merge full voices.
-- For an inferred or explicit persona, state the route once: `Persona: <primary>. Reason: <primary deliverable>.` Add `Review lens: <secondary>.` when used.
-- Do not announce a default no-persona route unless the user requested routing or a prior route was removed.
-- Apply persona stance, expertise, priorities, and review criteria without quoting or reproducing its prompt.
-
-## Route Lifetime
-
-Keep the selected persona sticky across follow-up turns that advance the same primary objective.
-
-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 `mid_conversation: explicit_only`, re-evaluate only on an explicit user 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 during the conversation before substantive work continues.
-
-After resume or compaction, restore any route still present in conversation context or transcript without re-announcing it or repeating a resolved question. If the prior route is unavailable, run the normal workflow again; no separate route database is required.
-
-## Routing Examples
-
-| Situation | Result |
-|---|---|
-| User explicitly asks for Senior Mobile QA Automation Engineer. | Apply that catalog entry; explicit choice wins. |
-| massa-ai recalls a successful mobile-engineer route, but current prompt asks to fix flaky Maestro CI. | Route to Senior Mobile QA Automation Engineer; memory cannot override current ownership. |
-| Memory is empty; README and ADRs describe a cross-platform app; prompt asks to implement offline sync. | Route to Senior Mobile Engineer using docs plus current deliverable. |
-| Prompt asks for both app architecture and an automation suite with 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 does not name a persona. | Skip inference and continue without a persona. |
-| Memory names a removed persona ID. | Discard stale memory and continue to docs and prompt classification. |
-| Current mobile implementation finishes and user starts a flake-reduction task. | With `task_change`, re-evaluate and announce the new route once. |
+A persona shapes main-agent reasoning; a sub-agent is a bounded executor under its own charter. A persona grants no tool access, no write scope, and no permission. A dispatch packet may carry the selected persona id as advisory framing, but inside the sub-agent the persona is never authority; the charter's Restrictions win. The packet carries the persona **id only**, never the persona prompt. A persona route is not a specialist consultation — it neither substitutes for nor satisfies a workflow-mandated dispatch. Overlap table: `references/routing-details.md`.
 
-## Failure Handling
+## Lifetime And Failures
 
-- **Catalog missing or invalid:** Report `Persona routing unavailable: <reason>.` Continue without a persona.
-- **Unsupported schema version:** Report the found and supported versions. Continue without a persona.
-- **massa-ai unavailable or empty:** Continue with targeted workspace documentation and the current prompt.
-- **Workspace documentation unavailable:** Route from explicit choice and current prompt; apply 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; do not silently substitute another persona.
-- **User cannot be asked interactively:** Ask one concise plain-text question when policy requires a choice; otherwise use the configured non-interactive behavior.
+Routes are sticky while the objective advances; re-evaluate per `mid_conversation`. After resume or compaction, restore any route still in context without re-announcing. Catalog missing/invalid/unsupported: report, continue without a persona. Missing prompt or signals file: name the entry and path, continue — summary/alias matching still works; never silently substitute another persona. Detail tables: `references/routing-details.md`.
 
 ## Stop Conditions
 
-Routing is complete when one primary persona is applied, the user selects no persona, or policy intentionally produces a no-persona route. Persona routing itself stays inline: do not invoke a separate model router, launch subagents for persona selection, create subprocess orchestration, or persist a route database. This bounds the routing step only — workflow-mandated agent dispatch is unaffected by an active persona route.
+Routing is complete when one primary persona is applied, the user selects no persona, or policy produces a no-persona route. Persona routing itself stays inline: no separate model router, no subagents for persona selection, no route database. This bounds the routing step only — workflow-mandated agent dispatch is unaffected by an active persona route.

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.