@massa-ai/cursor-plugin 1.6.0

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

@@ -0,0 +1,296 @@
+# massa-ai Tool Contracts (52 Tools)
+
+Load this reference when exact MCP schemas, REST fallbacks, response modes, or
+polling rules are needed. Prefer the active tool declaration over copied
+examples. The canonical tool list and order is defined in
+`apps/mcp-client/src/tool-definitions.ts` CANONICAL_ORDER.
+
+## Contract Precedence
+
+1. Active MCP schema for MCP calls.
+2. Live `/swagger/json` schema for direct REST calls.
+3. Release notes and README for intended behavior.
+4. Non-destructive runtime probes when the surfaces disagree.
+
+Swagger currently exposes empty response schemas and reports API version
+`1.0.0`; use it for request contracts and routes, not as proof of response
+shape or package version.
+
+## MCP Capability Matrix — Indexing & Search
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `index` | Start background project indexing | Requires `projectPath`; may return `jobId`. |
+| `index_status` | Poll indexing progress | Poll after a real delay, never in a tight loop. |
+| `reindex` | Force workspace reindex | Compatibility-sensitive; see Reindex And Reset below. |
+| `reset_project` | Delete vectors/symbols/memories | Destructive; explicit user intent required. |
+| `list_projects` | Resolve exact project IDs and index status | Use before indexing or project-map calls. |
+| `project_map` | General architecture/stats/PageRank overview | Uses `id`, not `projectId`. Returns stats, top files by PageRank, symbol counts, extension distribution, recent files. |
+| `get_architecture` | Architecture-specific deep map | Uses `id`. Returns packages, entry points, routes, hotspots, communities, layers, and opt-in cycles (Tarjan SCC). Pass `aspects:["cycles"]` for call cycles. Distinct from `project_map` (general overview vs architecture-specific). |
+| `search` | Semantic + keyword code search | Supports `summary`, `full`, `enriched`, and optional Synapse `sessionId`. |
+| `optimized_context` | Search plus compression | Has no `sessionId`; do not invent one. |
+| `read_file` | Targeted file/range read with symbols/imports | Relative paths may resolve against the server checkout; see below. Prefer over native Read when symbol metadata is useful. |
+| `symbol_snippet` | Read exact code lines by range | Requires `projectId` and relative `file` with `lineStart`/`lineEnd`. |
+| `fetch_and_index` | Fetch URL(s) → HTML→markdown/JSON → index | SSRF-guarded, TTL-cached. Req: `url` or `requests`[]. Opt: `source`, `concurrency`, `force`, `ttl`. |
+
+## MCP Capability Matrix — Symbol Graph
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `search_definitions` | Find symbol definitions | Search field is `search`; installed v2.0.2 may ignore search/kind filters. |
+| `get_references` | Find symbol usages | Use `fqn` when names are ambiguous. |
+| `go_to_definition` | Resolve a symbol from caller context | Optional `fromFile` improves disambiguation. |
+| `trace_path` | Trace call/data-flow/cross-service path (BFS) | Req: `function_name` or `qualifiedName`, `project`. Opt: `direction`, `mode`, `depth`, `include_tests`, `edge_types`[]. Only counts as evidence when index is fresh for current path/commit. |
+| `impact_analysis` | Git-diff → impacted symbols (centrality-ranked) | Req: `project`, `projectPath`. Opt: `scope`, `base_branch`, `since`, `depth`, `paths`[]. Only counts as evidence when index is fresh. Empty diff → empty impact set (not an error). |
+
+## MCP Capability Matrix — Memory & Lifecycle
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `remember` | Persist durable knowledge | Supported types: critical, conversation, code, decision, pattern. |
+| `recall` | Semantic memory retrieval | Use `projectId` for project-scoped decisions. |
+| `memory_list` | Chronological memory audit | Treat as unscoped until runtime proves project filtering. |
+| `memory_update` | Update a memory by id; re-embeds on content change | Req: `id`. Opt: `content`, `importance`, `tags`, `mergeTags`, `format`. |
+| `memory_delete` | Hard-delete a memory by id; severs graph edges | Req: `id`. Opt: `format`. |
+| `compress` | Compress large context | Pick a strategy from the table below; do not persist output automatically. |
+| `analytics` | Inspect search/cache usage | Requires analytics `type` (summary, project, query, cache, recent). |
+| `compact_snapshot` | Bounded (<2KB) session compaction snapshot | Req: `sessionId` (lifecycle session id, NOT workflowSessionId). Opt: `projectId`, `persist`. Zero-loss table-of-contents for /compact recovery. |
+
+### Compression Strategies
+
+`compress` takes one explicit `strategy`. Match the strategy to the input shape;
+the reduction ranges are observed, not guaranteed.
+
+| Strategy | Use case | Reduction |
+|---|---|---|
+| `code_structure` | Source code | 70-90% |
+| `conversation_summary` | Chat history | 80-95% |
+| `semantic_dedup` | Repetitive content | 50-70% |
+| `hierarchical` | Structured docs | 60-80% |
+
+Compress before persisting a large artifact into memory, not after. Compressed
+output is a lead, not a source of truth: re-read the original file when a claim
+depends on exact content.
+
+## MCP Capability Matrix — Synapse (Cognitive Layer)
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `synapse_session` | Create an ephemeral cognitive session | Supply explicit agent/workspace/context/TTL. Omit `sessionId` for server-generated ID. |
+| `synapse_get` | Inspect session state | Use to confirm state or diagnose expiry. |
+| `synapse_update` | Replace session task context | Use after a major focus shift (investigate → fix). |
+| `synapse_end` | End a session | Free resources after completion when practical. |
+| `synapse_prime` | Prime Synapse buffer | Adapter is compatibility-sensitive; may fail with 422. REST fallback or skip. |
+| `synapse_access` | Record a consumed hit for affinity | Verified adapter may fail path binding; REST fallback with `memoryId` works. |
+| `synapse_prefetch` | Warm buffer for a file about to be investigated | Req: `id` (session), `filePath`. Opt: `symbols`, `chains`, `maxResults`, `minImportance`, `entries`. |
+| `synapse_list` | List active session count | Debug aid. |
+| `synapse_task_begin` | Begin a task envelope within a session | Req: `id` (session id from `synapse_session`). Opt: `taskContext`. Requires existing session. |
+| `synapse_task_end` | End a task envelope within a session | Req: `id` (session id). Requires existing task envelope. |
+
+## MCP Capability Matrix — Checkpoints
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `create_checkpoint` | Save task progress for later resumption | Req: `taskId`, `description`. Opt: `status`, `currentStep`, `progressPercent`, `totalSteps`, `completedSteps`, `checkpointType` (manual/milestone), `agentId`, `projectId`, `memoryIds`, `fileChanges`, `decisions`, `learnings`, `nextAction`, `pendingValidations`, `format`. |
+| `list_checkpoints` | List saved checkpoints | Opt: `taskId`, `projectId`, `checkpointType`, `includeExpired`, `limit`, `format`. |
+| `restore_checkpoint` | Restore a checkpoint and return state + integrity | Opt: `checkpointId` or `taskId` (restore latest for task), `format`. |
+
+## MCP Capability Matrix — Cross-session Handoffs
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `handoff_begin` | Begin a cross-session handoff; dual-writes searchable memory | Req: `projectId`. Opt: `sourceSessionId`, `targetAgent`, `summary`, `openQuestions`, `nextSteps`, `files`. |
+| `handoff_accept` | Accept an open handoff (open→accepted) | Req: `id`. Opt: `projectId`. |
+| `handoff_cancel` | Cancel/expire an open handoff | Req: `id`. Opt: `projectId`. |
+| `handoff_list_pending` | List open handoffs, oldest-first | Req: `projectId`. Opt: `targetAgent`. |
+
+## MCP Capability Matrix — Auto-improvement (Proposals)
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `list_proposals` | List pending auto-improvement proposals, newest-first | Req: `projectId`. |
+| `approve_proposal` | Approve a proposal; applies the memory edit | Req: `id`. Opt: `projectId`, `source`. |
+| `reject_proposal` | Reject a proposal (no edit applied) | Req: `id`. Opt: `projectId`, `reason`. |
+
+## MCP Capability Matrix — Passive Capture
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `hook_ingest` | Passively ingest lifecycle events as Observations | Req: `events`[]. Used by host hook scripts, not agent workflows directly. |
+
+## MCP Capability Matrix — Project Bootstrap
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `bootstrap` | Scan a project and create seed memories | Req: `projectId`. Opt: `projectPath`, `force`. Idempotent; LLM-off degrades to rule-based. |
+
+## MCP Capability Matrix — Code Execution (Sandbox)
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `execute` | Run code in a detected runtime | Req: `language`, `code`. Opt: `timeout`, `background`, `cwd`, `intent`. Local-dev only. |
+| `execute_file` | Read a file into a sandboxed var and run code over it | Req: `path`, `language`, `code`. Opt: `timeout`, `intent`. Avoids loading full file into context. |
+| `batch_execute` | Run N shell commands in parallel | Req: `commands`[]. Opt: `queries`, `timeout`, `concurrency`, `cwd`, `query_scope`. Concurrency-capped at 256. |
+
+## MCP Capability Matrix — Project Lifecycle (Admin)
+
+| Tool | Primary use | Important contract note |
+|---|---|---|
+| `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. |
+
+## Retrieval Order
+
+1. `list_projects` or equivalent index metadata to verify project ID,
+   path, status, and `lastIndexedAt` before treating indexed context as current.
+2. `project_map` for general architecture orientation when the index is fresh for the current repository path and worktree state.
+3. `get_architecture` for architecture-specific deep maps (packages, routes, hotspots, communities, cycles) when the index is fresh.
+4. `search(responseMode="summary", maxResults=10)` for broad discovery.
+5. `search(responseMode="enriched", maxResults=3)` for targeted deep reads with `fileImports`, `parentSymbol`, and chunk navigation metadata; raise to `maxResults=5` only when 4-5 exact files, symbols, or report finding IDs are already named.
+6. Symbol tools (`search_definitions`, `get_references`, `go_to_definition`) and `read_file` for exact source evidence.
+7. `symbol_snippet` for raw code snippets by file + line range.
+8. `trace_path` for typed-edge BFS call/data-flow path tracing (fresh index only).
+9. `impact_analysis` for git-diff centrality-ranked impact (fresh index only).
+10. `optimized_context` for compact synthesized context when available.
+11. Focused `rg`/file reads when massa-ai is unavailable, stale, incomplete, or misses obvious local truth.
+
+Do not use `full` or `enriched` for broad whole-project sweeps. Attempt REST fallback exactly once after a documented MCP schema, adapter, or missing-operation failure; if REST also fails, continue with MCP/local fallback and record the skipped reason.
+
+Graph tools (`trace_path`, `impact_analysis`, `get_architecture`) only count as
+evidence when the index is fresh for the current repository path and
+commit/worktree state. When the index is stale, incomplete, missing the target
+path, or older than relevant local changes, fall back to `search`/`get_references`
+and record the reduced retrieval confidence.
+
+Project maps, search hits, and optimized context are discovery leads until
+confirmed against source files read in the current session or returned with
+freshness evidence for the current worktree. When index status is stale,
+incomplete, missing the target path, or older than relevant local changes, use
+focused source reads as proof and record the reduced retrieval confidence.
+
+## Common MCP Calls
+
+```js
+search({
+  query: "authentication middleware",
+  projectId: "<projectId>",
+  maxResults: 10,
+  responseMode: "summary",
+  autoReindex: false,
+  sessionId: "<synapseSessionId>"
+})
+```
+
+Omit `sessionId` for one-shot or stateless search.
+
+```js
+optimized_context({
+  query: "session:<workflowSessionId> payment ownership",
+  projectId: "<projectId>",
+  maxTokens: 4000,
+  maxResults: 5
+})
+```
+
+```js
+remember({
+  content: "<durable fact or decision>",
+  type: "decision",
+  importance: 0.8,
+  projectId: "<projectId>",
+  sessionId: "<workflowSessionId>",
+  tags: [
+    "project:<projectId>",
+    "session:<workflowSessionId>",
+    "workflow:<type>",
+    "entity:<name>",
+    "memory:semantic"
+  ],
+  format: "toon"
+})
+```
+
+```js
+create_checkpoint({
+  taskId: "auth-refactor",
+  description: "Token rotation mid-flight",
+  progressPercent: 60,
+  currentStep: "rotateToken",
+  nextAction: "finish rotateToken in src/auth.ts",
+  fileChanges: ["src/auth.ts"],
+  checkpointType: "manual"
+})
+```
+
+```js
+handoff_begin({
+  projectId: "<projectId>",
+  summary: "Auth refactor in progress; token rotation unfinished",
+  nextSteps: ["finish rotateToken in auth.ts", "add tests"],
+  files: ["src/auth.ts", "src/token.ts"]
+})
+```
+
+## Verified MCP/REST Differences
+
+| Area | MCP surface | REST/Swagger surface | Policy |
+|---|---|---|---|
+| Search session | `sessionId` | `sessionId` | Value is ephemeral `synapseSessionId`. |
+| Search output | No `format` field in active MCP | REST supports `format` | Keep `format` out of MCP search calls. |
+| Optimized context | No session field | No session field | Preserve workflow context in query text/tags. |
+| Memory store | No `linkTo` in active MCP | REST exposes `linkTo` | REST-only until MCP adds it. |
+| Memory recall | No `includeRelated` in active MCP | REST exposes `includeRelated` | REST-only until MCP adds it. |
+| Memory list | MCP declares `projectId` | REST body has no `projectId` | Do not trust it for project scoping. |
+| File read | MCP has line range/compress/symbol/import fields | REST also has offset/limit/targetRatio/format | Keep REST-only fields out of MCP. |
+| Synapse create | MCP fields are broadly optional | REST requires `agentId` | Always provide explicit agent/workspace/context/TTL. |
+| Synapse prime | MCP declares `{id, results}` | REST requires `{entries}` | Verified adapter may fail with 422; use REST fallback or skip. |
+| Synapse access | MCP permits `memoryId` or `filePath` | REST requires `memoryId` | Verified MCP path binding failed; use REST fallback with `memoryId`. |
+| Reindex | MCP declares `{id, forceReindex}` | REST requires path `id` plus body `projectPath` | Probe only on disposable workspace; otherwise use full index fallback. |
+| File read path | MCP permits relative or absolute `filePath` | REST reads server filesystem | If relative resolution fails, combine registered workspace path with the indexed relative path. |
+| Definition filters | MCP exposes `search`, `kind`, `file`, `exportedOnly` | REST documents query filters | If filters are ignored, client-filter results or use `go_to_definition`. |
+
+## REST-Only Operations
+
+Use `MASSA_AI_API_URL` and optional `x-api-key: $MASSA_AI_API_KEY`. Never expose the
+key in output or persistence.
+
+- System diagnostics: `/health`, `/api/v1/system/status`,
+  `/api/v1/system/health/local`, `/api/v1/system/ollama`.
+- Remote upload/index: `POST /api/v1/project/upload-and-index`.
+- Index events: `GET /api/v1/events`.
+- Workspace details/removal: `GET|DELETE /api/v1/workspace/:id`.
+- File centrality: `GET /api/v1/symbol/centrality/:projectId`.
+- Synapse inspect/update/delete/prefetch/list routes documented in
+  `references/synapse-policy.md`.
+
+Do not use API-only routes merely because they exist. Prefer MCP unless the
+required operation is absent or its adapter is proven broken.
+
+## Reindex And Reset
+
+- Prefer `search(autoReindex=true)` for small stale-index refreshes.
+- Use `reindex` only after verifying its installed adapter contract on a
+  disposable workspace.
+- Fallback for a known path: `index({ projectPath, projectId,
+  forceReindex: true })` and poll its job.
+- Never call `reset_project` as routine reindex preparation. It can delete
+  memories by default and requires explicit destructive intent.
+
+## Polling Discipline
+
+Never call `index_status` in a tight turn-by-turn loop. Poll after a real
+delay. Preferred shell pattern:
+
+```bash
+MASSA_AI_API_URL="${MASSA_AI_API_URL:-http://localhost:3333}"
+for i in $(seq 1 40); do
+  result=$(rtk curl -s "$MASSA_AI_API_URL/api/v1/project/index/status/JOB_ID")
+  status=$(printf '%s' "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['status'])")
+  printf '[%s] status=%s\n' "$i" "$status"
+  [ "$status" = "completed" ] || [ "$status" = "failed" ] && break
+  sleep 15
+done
+```
+
+When shell polling is inappropriate, call status once, wait for a natural turn
+or scheduled wakeup, then poll again.

package/skills/massa-ai/references/memory-policy.md

@@ -0,0 +1,103 @@
+# Memory Policy
+
+Read this when writing, updating, pruning, promoting, or resolving conflicting massa-ai memories.
+
+## Tiers
+
+| Tier | Use | Persist as | Required tag |
+|------|-----|------------|--------------|
+| Working | Active task state, pending local intent, temporary context | Usually skip; use `conversation` only for handoff | `memory:working` |
+| Episodic | Timestamped attempts, observations, command evidence, ruled-out hypotheses | `conversation` or `code` | `memory:episodic` |
+| Semantic | Durable project facts, constraints, decisions, architecture patterns | `critical`, `decision`, or `pattern` | `memory:semantic` |
+| Procedural | Reusable workflow, command, verification recipe, debugging protocol | `pattern` or `decision` | `memory:procedural` |
+
+Supported massa-ai types are only `critical`, `conversation`, `code`, `decision`, and `pattern`.
+
+## Observational Memory
+
+Observational Memory is not a new storage layer. It is the discipline for deciding which execution observations become massa-ai memories.
+
+- Observer mode: capture only high-signal events, decisions, failed attempts, ruled-out hypotheses, and verification recipes.
+- Reflector mode: when the same lesson appears in 3+ independent sessions, promote it to semantic or procedural memory.
+- Episodic observations stay lightweight: date, fact, evidence, why it matters, and what not to repeat.
+- Failed or repeated tool loops become compact cognition lessons only when reusable.
+
+A cognition lesson should use this shape:
+
+```md
+Trigger: ...
+Failure pattern: ...
+Prevention rule: ...
+Evidence: ...
+```
+
+Persist cognition lessons as `pattern` memories with `memory:procedural` when they would prevent future repeated failures. Skip one-off tool noise.
+
+## Allowed And Forbidden Payloads
+
+Persist only durable decisions, rejected approaches, reusable patterns,
+verification recipes, repeated lessons, and high-signal gotchas. Do not persist
+raw transcripts, raw logs, copied source, raw search output, raw subagent output,
+customer data, secrets, one-off observations, already-captured facts, or noisy
+command output.
+
+## Required Tags
+
+Every persisted memory must include:
+
+- `project:<projectId>`
+- `session:<workflowSessionId>`
+- `workflow:<type>`
+- `entity:<name>`
+- `memory:<tier>`
+
+Add focused domain tags only when they improve future retrieval, such as `auth`, `mobile`, `tests`, `issue`, `handoff`, or `stale`.
+
+## Write Protocol
+
+1. Recall first using the project, entity, and likely fact name.
+2. Classify the memory tier and supported massa-ai type.
+3. Score importance with `references/decision-engine.md`.
+4. Do not write duplicates. If the same fact already exists and still applies, reuse it.
+5. If a new fact supersedes an old memory, write a replacement containing the date, the new fact, and why it supersedes the old one. Add `stale-replaces:<memoryId>` to the replacement; do not mark the replacement itself as `stale`.
+6. If recall shows the same lesson in 3+ independent sessions, promote it to semantic or procedural memory as `pattern` or `decision`; include source memory IDs in the content.
+7. Report the memory outcome in completion or handoff evidence as one of:
+   written, intentionally skipped with reason, duplicate skipped, forbidden payload skipped, or failed write with recovery note.
+
+## Example
+
+Persist only after recall and scoring. Add `stale-replaces:<memoryId>` only when replacing a recalled memory.
+
+```js
+remember({
+  projectId: "massa-ai",
+  sessionId: "spec-memory-routing",
+  type: "decision",
+  importance: 0.8,
+  content: "2026-06-27 workflows/spec-driven.md owns the TLC v3 Specify, optional Design, optional Tasks, and Execute flow with mandatory independent validation as Execute's final gate. Approved feature artifacts own phase contracts, .specs/project/STATE.md owns resumable session state, and massa-ai owns durable cross-session decisions and patterns.",
+  tags: [
+    "project:massa-ai",
+    "session:spec-memory-routing",
+    "workflow:spec-driven",
+    "entity:massa-ai",
+    "memory:semantic",
+    "stale-replaces:dec_old123" // omit unless this supersedes that memory
+  ]
+})
+```
+
+## Retrieval Policy
+
+Prefer memories in this order:
+
+1. Exact `session:<workflowSessionId>` memories for current task continuity
+2. Non-stale semantic memories for project constraints and decisions
+3. Recent episodic memories for attempts and evidence
+4. Procedural memories for commands and verification recipes
+
+Treat memories tagged `stale`, or old memories whose IDs are referenced by newer `stale-replaces:*` tags, as historical context rather than current truth.
+
+Use `recall(projectId=...)` for project-scoped decisions. The v2.0.2 MCP
+declaration exposes `projectId` on `memory_list`, but the verified REST
+body does not; treat memory-list output as unscoped unless a runtime probe proves
+the installed adapter applies the filter.

package/skills/massa-ai/references/mobile-context.md

@@ -0,0 +1,113 @@
+# Mobile Context
+
+Use this reference when a non-debug workflow touches KMP, iOS, Android, native bridges, mobile app lifecycle, offline sync, permissions, push/background work, local persistence, or backend-mobile contracts.
+
+Mobile is a context modifier, not a primary workflow. Keep the selected workflow based on user intent:
+
+- New capability -> `workflows/feature.md`
+- Behavior-preserving structure change -> `workflows/refactor.md`
+- Broken behavior, crashes, regressions, or device-specific failures -> `workflows/debug.md` plus `references/mobile-diagnosis.md`
+- New Maestro mobile E2E flow implementation -> `workflows/maestro/maestro.md`
+- Findings-only Maestro mobile E2E audit -> `workflows/maestro/maestro-audit.md`
+- Child-only fix for saved Maestro audit findings -> `workflows/maestro/maestro-fix.md`
+- Findings-only test coverage review -> `workflows/tests/tests-audit.md`
+- Fix findings from a tests audit report -> `workflows/tests/tests-fix.md`
+- Direct Android Views/Compose, UIKit/SwiftUI, or KMP Compose Multiplatform implementation from Figma or screenshot context -> `workflows/design.md`
+- Findings-only platform-detected mobile comparison with Figma -> `workflows/mobile-figma/mobile-figma-audit.md`
+- Fix saved platform-detected mobile Figma findings -> `workflows/mobile-figma/mobile-figma-fix.md`
+- Findings-only security review -> `workflows/security/security-audit.md`
+- Fix findings from a security audit report -> `workflows/security/security-fix.md`
+- Broad, cross-boundary, unclear, or multi-platform implementation -> `workflows/spec-driven.md`
+
+For `feature`, `spec-driven`, `rfc`, `adr`, and `tdd`, supported mobile UI work can use the optional design-source gate. Ask for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none` only when the request is Android, iOS, KMP Compose Multiplatform UI, or plausibly mobile UI. Clear backend, CLI, docs, infrastructure, and non-UI requests skip the prompt.
+
+Maestro is a first-class mobile E2E workflow family when the primary target is flow implementation, existing-flow audit, or saved `MST-*` remediation. Generic test coverage, assertion quality, or regression-risk review still belongs to `workflows/tests/tests-audit.md` or `workflows/tests/tests-fix.md` when the target is not Maestro-specific.
+
+When Figma sources or screenshots are supplied for supported Android, iOS, or KMP Compose Multiplatform UI implementation, keep the parent workflow as the lifecycle owner and invoke `workflows/design.md` only for the affected UI slice or visual feasibility context. Use `workflows/mobile-figma/mobile-figma-audit.md` for compare/audit intent and `workflows/mobile-figma/mobile-figma-fix.md` for saved `MFM-*` findings.
+
+Treat `none` as a first-class answer: record `Figma Source: none by user choice` and do not re-ask unless the mobile UI scope changes. For unsupported targets such as Flutter, React Native, web, desktop, or generic design exploration, record supplied design sources as outside mobile Figma scope, do not run mobile Figma, and continue the parent workflow. Screenshots are context-only unless paired with structured Figma evidence; do not claim exact Figma parity, tokens, variables, or dimensions from screenshots alone.
+
+## Mobile Context Packet
+
+Capture only the fields needed for the active workflow:
+
+- Platform scope: Android, iOS, KMP shared logic, native bridge, React Native, Flutter, webview, or backend-mobile contract
+- Shared boundary: KMP shared code, native bridge, backend contract, local persistence, navigation, platform-only UI, or platform service
+- App/build context: debug/release, flavor, app version/build, distribution channel, signing/profile when relevant
+- Device matrix: impacted or targeted OS/API versions, real device vs simulator/emulator, and screen/accessibility constraints when UI is involved
+- Runtime state: online/offline, background/foreground, process death, permissions, locale/timezone, feature flags, remote config, account/tenant, and local data/cache state when relevant
+- Parity target: Android-only, iOS-only, shared behavior, or both platforms
+
+Do not collect a full device matrix when the task only changes pure shared logic and deterministic shared tests are sufficient.
+
+## Boundary Decisions
+
+Before changing mobile behavior, decide where the change belongs:
+
+- KMP shared logic: domain rules, shared repositories, serialization, retry/backoff, validation, state machines, and platform-neutral contracts
+- Platform-specific code: permissions, OS APIs, lifecycle hooks, background execution, native storage, push providers, UI layout, accessibility, navigation shell, and signing/build behavior
+- Native bridge: payload shape, nullability, serialization, threading, callback lifetime, event ordering, error mapping, and backward compatibility
+- Backend-mobile contract: API versioning, auth refresh, pagination, schema nullability, media limits, upload retries, clock skew, and feature flag or remote config behavior
+
+Prefer shared logic only when both platforms need the same behavior and the platform APIs can support it cleanly. Keep platform-specific behavior explicit when OS rules, permissions, lifecycle, or UI conventions differ.
+
+## Platform Parity
+
+Any mobile change must state:
+
+- Impacted platform or shared boundary
+- Expected comparison platform result
+- Validation run for each affected platform, or skipped platform with reason
+- Risk if one platform cannot be checked
+
+For shared-code changes, run or document Android and iOS/KMP validation. For platform-only changes, prove the affected platform and state whether the other platform is unaffected, untested, or out of scope.
+
+## Verification Sensors
+
+Use the cheapest deterministic sensor that proves the workflow claim:
+
+- KMP/shared: shared unit tests, common fixtures, platform-specific `actual` tests, serialization contract tests, or KMP compiler tasks
+- Android: unit tests, instrumentation tests, Compose/Espresso tests, Gradle build/test tasks, emulator commands, deep-link intents, or focused lint/static checks
+- iOS: unit tests, XCTest/UI tests, scheme build/test, simulator commands, universal/deep-link checks, or focused lint/static checks
+- Cross-platform E2E: existing repo tools such as Maestro, Detox, Appium, XCTest UI, Espresso, or Compose UI tests
+- Mobile artifacts: screenshots, videos, sanitized logs, crash reports, device logs, or human-in-the-loop scripts only when deterministic harnesses are unavailable
+
+For design, mobile Figma audit, or mobile Figma fix, load `references/mobile-figma-matcher/repository-detection.md` and `references/mobile-figma-matcher/core.md`, then only the stack references selected by the Target Surface Packet. Maestro MCP/CLI is an optional runtime sensor: prefer existing safe flows and fixed device configurations, and never treat flow success or screenshots alone as parity proof.
+
+Never rely on model self-evaluation. If device access, signing, credentials, provisioning, or hardware is unavailable, state the missing dependency and use the strongest available artifact or static proof.
+
+## Tests Lens
+
+When auditing or executing test work, check mobile-specific coverage for:
+
+- KMP shared logic and platform-specific `actual` behavior
+- Native bridge payloads, nullability, serialization, callbacks, threading, and error paths
+- Permissions, deep links, push/background flows, lifecycle transitions, offline/online sync, local persistence, migrations, and auth refresh
+- UI layout, accessibility font size, safe areas/notches, keyboard, rotation, navigation/back stack, and locale/timezone behavior when relevant
+- Fixture drift between backend contracts, KMP models, Android models, and iOS bridge payloads
+- Snapshot or screenshot assertions that were weakened, over-broadened, or made nondeterministic
+
+## Security Lens
+
+When auditing or executing security work, check mobile-specific trust boundaries:
+
+- Secure storage/keychain/keystore use, token lifecycle, refresh behavior, and logout/session invalidation
+- Permission prompts, denied/restricted states, background permission behavior, and OS-version permission changes
+- Deep links, universal/app links, intent filters, route params, and auth guards
+- Push tokens, APNs/FCM environment, notification tap actions, background tasks, and token privacy
+- Biometrics, device credentials, fallback paths, and local lockout behavior
+- Local DB/cache, offline queues, pending writes, sync conflict handling, and data retention
+- Logs, crash reports, analytics, screenshots, and breadcrumbs for secret or personal data exposure
+- Backend-mobile contract skew, schema nullability, media upload limits, retry idempotency, and clock skew
+
+## Memory Guidance
+
+Persist durable mobile lessons only after recall and importance scoring:
+
+- KMP/shared vs platform-specific boundary decisions
+- Native bridge payload contracts or compatibility constraints
+- Project-specific mobile verification recipes or device matrix constraints
+- Security boundaries involving secure storage, permissions, deep links, push, biometrics, local data, logs, or backend-mobile contracts
+- Repeated mobile testing gaps, fixture drift patterns, or platform parity gotchas
+
+Do not persist one-off device details, raw logs, screenshots, customer data, tokens, device IDs, or temporary debugging artifacts.

package/skills/massa-ai/references/mobile-diagnosis.md

@@ -0,0 +1,106 @@
+# Mobile Diagnosis
+
+Use this reference when `workflows/debug.md` handles broken behavior involving KMP, iOS, Android, native bridges, real devices, simulators, emulators, mobile app lifecycle, or device-specific failures.
+
+This extends `references/debug-diagnosis-loop.md`. Do not use it instead of the general debug loop.
+
+For non-debug mobile feature, refactor, tests, or security work, keep the intent-specific workflow and load `references/mobile-context.md` instead. Use `references/mobile-context.md` from Debug only when shared mobile vocabulary or non-bug parity/security/test framing is needed.
+
+## Mobile Intake
+
+Add these fields to the normal debug intake packet:
+
+- Platform: Android, iOS, KMP shared logic, native bridge, React Native, Flutter, webview, or backend-mobile contract
+- OS/API version and device model
+- Real device vs simulator/emulator
+- App version, build number, build flavor, distribution channel, and signing/profile context when relevant
+- Debug, release, staging, production, or TestFlight/internal track
+- Network state: online, offline, captive portal, cellular, Wi-Fi, VPN, proxy, low bandwidth, or packet loss
+- Locale, timezone, calendar, text direction, region, and accessibility settings
+- Permission state: notifications, location, camera, contacts, Bluetooth, background refresh, biometrics, files, or photos
+- Battery, power saver, background/foreground state, app termination, process death, and cold/warm start state
+- Account, tenant, feature flags, remote config, entitlement, and experiment bucket
+- Data state: local DB/cache version, migration history, sync queue, pending writes, and corrupted or stale local records
+- Crash/log artifact availability: stack trace, sanitized `logcat`, iOS device logs, crash report, screenshot, video, or repro script
+
+If the bug is platform-specific, record the impacted platform and at least one unaffected or untested comparison platform.
+
+## Mobile Feedback Loops
+
+Choose the first loop that can reproduce the mobile failure, preserves the reported signal, and can later prove the fix:
+
+- KMP shared unit tests, common test fixtures, or platform-specific `actual` tests
+- Android unit tests, instrumentation tests, UI tests, Gradle task, emulator command, or deep-link intent command
+- iOS unit tests, UI tests, scheme build/test, simulator command, or universal link/deep-link command
+- Existing E2E tools already in the repo, such as Maestro, Detox, Appium, XCTest UI, Espresso, or Compose UI tests
+- App kill/restart, cold start, background/foreground transition, rotation, keyboard, notification tap, or deep-link flow
+- Push notification, background task, location, permission prompt, biometric, or offline/online simulation only when supported by local tools
+- Sanitized `logcat`, iOS device logs, crash reports, breadcrumbs, screenshots, videos, or trace exports
+- Device-farm, crash analytics, performance, or observability checks only when the project already has approved access
+- Structured human-in-the-loop script when a real device or account state is required
+
+Use skipped-reason enum values from `references/debug-diagnosis-loop.md` for unavailable mobile loops, especially `missing-hardware`, `missing-credentials`, `tool-missing`, `unsafe-production`, and `destructive-risk`.
+
+Loop quality rules:
+
+- Prefer deterministic local tests for KMP/shared logic before full-device loops.
+- For device-only failures, keep the device matrix explicit and avoid claiming global coverage from one simulator/emulator.
+- Preserve the original user-visible mobile failure signal, such as a crash, blank screen, lost sync item, permission failure, missing push, bad layout, or wrong navigation target.
+- If a loop needs unavailable hardware, credentials, signing, provisioning, or production data, state the missing dependency and use the strongest root-cause proof available.
+
+## Mobile Hypothesis Prompts
+
+Use these prompts to build the normal 3-5 item hypothesis board:
+
+- Lifecycle: cold start, warm start, process death, background resume, app switch, orientation, keyboard, memory pressure, or foreground service state
+- Permissions: denied, not determined, one-time grant, restricted, background-only, OS-version permission changes, or prompt timing
+- Native bridge: payload shape, nullability, serialization, threading, callback lifecycle, event ordering, or platform-specific type conversion
+- KMP boundary: `expect/actual` mismatch, coroutine dispatcher, freezing/thread confinement, platform clock/filesystem/network behavior, or shared persistence abstraction
+- Offline sync: queue ordering, conflict resolution, retry backoff, idempotency, cache invalidation, local DB migration, or partial-write recovery
+- Navigation/deep links: auth guard, universal/app link entitlement, intent filter, route params, nested navigator state, back stack, or cold-start restoration
+- Push/background: token registration, APNs/FCM environment mismatch, notification permission, background fetch limits, collapse keys, or tap-action routing
+- Build/runtime config: debug vs release behavior, minification/ProGuard/R8, bitcode/symbols, signing/profile, build flavor, env file, remote config, or feature flag
+- OS/device regression: API level, iOS version, OEM behavior, screen size, notch/safe area, locale/timezone, accessibility font size, battery saver, or low-memory behavior
+- Backend-mobile contract: API version skew, clock skew, auth refresh, pagination, schema nullability, media upload limits, or network retry semantics
+
+For each hypothesis, name the impacted boundary and the expected platform parity result.
+
+## Crash And Log Discipline
+
+Use crash and log artifacts as evidence, not as raw context:
+
+- Keep only sanitized frames, exception names, thread names, relevant app logs, event breadcrumbs, and source pointers.
+- Redact tokens, user IDs, device IDs, emails, phone numbers, precise locations, and customer data before memory or final output.
+- Symbolicate or deobfuscate when concrete project tools exist; otherwise state that stack evidence is partial.
+- Compare app frames against platform/framework frames to avoid fixing symptoms outside project code.
+- Load `references/context-firewall.md` before inspecting verbose device logs or crash exports.
+
+## Platform Parity
+
+Mobile fixes need explicit parity framing:
+
+- Impacted platform: where the failure occurs.
+- Comparison platform: unaffected, untested, or unknown.
+- Shared boundary: KMP shared code, native bridge, backend contract, local persistence, navigation, or platform-only UI.
+- Required validation: impacted platform fixed, unaffected platform still passes or is explicitly not in scope.
+
+If a shared-code change affects both platforms, run or document Android and iOS/KMP validation. If only one platform can be checked, state the skipped platform and risk.
+
+## Output Extension
+
+Add these fields to the normal Debug output contract:
+
+- Device Matrix: platform, OS/API, device/simulator, app build/flavor, network, permissions, and lifecycle state checked
+- Mobile Evidence: crash/log artifact, screenshot/video, deep-link command, device test, KMP test, or human-in-the-loop script
+- Platform Parity: impacted platform, comparison platform, shared boundary, and skipped platform checks
+- Mobile Prevention: regression test, device-matrix note, crash/logging improvement, runbook step, or durable mobile constraint memory
+
+## Memory Guidance
+
+Persist durable mobile lessons only after recall and importance scoring:
+
+- Platform-specific root causes that future agents might misdiagnose
+- KMP or native bridge boundary decisions
+- Reusable device commands, simulator/emulator recipes, or log-filter commands
+- Mobile verification matrices that prevent repeated false confidence
+- OS-version, permission, lifecycle, or build-flavor gotchas with project impact

package/skills/massa-ai/references/mobile-figma-matcher/ATTRIBUTION.md

@@ -0,0 +1,5 @@
+# Attribution
+
+The mobile Figma guidance adapts concepts from OpenAI's `figma-implement-design` skill in `openai/skills`, including ordered Figma MCP extraction, screenshots, variables, Code Connect, asset handling, project-convention translation, component reuse, iterative validation, examples, and troubleshooting.
+
+The upstream material is licensed under the Apache License 2.0. This repository includes that license at the root `LICENSE` file. The adapted guidance has been substantially modified for massa-ai routing, deterministic evidence, Android Views, Android Compose, UIKit, SwiftUI, Compose Multiplatform, target-module detection, temporary asset persistence, audit reports, and report-driven remediation.

package/skills/massa-ai/references/mobile-figma-matcher/android-compose.md

@@ -0,0 +1,13 @@
+# Android Jetpack Compose Figma Contract
+
+Load this reference only for Target Surface Packet rows classified as Android Jetpack Compose.
+
+- Resolve composables, modifiers, layout primitives, Material/theme tokens, typography, shapes, painters/assets, state holders, previews/providers, navigation entry, semantics, and test tags affecting the surface.
+- Distinguish Android-only Compose from Compose Multiplatform using module and source-set evidence.
+- Normalize Figma pixels against density for `dp`; compare typography using `sp`, font scale, font metrics, line height, and wrapping.
+- Record device/viewport, density, orientation, API, theme/UI mode, locale, font scale, `WindowInsets`, app variant, and content state.
+- Verify adaptive layouts, RTL, clipping, elevation, recomposed visual states, minimum touch targets, TalkBack semantics/order, keyboard/focus behavior, and state restoration when applicable.
+- Preserve established Navigation Compose or host navigation ownership, state hoisting, system back handling, Material interaction feedback, focus/IME behavior, and lifecycle restoration. Require product requirements for transitions or interactions not represented by Figma.
+- Prefer existing theme tokens and shared composables when semantics, states, accessibility, and resolved values match.
+- Use existing previews, Compose screenshot tests, Compose UI tests, instrumentation, emulator/device harnesses, and optional Maestro evidence.
+- Do not weaken assertions, semantics, test tags, or screenshot baselines to make parity appear successful.