@massa-ai/cursor-plugin 1.6.0

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

@@ -0,0 +1,13 @@
+# Android Views Figma Contract
+
+Load this reference only for Target Surface Packet rows classified as Android Views XML.
+
+- Resolve `res/layout`, qualifiers, includes/merges, styles/themes, dimensions, colors/selectors, text appearances, drawables, fonts, strings, binding/adapters, and Material components affecting the surface.
+- Follow aliases to final values. Record the symbolic resource chain and resolved value.
+- Normalize Figma pixels against Android density before comparing `dp`; compare text using `sp`, font scale, font metrics, line height, and actual wrapping.
+- Record device/viewport, density, orientation, API, theme/UI mode, locale, font scale, system bars/insets, app variant, and content state.
+- Verify constraints, weights, intrinsic sizing, RTL, clipping, elevation, state drawables, minimum touch targets, TalkBack labels/order, and keyboard/focus behavior when represented or required.
+- Preserve the repository's Activity/Fragment/navigation ownership, system back behavior, Material interaction feedback, focus traversal, IME handling, and lifecycle-safe state restoration. Figma may represent appearance and selected states but does not define these behaviors by itself.
+- Prefer established styles, resources, and shared Views components over duplicated local values when their resolved behavior matches.
+- Use existing layout previews/renderers, screenshot tests, instrumentation, Espresso/UIAutomator, emulator/device harnesses, and optional Maestro evidence.
+- Never approve or regenerate a screenshot baseline solely to hide a mismatch.

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

@@ -0,0 +1,117 @@
+# Mobile Figma Core
+
+Use this shared reference after `repository-detection.md` identifies one or more target surfaces. It defines Figma evidence, requirements boundaries, asset handling, mapping and comparison semantics, runtime evidence, and parity-claim limits. Load only the platform references named by the Target Surface Packet.
+
+## Boundaries
+
+- Supported UI stacks are Android Views XML, Android Jetpack Compose, iOS UIKit, iOS SwiftUI, and Kotlin Multiplatform Compose Multiplatform.
+- Flutter, React Native, web styling, generic Figma exploration, variable-only queries, and MCP troubleshooting are out of scope.
+- Figma MCP is mandatory design evidence. A screenshot or pasted description alone is not a design contract.
+- Figma defines visible design intent and represented variants. Product behavior, navigation, data, analytics, error handling, and state transitions require a separate requirements source.
+- Accessibility, platform conventions, localization, safe areas/insets, minimum touch targets, Dynamic Type/font scale, and explicit product requirements outrank literal replication when supported by evidence. Record these as `CONSTRAINT DEVIATION`.
+
+## Figma Evidence Packet
+
+Build one packet per selected Figma node or desktop selection:
+
+```text
+Figma File/Selection: <URL, file key, or desktop selection>
+Figma Node: <node ID and name>
+Figma Evidence Timestamp: <local timestamp>
+Metadata: <node outline or not needed>
+Design Context: <nodes fetched>
+Screenshot: <artifact/tool result>
+Variables: <variable names, aliases, and resolved values>
+Code Connect: <mapped components or none>
+States/Variants: <default, pressed, disabled, loading, error, dark, etc.>
+Annotations: <relevant design notes or none>
+Assets: <asset inventory and intended repository destinations>
+```
+
+- Use `get_metadata` first for a large or truncated selection, then fetch only relevant children with `get_design_context`.
+- Always obtain `get_design_context` and `get_screenshot` for each comparison frame.
+- Use `get_variable_defs` to resolve colors, typography, spacing, effects, and aliases.
+- Use current Code Connect mappings when available, but verify every mapping against current source and semantics.
+- Treat generated React, Tailwind, or other sample output as design representation, never implementation guidance for a mobile stack.
+- Stop if the selected node cannot be read. Do not replace structured Figma evidence with visual inference.
+
+## Asset Contract
+
+- Inventory images, icons, SVGs, vectors, animations, and fonts returned by Figma before editing.
+- Figma MCP asset URLs, including localhost URLs, are temporary transport endpoints. Save required assets into the target repository using its existing asset pipeline and reference the durable project asset.
+- Do not leave temporary MCP URLs in source, tests, fixtures, documentation, or generated configuration.
+- Reuse an existing project asset only after verifying visual content, semantics, licensing, scale behavior, and platform rendering.
+- Do not install icon packages or create placeholders when the design supplies the real asset.
+- Preserve vector data when the target stack supports it; otherwise record any conversion and verify rendered output.
+
+## Design-To-Code Mapping Matrix
+
+Before implementation, or as the basis of an audit, map every visible in-scope element and required state:
+
+| ID | Surface ID | Figma Element/State | Existing Component/Token/Asset | Intended Implementation | Requirements Source | Validation Sensor |
+|---|---|---|---|---|---|---|
+
+- Reuse existing components only when semantics, states, accessibility, and visual contract match.
+- Prefer established tokens when their resolved values satisfy the Figma contract. A name match is not evidence.
+- When project tokens differ materially, report the conflict and choose the smallest scoped change that preserves system consistency and design intent.
+- Do not promote a screen-local need into a shared design-system API without evidence of reuse or an established local pattern.
+
+## Runtime Sensors And Maestro
+
+Use the cheapest existing sensor that proves the claim:
+
+1. Static source, resource, token, and asset resolution.
+2. Existing previews, layout renderers, or screenshot/snapshot tests.
+3. Existing instrumentation, XCTest, UI tests, or project render harnesses.
+4. Existing emulator, simulator, or device workflow.
+5. Optional Maestro MCP/CLI evidence.
+6. Human or model visual comparison only as labeled `inferential-visual` evidence.
+
+Detect Maestro MCP, Maestro CLI, device availability, and applicable existing flows independently. Prefer existing safe flows and fixed configurations. Never install Maestro, start a device, clear app state, change permissions, seed accounts, mutate backend data, or run a destructive flow without explicit approval. Temporary approved flows stay outside tracked source and do not count as durable regression coverage.
+
+A passing flow proves reachability and interaction for the tested journey. It does not prove Figma parity. A screenshot is runtime evidence only when its surface, configuration, state, and provenance are recorded.
+
+Sensor matrix:
+
+| Need | Required evidence |
+|---|---|
+| Relevant state | Explicit Figma variant, requirement, platform default, or touched code path names the state. |
+| Token match | Resolved value equality or documented tolerance from Figma variable -> project token/resource -> rendered value. Name equality alone is insufficient. |
+| Static parity | Source/resource/asset/constraint chain resolves every in-scope row. |
+| Runtime parity | Static parity plus screenshot/snapshot/render/device evidence with surface, configuration, state, and provenance. |
+| Maestro evidence | Existing safe flow only; do not create tracked flows or mutate app/backend/device state without approval. |
+| Complete parity | No unexplained `MISMATCH`, no required `NOT EVALUATED`, and strongest safe runtime sensor recorded for every in-scope surface. |
+
+## Comparison Matrix
+
+Use one complete matrix across all selected surfaces:
+
+| ID | Surface ID | Element/State | Property/Constraint | Figma Value | Resolved Implementation Value | Runtime Evidence | Evidence Class | Status | Confidence | Fix Direction |
+|---|---|---|---|---|---|---|---|---|---|---|
+
+Evidence classes:
+
+- `deterministic-source`: resolved source, token, resource, asset, or constraint evidence.
+- `deterministic-runtime`: measured hierarchy, geometry, snapshot result, UI assertion, or fixed-configuration artifact.
+- `inferential-visual`: labeled visual comparison without deterministic measurement.
+- `missing`: required evidence is unavailable or unsafe to obtain.
+
+Statuses:
+
+- `MATCH`: sufficient evidence supports parity for the row and configuration.
+- `MISMATCH`: concrete evidence shows a difference without an overriding constraint.
+- `CONSTRAINT DEVIATION`: an evidenced platform, accessibility, localization, safe-area, or product constraint intentionally differs.
+- `NOT EVALUATED`: evidence is unavailable, ambiguous, stale, or unsafe to obtain.
+
+Only `MISMATCH` rows create `MFM-*` findings. Every row and finding must retain its `Surface ID`.
+
+## Claim Rules
+
+- Never claim complete parity while an in-scope surface has unexplained `MISMATCH` or required `NOT EVALUATED` rows. `NOT EVALUATED` always blocks complete parity for the affected surface.
+- Complete parity requires fixed Figma evidence, a Target Surface Packet, per-surface configurations, deterministic source evidence, strongest available runtime sensors, zero unexplained mismatches, and explicit residual risk.
+- A shared KMP row may match statically while Android or iOS runtime rows remain `NOT EVALUATED`; report those separately.
+- When only source evidence exists, state: `Resolved implementation values align with the extracted Figma contract; runtime visual parity was not evaluated.`
+
+## Attribution
+
+Read `ATTRIBUTION.md` when modifying this contract or redistributing adapted Figma implementation guidance.

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

@@ -0,0 +1,12 @@
+# iOS SwiftUI Figma Contract
+
+Load this reference only for Target Surface Packet rows classified as iOS SwiftUI.
+
+- Resolve `View` composition, modifiers, layout containers, environment values, state selection, navigation entry, styles, asset catalogs, symbols, fonts, previews, accessibility modifiers, and UIKit hosting/interoperability affecting the surface.
+- Compare Figma coordinates with SwiftUI points, then account for display scale only for rendered-pixel evidence.
+- Record device/viewport, display scale, orientation, OS version, size classes, color scheme, locale, Dynamic Type category, safe-area assumptions, app scheme/build, and content state.
+- Verify proposed/ideal sizing, layout priorities, safe areas, adaptive stacks/grids, RTL, clipping, shadows, SF Symbols, Dynamic Type, minimum targets, VoiceOver labels/traits/order, focus, and represented state transitions.
+- Preserve established `NavigationStack`, tab, sheet/full-screen-cover, dismissal, gesture, focus/keyboard, sensory feedback, scene state, and restoration ownership. Require product requirements for interactions or transitions not represented by Figma.
+- Prefer established styles, environment tokens, and reusable views when semantics, states, accessibility, and resolved values match.
+- Use existing previews, snapshot tests, XCTest/XCUITest, simulator/device workflows, accessibility inspection, and optional Maestro evidence.
+- Do not add fixed frames or disable Dynamic Type solely to force one screenshot to match.

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

@@ -0,0 +1,12 @@
+# iOS UIKit Figma Contract
+
+Load this reference only for Target Surface Packet rows classified as iOS UIKit.
+
+- Resolve storyboards, XIBs, programmatic views, view controllers, reusable views/cells, Auto Layout constraints, appearance APIs, trait-dependent resources, asset catalogs, fonts, strings, and state configuration.
+- Compare Figma coordinates with UIKit points, then account for device display scale only when validating rendered pixels.
+- Record device/viewport, display scale, orientation, OS version, size classes, appearance, locale, content-size category, safe-area assumptions, app scheme/build, and content state.
+- Verify intrinsic content size, content hugging/compression resistance, safe-area guides, readable-content guides, RTL, clipping, shadows, SF Symbols configuration, Dynamic Type through `UIFontMetrics`, minimum targets, and UIAccessibility labels/traits/order.
+- Preserve established `UINavigationController`, tab, sheet, presentation, dismissal, gesture, keyboard, focus, haptic, and state-restoration behavior. Apply Apple platform conventions when Figma omits native interaction details.
+- Prefer established UIKit components, appearance tokens, and asset-catalog resources when their semantics and resolved behavior match.
+- Use existing previews/render harnesses, snapshot tests, XCTest/XCUITest, simulator/device workflows, accessibility inspection, and optional Maestro evidence.
+- Do not rewrite snapshot references or accessibility identifiers merely to hide a mismatch.

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

@@ -0,0 +1,14 @@
+# KMP Compose Multiplatform Figma Contract
+
+Load this reference only for shared Compose Multiplatform Target Surface Packet rows.
+
+- Resolve common composables, shared state, theme/design tokens, Compose resources, adaptive layout, accessibility semantics, platform adapters, and `expect`/`actual` declarations affecting presentation.
+- Keep business/domain behavior in established shared boundaries. Do not move platform-only UI behavior into common code merely to reduce duplication.
+- Keep navigation hosting, system back/dismissal, permissions, keyboard/focus integration, haptics, lifecycle, and other platform-native UX behind established shared interfaces or platform adapters. Do not force identical mechanics when Android and iOS conventions differ.
+- Compare shared layout values using Compose density-independent units and typography scaling, but record runtime configurations separately for Android and iOS targets.
+- Audit common composables and resources once. Create distinct runtime rows for each requested Android and iOS target because insets, font rendering, accessibility, resource loading, and host integration differ.
+- Load Android Compose for Android-only source sets or hosts, Android Views for XML interop, UIKit for UIKit hosts/wrappers, and SwiftUI for SwiftUI hosts/wrappers.
+- Verify `expect`/`actual`, resource lookup, platform painters/fonts, safe-area/inset adapters, lifecycle/host integration, and platform accessibility when they affect the surface.
+- Prefer shared components and tokens only when they are already the correct ownership boundary. Apply a shared root fix before platform-local overrides when evidence shows a shared cause.
+- Use existing common tests, platform compilation, previews, snapshot/screenshot tests, Android/iOS UI harnesses, and optional Maestro evidence.
+- If one affected platform cannot be rendered or tested, mark its runtime rows `NOT EVALUATED`; do not infer parity from the other platform.

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

@@ -0,0 +1,77 @@
+# Mobile Figma Repository Detection
+
+Use this reference before loading any stack-specific matcher reference. Classify the concrete target module and files, not the repository root or repository name.
+
+Monorepositories may contain several valid mobile stacks; classify only modules connected to the requested target.
+
+## Target Surface Packet
+
+Produce one immutable packet before Figma extraction or implementation comparison:
+
+```text
+Repository Classification: <Android | iOS | KMP | monorepo/mixed>
+Target Feature/Flow: <requested target>
+Target Module(s): <module paths>
+Surface IDs: <stable IDs used by matrices and findings>
+Surface Matrix: <surface ID -> module/source set -> UI stack -> Figma node -> runtime targets>
+Detection Evidence: <build files, manifests/projects, source sets, imports, resources, entry points>
+Ambiguities Resolved: <evidence or user decision>
+Excluded Surfaces: <found but out of scope, with reason>
+```
+
+## Detection Order
+
+1. Resolve the requested feature, flow, files, symbols, commits, branch comparison, or modified-file set.
+2. Locate candidate modules using build configuration, manifests/projects, source sets, and ownership boundaries.
+3. Classify each target surface using at least one build/configuration signal and one source/resource signal when available.
+4. Map each selected surface to its Figma node. A single node may map to several surfaces; separate platform frames require explicit mappings.
+5. Load only the references required by selected surface IDs.
+
+## Stack Signals
+
+### Android Views XML
+
+- Android Gradle plugin or Android module plus `AndroidManifest.xml`.
+- `res/layout`, layout qualifiers, data/view binding, layout inflation, `View`/`ViewGroup`, Fragment/Activity views, story-equivalent navigation hosts, or XML Material components.
+
+### Android Jetpack Compose
+
+- Android Gradle plugin plus Compose build features/compiler/dependencies.
+- `setContent`, `@Composable`, `androidx.compose` imports, Compose navigation, previews, or Compose UI tests.
+
+### iOS UIKit
+
+- Xcode project/workspace or Swift package with Apple platform target.
+- `import UIKit`, `UIView`, `UIViewController`, `AppDelegate`/`SceneDelegate`, storyboards, XIBs, Auto Layout constraints, or UIKit snapshot/UI tests.
+
+### iOS SwiftUI
+
+- Xcode project/workspace or Swift package with Apple platform target.
+- `import SwiftUI`, `View`, `@main App`, hosting controllers, previews, SwiftUI navigation, or SwiftUI snapshot/UI tests.
+
+### KMP Compose Multiplatform
+
+- Kotlin Multiplatform plugin and source sets such as `commonMain`, `androidMain`, `iosMain`, or configured equivalents.
+- Compose Multiplatform plugin/dependencies and shared `@Composable` UI in a common source set.
+- Common resources, shared UI modules, platform adapters, and `expect`/`actual` declarations affecting presentation.
+
+## Mixed And KMP Composition
+
+- Do not classify every Compose file in a KMP repository as shared.
+- Shared Compose UI in `commonMain` or the configured common UI source set loads the KMP contract.
+- Compose in `androidMain`, an Android application module, or Android-only host loads Android Compose.
+- Android XML hosts or interop load Android Views in addition to any shared KMP contract.
+- Swift/UIKit/SwiftUI hosts, wrappers, or surrounding native screens load the matching iOS contract.
+- Audit shared composables once, then capture and report runtime evidence separately for each requested Android or iOS target.
+- When a shared fix affects both targets, verify both. Unavailable targets remain `NOT EVALUATED` with explicit risk.
+
+## Ambiguity Gate
+
+Ask the user only when evidence cannot resolve one of these cases:
+
+- The requested feature maps to multiple plausible modules.
+- Legacy and replacement UI stacks both implement the target with no current ownership evidence.
+- Shared Compose Multiplatform UI serves Android and iOS but requested runtime coverage is unspecified.
+- Separate Figma platform frames cannot be mapped reliably to code surfaces.
+
+Do not ask merely because the repository contains several mobile stacks. Exclude unrelated surfaces and record why.

package/skills/massa-ai/references/naming-standards.md

@@ -0,0 +1,47 @@
+# Naming Standards
+
+Use this reference when a workflow writes code, drafts implementation contracts, audits code quality, or executes findings that introduce, rename, or preserve identifiers.
+
+## Goal
+
+Names must explain the role, domain concept, or contract they represent without forcing a future agent to infer intent from surrounding code alone.
+
+## Source Order
+
+Prefer naming evidence in this order:
+
+1. Current source and public contracts.
+2. `CONTEXT.md`, glossary files, product docs, specs, tickets, ADRs, and TDDs.
+3. Existing tests, fixtures, schemas, routes, events, commands, screens, and use-case names.
+4. Local surrounding-code vocabulary when no stronger source exists.
+
+Code vocabulary is evidence, not truth. When business intent is inferred only from names, mark it as an inference or keep the existing term until stronger evidence exists.
+
+## Rules
+
+- Use domain vocabulary for business concepts, state, policy, workflows, and persisted data.
+- Name technical plumbing by exact role: parser, adapter, transport, serializer, cache, fixture, validator, resolver, mapper, projection, or report.
+- Replace vague names such as `data`, `info`, `result`, `value`, `temp`, `obj`, `item`, `list`, `manager`, `handler`, and `helper` when a more specific role or concept is known.
+- Keep short generic names only for narrow, conventional scopes where they increase clarity: loop indexes, tuple destructuring, common callback names, test placeholders, tiny local transforms, or framework-required signatures.
+- Prefer naming the invariant over naming the implementation detail when that invariant is what callers depend on.
+- Do not rename public contracts, persisted fields, event names, API parameters, CLI flags, fixture keys, or snapshot/test identifiers unless compatibility and migration impact are explicitly in scope.
+- When a rename is the fix, update all call sites, docs, tests, fixtures, snapshots, and generated examples that form the contract; do not weaken validation assets to hide drift.
+- Avoid fabricated domain terms. If no meaningful name is supported by evidence, choose the most precise technical role name and leave the domain uncertainty explicit in the plan, TDD, or audit.
+
+## Workflow Use
+
+- Feature, spec-driven execution, and implementation execution use this before writing or changing identifiers.
+- TDD uses this when naming proposed components, modules, states, events, schemas, or data fields.
+- Code-quality audit uses this to distinguish real vague-name findings from harmless conventional short names.
+- Code-quality execution uses this to choose precise replacements and protect public compatibility during renames.
+
+## Verification
+
+Before completion, perform a focused diff review for touched identifiers:
+
+- New or renamed identifiers use domain or role-specific vocabulary.
+- Remaining generic names are narrow, conventional, or externally required.
+- Public contracts and persisted names were preserved unless compatibility handling was part of the task.
+- Tests, fixtures, snapshots, schemas, docs, and examples were not weakened to make a rename pass.
+
+Report skipped naming checks when the task does not touch code or design identifiers.

package/skills/massa-ai/references/pr-task-fix.md

@@ -0,0 +1,80 @@
+# PR Task Fix
+
+Load this reference from `workflows/feature.md` and `workflows/refactor.md` before non-trivial implementation or refactor execution that can be decomposed into reviewable task groups.
+
+## ADR/TDD Input Gate
+
+Before decomposition, inspect the first user prompt, current prompt context, explicitly attached or readable local files, and any already supplied Atlassian MCP source pointers.
+
+If there is no ADR or TDD plain text, no attached/readable ADR or TDD file, and no already supplied Atlassian ADR/TDD source, ask whether the user wants to provide an ADR or TDD through Atlassian MCP. Do not ask again when the user has already supplied, declined, or made Atlassian unavailable for this run.
+
+Use ADR/TDD input as implementation context, not as permission to bypass the active workflow's scope, source verification, or verification recipe. If the ADR/TDD conflicts with current source or project instructions, surface the conflict and resolve it before implementation.
+
+## PR Task Grouping
+
+Decompose work into reviewable PR groups before editing. Reuse the TDD task-planning contract:
+
+- Prefer Small PRs: `1-200 LOC / 1-3 files`, with a practical sweet spot under `50-100 LOC`.
+- Use Medium PRs: `201-500 LOC / 3-10 files` only when splitting further would break buildability, testability, UI coherence, or implementation dependency order.
+- Treat Large PRs: `500+ LOC / 10+ files` as exceptions requiring a split, stacked PR, feature-flag, or containment rationale before execution.
+
+Every PR group must be independently buildable and testable. It must not leave an intermediate state that breaks tests, UI, migrations, public contracts, required runtime behavior, or the active workflow's verification recipe.
+
+If a group is too large, split it into two or more groups. If tasks are too small, merge related small work only when the merged group remains independent, reviewable, buildable, and testable.
+
+Order non-breaking groups by layer when applicable:
+
+1. `Data`: DTOs, DAOs, data sources, repositories, analytics, persistence, and data-layer interfaces.
+2. `Domain`: use cases, models, mappers, configs, exceptions, monitoring, and business rules.
+3. `Presentation/Navigation`: screens, views, view models, actions, states, routes, and navigation.
+
+When the target project uses different boundaries, map these labels to the closest repository terms and state the mapping before execution.
+
+## Commit Per Group
+
+For each PR group:
+
+1. Implement only that group's scoped work.
+2. Run the active workflow's verification recipe for that group.
+3. Invoke `workflows/commit.md` to draft or create the commit.
+
+Do not duplicate raw commit-message, staging, audit-file exclusion, or Jira-prefix rules here. The commit workflow remains authoritative for commit safety and message generation.
+
+If stacked branching is declined, unavailable, or not applicable, continue sequentially on the current branch and still use the commit workflow after each verified group.
+
+## Jira-Key Stacked Branches
+
+After the PR groups are stable, inspect their Jira keys. Offer stacked branch automation only when every PR group has a confirmed Jira key. Do not create Jira tickets from this reference; ticket creation remains owned by `workflows/ticket.md`.
+
+If every group has a Jira key, ask whether the user wants to automatically create separate stacked branches for each Jira task. If the user accepts, ask for:
+
+- the base branch to branch off for the first task
+- a branch name pattern containing the exact token `<jira-task-key>`, for example `features/<jira-task-key>`
+
+Normalize Jira keys with the commit workflow regex semantics before substitution, preserving uppercase keys unless the user explicitly supplies a lowercase pattern rule. Reject a branch pattern that omits `<jira-task-key>`.
+
+Before creating branches:
+
+- Verify the working tree is in a safe state for branch creation.
+- Resolve the base branch and fail early if it is missing.
+- Derive all branch names and check for duplicates or existing local branch name collisions.
+- Do not push any branch.
+
+Create branches as a stack:
+
+1. Create the first task branch from the user-selected base branch.
+2. Implement, validate, and commit the first PR group through `workflows/commit.md`.
+3. Create the second task branch from the first task branch, not from the original base.
+4. Repeat until every task branch has its implementation, verification, and commit.
+
+If a branch creation, implementation, verification, or commit fails, stop at that branch, report completed branches and commits, and leave the next exact resume step. Do not skip ahead to later branches.
+
+## Completion Report
+
+At completion, report:
+
+- ADR/TDD source outcome: supplied, Atlassian provided, declined, unavailable, or not needed.
+- PR groups in execution order, with layer, size, Jira key, verification result, and commit result.
+- All created branches and commits in the order they should be pushed.
+- Explicit `No branches were pushed`.
+- Skipped checks, residual risks, memory outcome, and active workflow Evidence Gate status.

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

@@ -0,0 +1,76 @@
+# Project Context Intake
+
+Use this reference at the start of every workflow, before the first substantive
+read, edit, plan, or answer. It defines the minimum project-context sweep that
+makes agent behavior match this repository's actual conventions instead of
+generic defaults.
+
+## Principle
+
+Host and project instruction files are the highest-precedence description of how
+work is done here. Reading them is cheaper than discovering their rules by
+failing a gate. Read them once per session, honor precedence, and never re-read
+what is already loaded.
+
+## Intake Sweep
+
+Read in this order. Stop at the first tier that answers the current question;
+continue only when the next decision still needs more.
+
+| Tier | Sources | Answers |
+| --- | --- | --- |
+| 1 — Agent contract | `AGENTS.md`, `CLAUDE.md`, and any nearest-ancestor copy between the repo root and the working directory | Startup contract, routing, mandatory policies, forbidden actions |
+| 2 — Host config | `.claude/` (`settings.json`, `settings.local.json`, `commands/`, `agents/`, `skills/`, `hooks/`), `.cursor/` (`rules/`, `mcp.json`), `.github/copilot-instructions.md`, `.opencode/`, `.codex/` | Permissions, hooks, host-specific tooling, MCP registrations |
+| 3 — Product docs | `README.md`, `CONTRIBUTING.md`, `docs/`, `ARCHITECTURE.md` | Install/run/build surface, contribution protocol, architecture |
+| 4 — Delivery config | `.github/workflows/`, `CHANGELOG.md`, `package.json` / `Cargo.toml` / `build.gradle*` / `pyproject.toml`, `.tool-versions`, `mise.toml`, `Makefile` | CI gates, release rules, runtime and toolchain pins, task commands |
+| 5 — Live state | `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, `.specs/LESSONS.md` | In-flight work, decisions already made, confirmed lessons |
+
+Tier 1 and Tier 3 (`README.md`) are mandatory in every workflow. Tiers 2, 4, and
+5 are read when the task touches host tooling, a gate/release surface, or
+in-flight spec work respectively.
+
+## Precedence
+
+When two sources conflict, the higher tier wins:
+
+1. Explicit user instruction in the current turn.
+2. System/developer instructions.
+3. Nearest-ancestor `AGENTS.md` / `CLAUDE.md` (deeper path beats repo root).
+4. Repo-root `AGENTS.md` / `CLAUDE.md`.
+5. `CONTRIBUTING.md`, then `README.md`, then `docs/`.
+6. Current repository source code.
+7. Recalled memory — context only, never canonical.
+
+A conflict between a doc and current source is a finding: report it rather than
+silently picking a side.
+
+## Dedupe Guard
+
+- Run the sweep once per conversation. Record which tiers were read.
+- Do not re-read a file because a later workflow or reference names it.
+- On a `git pull`, branch switch, or worktree change, re-read Tier 1 and Tier 4 only.
+- Loading a file is not the same as applying it — state which rule you took from it.
+
+## Size And Hygiene
+
+- Apply `references/context-firewall.md` thresholds to every file in the sweep.
+  A `README.md` over 200 lines is summarized, not pasted.
+- Honor the global ignore paths from the `AGENTS.md` bootstrap block. Never index
+  or read `node_modules/`, `dist/`, `build/`, `target/`, `.venv/`, `.env*`,
+  `*.pem`, `*.key`, `.ssh/`, or `secrets.json` during intake.
+- Never echo secrets found in a config file. Report the key name only.
+
+## Failure Handling
+
+| Condition | Behavior |
+| --- | --- |
+| File absent | Record it as absent and continue. Absence is evidence, not an error. |
+| No `AGENTS.md` and no `CLAUDE.md` | Say the project has no agent contract; fall back to `README.md` + `CONTRIBUTING.md`. |
+| Not a repository | Skip Tiers 4 and 5; run Tiers 1–3 against the working directory. |
+| Conflicting nested contracts | Apply the nearest ancestor, and report the divergence once. |
+| Sweep would exceed the context budget | Summarize per file to its rules-that-apply, and name what was summarized. |
+
+## Output
+
+Report the sweep in one line: which tiers were read, and the rules taken from
+them that change this task's behavior. Do not restate file contents.

package/skills/massa-ai/references/rfc/ATTRIBUTION.md

@@ -0,0 +1,5 @@
+# Attribution
+
+RFC authoring guidance in this directory adapts material by [Tech Leads Club](https://github.com/tech-leads-club), originally distributed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).
+
+The material has been modified and integrated into the `massa-ai` workflow architecture. Tech Leads Club does not endorse this adaptation.

package/skills/massa-ai/references/rfc/discovery-and-sizing.md

@@ -0,0 +1,120 @@
+# RFC Discovery And Classification
+
+Load this reference before source investigation, RFC classification, impact selection, or clarification questions.
+
+## Workflow Fit
+
+- Use RFC when the decision is open, at least two directions deserve comparison, and stakeholders need feedback or approval.
+- Use ADR when a significant architecture decision is finalized or being formally recorded.
+- Use TDD when the direction is settled and implementation architecture, contracts, rollout, and verification remain.
+- Use spec-driven when the request spans requirements, design, task planning, and implementation.
+- Use a feature, refactor, debug, or general workflow when a durable stakeholder proposal would add no decision value.
+
+Route matrix:
+
+| User state | Route |
+|---|---|
+| One architecture decision is selected and needs durable consequences recorded | ADR |
+| Two or more options remain open, decision criteria are needed, or stakeholders must review before choosing | RFC |
+| Direction is selected and implementation architecture/contracts/rollout need a blueprint | TDD |
+| Requirements, design, tasks, and execution all need staged approval | Spec-driven |
+
+Source relevance requires the source to name at least one target, constraint, risk, dependency, public contract, option, decision criterion, stakeholder, cost, rollout path, or rejected approach for this RFC. Style-only examples cannot support factual claims.
+
+## Evidence Order
+
+Use the narrowest authoritative evidence first:
+
+1. Current repository source, schemas, tests, configuration, and project instructions.
+2. Existing RFC templates and conventions, approved ADRs/TDDs, tickets, metrics, incident records, and supplied research.
+3. Relevant current massa-ai memories, treated as evidence rather than authority.
+4. Internal MCP sources such as Jira, Linear, Confluence, or NotebookLM when supplied or available and relevant.
+5. Official dependency, vendor, standard, or regulatory documentation.
+6. Broader external research only when authoritative local or official evidence cannot answer a material question.
+
+Distinguish verified facts, evidence-backed inferences, generated estimates, proposed choices, and unresolved facts. Record the source of consequential claims. When sources conflict and authority remains unclear, ask rather than silently choosing one.
+
+## RFC Types
+
+Classify the proposal and emphasize its domain concerns:
+
+| Type | Required emphasis |
+|---|---|
+| Technical/Architecture | system boundaries, compatibility, migration path, technical and operational risks |
+| Process/Workflow | team impact, ownership, adoption, enforcement, pilot, and rollback if the process fails |
+| Product/Feature | user impact, success metrics, go/no-go criteria, adoption, and support implications |
+| Vendor/Tool Selection | capability fit, total cost, lock-in, support, security, exit strategy, and evaluation evidence |
+| Policy/Compliance | obligations, scope, enforcement, exceptions, audit trail, ownership, and review cadence |
+
+## Impact Labels
+
+Every RFC must use one preserved label with a short justification:
+
+- `HIGH`: affects multiple teams, systems, user groups, material cost, sensitive data, compliance, public compatibility, or a difficult-to-reverse decision.
+- `MEDIUM`: materially affects one team or system, has non-trivial adoption or operational cost, or requires coordinated rollout.
+- `LOW`: limited scope, low coordination cost, and easy reversibility, while still benefiting from explicit stakeholder alignment.
+
+## Provider-Specific AskQuestion
+
+When mandatory context is missing and the provider exposes `AskQuestion`, use it instead of an unstructured question dump. Preserve these question IDs and choices so separate runs gather consistent inputs:
+
+```json
+{
+  "title": "RFC Information",
+  "questions": [
+    {
+      "id": "rfc_topic",
+      "prompt": "What is the topic or change you want to propose?",
+      "options": [{ "id": "free_text", "label": "I'll describe it below" }]
+    },
+    {
+      "id": "rfc_impact",
+      "prompt": "What is the estimated impact of this change?",
+      "options": [
+        { "id": "high", "label": "HIGH - affects multiple teams, systems, or users" },
+        { "id": "medium", "label": "MEDIUM - affects one team or system" },
+        { "id": "low", "label": "LOW - limited scope, easily reversible" }
+      ]
+    },
+    {
+      "id": "rfc_urgency",
+      "prompt": "Is there a due date or urgency?",
+      "options": [
+        { "id": "urgent", "label": "Yes, we need a decision soon" },
+        { "id": "planned", "label": "Part of planned roadmap" },
+        { "id": "open", "label": "No fixed deadline" }
+      ]
+    },
+    {
+      "id": "rfc_options",
+      "prompt": "Do you have options or alternatives in mind?",
+      "options": [
+        { "id": "yes", "label": "Yes, I have 2+ options to compare" },
+        { "id": "one", "label": "I have a preferred option and need alternatives" },
+        { "id": "no", "label": "No, help me structure options" }
+      ]
+    }
+  ]
+}
+```
+
+Follow with focused `AskQuestion` calls for missing RACI roles, assumptions, criteria, weights, or options. If `AskQuestion` is unavailable, ask equivalent concise questions in conversation. Ask in the user's language and do not re-ask supplied or discoverable facts.
+
+## Mandatory Inputs
+
+Do not finalize the RFC without:
+
+- a clear action-oriented title and evidence-backed background
+- full RACI: Driver, Approver or Approvers, Contributors, and Informed parties
+- `HIGH`, `MEDIUM`, or `LOW` impact with justification
+- urgency or due date, including explicit `TBD` when the user cannot provide one
+- at least one assumption with owner, confidence, and invalidation trigger
+- at least two decision criteria defined before options, with numeric weights
+- at least two credible options and explicit status quo consideration
+- a recommendation tied back to the weighted criteria
+
+When a person or date is unknown, ask for it. If the user cannot supply it, keep the required field visible as `TBD`; never pretend it was resolved.
+
+## Language
+
+Write the RFC in the same language as the user's request unless another language is requested. Preserve technical identifiers, product names, standards, and common terms such as API, RFC, rollback, and stakeholder when translation would reduce clarity.