@massa-ai/cursor-plugin 1.27.0 → 1.30.0

package/skills/massa-ai/references/coding-guidelines.md

@@ -0,0 +1,67 @@
+# Coding Guidelines
+
+Source: Karpathy Guidelines (Useful-Agent-Skills)
+
+Behavioral guidelines to reduce common LLM coding mistakes. These principles bias toward caution over speed—for trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them—don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- Disagree honestly. If the user's approach seems wrong, say so—don't be sycophantic.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it—don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+**The test:** Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

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

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

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

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

package/skills/massa-ai/references/skill-architect/examples.md

@@ -0,0 +1,256 @@
+# Description & Instruction Examples
+
+Reference for writing effective skill descriptions and instructions.
+Read this during the Architecture phase (for descriptions) and Craft phase
+(for instructions).
+
+---
+
+## Good Descriptions
+
+Each example follows the pattern: [What] + [When/Triggers] + [Not-when].
+
+### Document & Asset Creation
+
+```yaml
+description: Analyzes Figma design files and generates developer handoff documentation.
+  Use when user uploads .fig files, asks for "design specs", "component
+  documentation", or "design-to-code handoff". Do NOT use for general
+  design discussions or UI feedback.
+```
+
+```yaml
+description: Creates distinctive, production-grade frontend interfaces with high design
+  quality. Use this skill when the user asks to build web components, pages,
+  artifacts, posters, or applications (examples include websites, landing
+  pages, dashboards, React components, HTML/CSS layouts, or when
+  styling/beautifying any web UI). Generates creative, polished code and UI
+  design that avoids generic AI aesthetics.
+```
+
+### Workflow Automation
+
+```yaml
+description: Manages Linear project workflows including sprint planning, task creation,
+  and status tracking. Use when user mentions "sprint", "Linear tasks",
+  "project planning", or asks to "create tickets". Do NOT use for general
+  project management advice without Linear context.
+```
+
+```yaml
+description: End-to-end customer onboarding workflow for PayFlow. Handles account
+  creation, payment setup, and subscription management. Use when user says
+  "onboard new customer", "set up subscription", or "create PayFlow account".
+```
+
+### MCP Enhancement
+
+```yaml
+description: Automatically analyzes and fixes detected bugs in GitHub Pull Requests
+  using Sentry's error monitoring data via their MCP server. Use when user
+  mentions "Sentry errors", "fix bugs from monitoring", "PR review with
+  error data", or asks to analyze production errors in code.
+```
+
+---
+
+## Bad Descriptions (and Why)
+
+```yaml
+# ❌ Too vague — no trigger phrases, no specifics
+description: Helps with projects.
+# Why it fails: the agent can't determine WHEN to load this.
+```
+
+```yaml
+# ❌ Missing triggers — describes capability but not activation
+description: Creates sophisticated multi-page documentation systems.
+# Why it fails: What would a user SAY to trigger this? "Create docs"?
+# "Write documentation"? Include the actual phrases.
+```
+
+```yaml
+# ❌ Too technical, no user perspective
+description: Implements the Project entity model with hierarchical relationships.
+# Why it fails: Users don't think in entity models. They think in tasks.
+```
+
+```yaml
+# ❌ Too broad — will overtrigger
+description: Processes documents.
+# Why it fails: Loads for ANY document task. Add file types and specifics.
+```
+
+```yaml
+# ❌ Overlap without boundaries
+description: Analyzes data and creates visualizations.
+# Why it fails: Conflicts with built-in capabilities and other skills.
+# Add specifics about WHAT data and WHAT kind of visualizations.
+```
+
+---
+
+## Fixing Overtriggering with Negative Triggers
+
+```yaml
+# Before: triggers on all data tasks
+description: Advanced data analysis for CSV files.
+
+# After: scoped with negative triggers
+description: Advanced data analysis for CSV files. Use for statistical modeling,
+  regression, clustering. Do NOT use for simple data exploration
+  (use data-viz skill instead) or for reading CSV files without analysis.
+```
+
+---
+
+## Good Instructions
+
+### Specific and Actionable
+
+```markdown
+# ✅ Good — tells the agent exactly what to do
+
+Run `python scripts/[validate].py --input {filename}` to check data format.
+If validation fails, common issues include:
+
+- Missing required fields → add them to the CSV
+- Invalid date formats → use YYYY-MM-DD
+- Encoding errors → convert to UTF-8 first
+```
+
+```markdown
+# ❌ Bad — vague and unactionable
+
+Validate the data before proceeding.
+```
+
+### Error Handling
+
+```markdown
+# ✅ Good — specific error, cause, solution
+
+## Common Issues
+
+### MCP Connection Failed
+
+If you see "Connection refused":
+
+1. Verify MCP server is running: Check Settings > Extensions
+2. Confirm API key is valid
+3. Try reconnecting: Settings > Extensions > [Service] > Reconnect
+```
+
+```markdown
+# ❌ Bad — no specifics
+
+If something goes wrong, try again.
+```
+
+### Resource References
+
+```markdown
+# ✅ Good — says WHEN and WHY to read the file
+
+Before writing queries, consult `references/[api-patterns].md` for:
+
+- Rate limiting guidance (if making >10 calls)
+- Pagination patterns (if results may exceed 100 items)
+- Error codes and handling (if calls may fail)
+```
+
+```markdown
+# ❌ Bad — no guidance on when to read
+
+See references/ for more information.
+```
+
+### Critical Instructions
+
+```markdown
+# ✅ Good — prominent, specific, verifiable
+
+CRITICAL: Before calling create_project, verify:
+
+- Project name is non-empty
+- At least one team member assigned
+- Start date is not in the past
+  If any check fails, tell the user what's missing before proceeding.
+```
+
+```markdown
+# ❌ Bad — buried, vague, not verifiable
+
+Make sure to validate things properly.
+```
+
+### Examples in Skills
+
+```markdown
+# ✅ Good — realistic user input with concrete output
+
+## Examples
+
+### Example 1: New sprint setup
+
+User says: "Help me plan the Q4 sprint for the mobile team"
+Actions:
+
+1. Fetch current backlog from Linear (MCP)
+2. Check team capacity (3 engineers, 2-week sprint)
+3. Prioritize by impact score
+4. Create 12 tasks with estimates
+   Result: Sprint board populated with 12 prioritized tasks, each with
+   story points and assignees. Summary posted to #mobile-team Slack.
+```
+
+```markdown
+# ❌ Bad — generic, no concrete details
+
+### Example 1: Setup
+
+User says: "Set up a project"
+Result: Project gets created.
+```
+
+---
+
+## Anti-Patterns Checklist
+
+Before finalizing any skill, verify NONE of these are present:
+
+### Structural Anti-Patterns
+
+- [ ] File named SKILL.MD, skill.md, or any variant (must be exactly SKILL.md)
+- [ ] Folder has spaces or capitals (must be kebab-case)
+- [ ] README.md exists inside the skill folder
+- [ ] XML angle brackets (< >) in YAML frontmatter
+- [ ] "claude" or "anthropic" in the skill name
+- [ ] Missing --- delimiters around frontmatter
+- [ ] SKILL.md exceeds 500 lines without progressive disclosure
+
+### Description Anti-Patterns
+
+- [ ] No trigger phrases included
+- [ ] Too vague (could match anything)
+- [ ] Too technical (user perspective missing)
+- [ ] No negative triggers when overlap risk exists
+- [ ] Exceeds 1024 characters
+
+### Instruction Anti-Patterns
+
+- [ ] Vague directions without specific actions
+- [ ] Critical instructions buried in middle of document
+- [ ] No examples of realistic usage
+- [ ] No error handling guidance
+- [ ] References to external files without load conditions
+- [ ] Wall-of-text instructions without structure
+- [ ] Assumes skill is the only one loaded
+- [ ] Uses prose where a script would be deterministic
+
+### Quality Anti-Patterns
+
+- [ ] No validation step in workflow
+- [ ] No stopping conditions for iterative processes
+- [ ] Missing rollback/failure handling
+- [ ] Over-reliance on "be careful" instead of specific checks

package/skills/massa-ai/references/skill-architect/patterns.md

@@ -0,0 +1,317 @@
+# Skill Patterns Reference
+
+This document details the five proven patterns for skill architecture.
+Read this when deciding how to structure a skill's workflow during the
+Architecture phase.
+
+## Table of Contents
+
+1. Sequential Workflow Orchestration (line ~20)
+2. Multi-MCP Coordination (line ~70)
+3. Iterative Refinement (line ~120)
+4. Context-Aware Tool Selection (line ~170)
+5. Domain-Specific Intelligence (line ~210)
+6. Choosing Between Patterns (line ~250)
+7. Combining Patterns (line ~280)
+
+---
+
+## 1. Sequential Workflow Orchestration
+
+**Use when:** Users need multi-step processes executed in a specific order,
+where each step depends on the previous one.
+
+**Problem-first framing:** "I need to onboard a new customer" → Skill
+orchestrates the right calls in the right sequence.
+
+**Key characteristics:**
+
+- Explicit step ordering with dependencies between steps
+- Validation gates between steps (don't proceed if step N fails)
+- Rollback instructions for failures
+- Data flows from earlier steps to later ones
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Step 1: [Action]
+Call tool: `tool_name`
+Parameters: [what's needed]
+Validation: [how to know it succeeded]
+On failure: [what to do]
+
+### Step 2: [Action]
+Depends on: Step 1 (uses [specific output])
+Call tool: `tool_name`
+Parameters: [include output from Step 1]
+Validation: [check]
+
+### Step 3: [Action]
+...
+```
+
+**When to choose this pattern:**
+
+- The workflow has a natural linear order
+- Steps have clear dependencies
+- Skipping a step would break the workflow
+- Users currently do these steps manually in sequence
+
+**Watch out for:**
+
+- Rigid ordering when some steps could be parallel
+- Missing rollback logic (what if step 3 fails after step 1 and 2 succeeded?)
+- Not validating between steps
+
+---
+
+## 2. Multi-MCP Coordination
+
+**Use when:** Workflows span multiple external services, each connected
+via its own MCP server.
+
+**Key characteristics:**
+
+- Clear phase separation by service
+- Data passing between MCP servers
+- Validation before moving to next phase
+- Centralized error handling across services
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Phase 1: [Service A] ([MCP name])
+1. [Action using Service A tools]
+2. [Action using Service A tools]
+Output: [data needed by Phase 2]
+
+### Phase 2: [Service B] ([MCP name])
+Input: [data from Phase 1]
+1. [Action using Service B tools]
+2. [Action using Service B tools]
+Output: [data needed by Phase 3]
+
+### Phase 3: [Service C] ([MCP name])
+...
+
+## Error Handling
+- If Phase 1 fails: [action]
+- If Phase 2 fails but Phase 1 succeeded: [action]
+```
+
+**When to choose this pattern:**
+
+- The workflow crosses service boundaries
+- Multiple MCP servers are involved
+- Data needs to flow between services
+- Users currently switch between tools manually
+
+**Watch out for:**
+
+- Assuming all MCPs are connected (check availability first)
+- Not handling partial failures (Phase 2 fails but Phase 1 already ran)
+- Tight coupling between phases (prefer passing data explicitly)
+
+---
+
+## 3. Iterative Refinement
+
+**Use when:** Output quality improves through multiple review-and-fix cycles.
+
+**Key characteristics:**
+
+- Initial draft generation
+- Quality check against explicit criteria
+- Refinement loop with clear stopping conditions
+- Finalization step
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Initial Draft
+1. Gather input data
+2. Generate first version
+3. Save to working file
+
+### Quality Check
+Run validation: `scripts/[check_quality].py`
+Criteria:
+- [Criterion 1]: [how to check]
+- [Criterion 2]: [how to check]
+- [Criterion 3]: [how to check]
+
+### Refinement Loop
+For each issue found:
+1. Identify the specific problem
+2. Fix it
+3. Re-validate
+
+STOP when:
+- All criteria pass, OR
+- 3 iterations completed (diminishing returns), OR
+- User signals satisfaction
+
+### Finalization
+1. Apply final formatting
+2. Generate summary of changes
+3. Save final version
+```
+
+**When to choose this pattern:**
+
+- Output quality is subjective or multi-dimensional
+- First drafts are usually "close but not quite"
+- Users currently review and ask for revisions manually
+- There are explicit quality criteria to check against
+
+**Watch out for:**
+
+- Infinite loops (always define stopping conditions)
+- Over-polishing (3 iterations is usually enough)
+- Vague quality criteria (make them checkable)
+
+---
+
+## 4. Context-Aware Tool Selection
+
+**Use when:** The same goal can be achieved with different tools depending
+on the input or context.
+
+**Key characteristics:**
+
+- Decision tree based on input properties
+- Fallback options when primary choice isn't available
+- Transparency about why a particular path was chosen
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Analyze Input
+Check: [what properties to examine]
+- Property A: [value range or type]
+- Property B: [value range or type]
+
+### Decision Tree
+IF [condition 1]:
+  → Use [Tool/Approach A]
+  Rationale: [why this is better for this case]
+ELIF [condition 2]:
+  → Use [Tool/Approach B]
+  Rationale: [why]
+ELSE:
+  → Use [Tool/Approach C] (default)
+
+### Execute
+Based on decision, execute using the selected approach.
+
+### Explain Choice
+Tell the user which approach was selected and why.
+```
+
+**When to choose this pattern:**
+
+- Multiple valid approaches exist for the same goal
+- The "best" approach depends on input characteristics
+- Users don't know (or shouldn't need to know) which tool is optimal
+
+**Watch out for:**
+
+- Decision criteria that overlap (ambiguous routing)
+- Missing fallback for edge cases
+- Not explaining the choice to the user
+
+---
+
+## 5. Domain-Specific Intelligence
+
+**Use when:** The skill's value comes from specialized knowledge, not just
+tool orchestration.
+
+**Key characteristics:**
+
+- Domain rules and constraints embedded in logic
+- Compliance or validation checks before action
+- Comprehensive audit trails
+- Expert-level decision making
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Pre-Check ([Domain] Rules)
+Before proceeding, verify:
+1. [Domain rule 1]: [how to check]
+2. [Domain rule 2]: [how to check]
+3. [Domain rule 3]: [how to check]
+
+IF any rule fails:
+  → [Escalation or alternative path]
+  → Document the failure
+
+### Execute
+Only if pre-checks pass:
+1. [Action with domain context]
+2. [Action with domain context]
+
+### Audit Trail
+Log:
+- All checks performed and results
+- Decisions made and rationale
+- Actions taken
+```
+
+**When to choose this pattern:**
+
+- The skill needs expert knowledge to execute correctly
+- There are compliance, safety, or quality rules to enforce
+- Getting it wrong has significant consequences
+- Users benefit from the skill's "expertise" more than its automation
+
+**Watch out for:**
+
+- Outdated domain knowledge (plan for updates)
+- Over-encoding rules that change frequently (reference external docs instead)
+- Not documenting the reasoning for decisions
+
+---
+
+## 6. Choosing Between Patterns
+
+| Signal | Suggested Pattern |
+|--------|------------------|
+| "Do A, then B, then C" | Sequential Workflow |
+| "Get data from X, send to Y, notify in Z" | Multi-MCP Coordination |
+| "Make it good, then review and improve" | Iterative Refinement |
+| "Handle PDFs differently from CSVs" | Context-Aware Selection |
+| "Follow our compliance rules" | Domain-Specific Intelligence |
+| Steps have no dependencies | Consider parallel execution |
+| User says "it depends" a lot | Context-Aware Selection |
+| Quality is subjective | Iterative Refinement |
+
+---
+
+## 7. Combining Patterns
+
+Most real skills combine patterns. Common combinations:
+
+- **Sequential + Domain Intelligence:** Follow steps in order, but embed
+  expert checks at critical points (e.g., compliance check before payment)
+- **Multi-MCP + Iterative:** Coordinate across services, then refine the
+  combined output
+- **Context-Aware + Sequential:** Choose the right tool first, then follow
+  a sequential workflow specific to that tool
+- **Domain Intelligence + Iterative:** Apply domain rules, generate output,
+  review against domain criteria, refine
+
+When combining, identify the PRIMARY pattern (the one that shapes the
+overall flow) and SECONDARY patterns (the ones that apply within specific
+steps).