@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/references/spec-driven/design.md

@@ -0,0 +1,257 @@
+# Design
+
+Use this reference when the spec-driven flow includes a Design phase. The output is `.specs/features/<slug>/design.md`. **Goal**: define HOW to build it — architecture, components, what to reuse.
+
+**Skip this phase when:** The change is straightforward — no architectural decisions, no new patterns, no component interactions to plan. For simple features, design happens inline during Execute.
+
+## Include Design When
+
+- Architecture or module boundaries change.
+- Interfaces, API contracts, data models, migrations, or public compatibility change.
+- Security, privacy, auth, tenant, permission, or irreversible behavior is involved.
+- A reusable pattern, shared abstraction, or cross-component integration must be selected.
+- Multiple implementation approaches are plausible and the choice affects maintainability or verification.
+- Large/Complex work needs approach exploration before implementation.
+
+## Inputs
+
+- Approved `.specs/features/<slug>/spec.md`.
+- `.specs/features/<slug>/context.md` when present (locked decisions and Agent's Discretion decisions).
+- Current codebase patterns and contracts.
+- Relevant local docs, tests, and validation assets.
+- Active `.specs/project/STATE.md` decisions — read the `## Decisions` section before any architectural choice.
+- Existing lessons only when lesson artifacts already exist.
+
+## Process
+
+### 1. Load Context
+
+Read `.specs/features/<slug>/spec.md` before designing. If `.specs/features/<slug>/context.md` exists, load it too — it contains implementation decisions that constrain the design (layout choices, behavior preferences, interaction patterns). Decisions marked as "Agent's Discretion" are yours to decide.
+
+**Mandatory: read `.specs/project/STATE.md` `## Decisions` now.** This MUST happen before any architectural choices are made. Every `active` `AD-NNN` entry is a project-level constraint this design must conform to. If a decision from a prior feature conflicts with what is best for this feature, you have two options — both require an explicit choice:
+
+1. **Conform** — Design within the active constraint.
+2. **Supersede** — Append a new `AD-NNN` entry to `.specs/project/STATE.md` `## Decisions` that supersedes the old one (set the old entry's `status` to `superseded by AD-NNN`) and document the reason. The new decision becomes the project standard going forward.
+
+Silently ignoring an active decision is not an option — it creates invisible inconsistency across features.
+
+**Also load confirmed lessons** relevant to this feature: `python3 skills/massa-ai/scripts/lessons.py list --status confirmed` (filter with `--scope`/`--query`). These are past verification failures distilled into guidance — apply them while designing. Load only `confirmed`. Skip silently if no store or no code tool. See [lessons.md](lessons.md).
+
+### 1.5. Research (Optional but Recommended)
+
+If the feature involves unfamiliar technology, patterns, or integrations, research before designing. Document findings briefly in the design doc or as inline notes. This prevents incorrect assumptions from propagating into tasks.
+
+Follow the **Knowledge Verification Chain** (see SKILL.md) in strict order:
+
+```
+Codebase → Project docs → Context7 MCP → Web search → Flag as uncertain
+```
+
+When verifying codebase claims, prefer the massa-ai tool chain FIRST — `list_projects`, `search`, `project_map`, `optimized_context` — before falling back to ast-grep / ripgrep / grep. Apply freshness and source-precedence rules: current source code overrides a stale index, and a stale index or durable memory never overrides current evidence. When uncertain about index freshness, read the live file directly.
+
+**CRITICAL: NEVER assume or fabricate information.** If you cannot find an answer through the chain, explicitly say "I don't know" or "I couldn't find documentation for this". Inventing an API, a pattern, or a behavior that doesn't exist is far worse than admitting uncertainty. Wrong assumptions propagate through design → tasks → implementation and cause cascading failures.
+
+Good triggers for research: new libraries, unfamiliar APIs, performance-sensitive features, security-sensitive features, patterns you haven't used in this codebase before.
+
+**Concern flagging (MUST do while reading code):** While walking the codebase via the Knowledge Verification Chain, flag any concerns you encounter in the areas this feature touches. Capture each finding in the `## Risks & Concerns` section of `design.md`:
+
+- **Fragile code** — tight coupling, large functions, implicit state
+- **Tech debt** — hacks, workarounds, deprecated APIs
+- **Security risks** — unvalidated input, auth gaps, exposed secrets
+- **Performance bottlenecks** — N+1 queries, unbounded loops, missing indexes
+- **Test coverage gaps** — untested paths the feature depends on
+
+Every flagged concern MUST include a mitigation — how the design (or a follow-up task) addresses it.
+
+### 2. Define Architecture
+
+**Large/Complex only — approach exploration:** Before committing to a single architecture, present 2–3 viable approaches with trade-offs and a recommendation. Lead with the recommendation to avoid analysis paralysis. All approaches must deliver the same scoped thing (no alternative scopes). Confirm the chosen approach with the user before detailing components. Medium features: skip — design inline.
+
+Overview of how components interact. Use mermaid diagrams when helpful.
+
+### 3. Identify Code Reuse
+
+**CRITICAL**: What existing code can we leverage? This saves tokens and reduces errors.
+
+Flag any concerns found here per step 1.5 into `## Risks & Concerns`.
+
+### 4. Define Components and Interfaces
+
+Each component: Purpose, Location, Interfaces, Dependencies, What it reuses.
+
+### 5. Define Data Models
+
+If the feature involves data, define models before implementation.
+
+---
+
+## Required Sections
+
+`design.md` must include:
+
+- Design summary.
+- Requirements traceability by ID.
+- Current codebase evidence: files, symbols, conventions, and tests inspected.
+- Proposed structure and ownership.
+- Interface, data, migration, security/privacy, and compatibility decisions when applicable.
+- Active decision handling: conform to active `AD-NNN` decisions or add a superseding `AD-NNN` entry in `.specs/project/STATE.md`.
+- Artifact-store evidence: active artifact key, version, and checksum after write.
+- Reuse plan and rejected alternatives.
+- Large/Complex approach tradeoffs: 2-3 viable approaches, same scope, recommendation first, user-confirmed chosen approach.
+- Verification design, including how tests or checks prove each high-risk requirement.
+- Risks, concerns, and mitigations.
+
+## Decision Supersession
+
+When the design replaces an existing decision, never delete the old entry. Append a new `AD-NNN` entry, update the old entry status to `superseded by AD-NNN`, and record the reason, rejected alternatives, and evidence. The new decision becomes active only after it is written to `.specs/project/STATE.md` or the relevant approved artifact.
+
+## Knowledge Verification
+
+Use this order for technical claims:
+
+1. Current codebase.
+2. Project docs and approved specs.
+3. Context7 MCP or available local MCP source for current library behavior when relevant.
+4. Official documentation or primary source when current APIs or external services matter.
+5. Mark uncertainty explicitly when evidence is unavailable.
+
+Never invent APIs, project conventions, or external behavior.
+
+---
+
+## Template: `.specs/features/<slug>/design.md`
+
+````markdown
+# [Feature] Design
+
+**Spec**: `.specs/features/<slug>/spec.md`
+**Status**: Draft | Approved
+
+---
+
+## Architecture Overview
+
+[Brief description of the architecture approach]
+
+```mermaid
+graph TD
+    A[User Action] --> B[Component A]
+    B --> C[Service Layer]
+    C --> D[Data Store]
+    B --> E[Component B]
+```
+````
+
+---
+
+## Code Reuse Analysis
+
+### Existing Components to Leverage
+
+| Component            | Location            | How to Use                |
+| -------------------- | ------------------- | ------------------------- |
+| [Existing Component] | `src/path/to/file`  | [Extend/Import/Reference] |
+| [Existing Utility]   | `src/utils/file`    | [How it helps]            |
+| [Existing Pattern]   | `src/patterns/file` | [Apply same pattern]      |
+
+### Integration Points
+
+| System         | Integration Method                      |
+| -------------- | --------------------------------------- |
+| [Existing API] | [How new feature connects]              |
+| [Database]     | [How data connects to existing schemas] |
+
+---
+
+## Components
+
+### [Component Name]
+
+- **Purpose**: [What this component does - one sentence]
+- **Location**: `src/path/to/component/`
+- **Interfaces**:
+  - `methodName(param: Type): ReturnType` - [description]
+  - `methodName(param: Type): ReturnType` - [description]
+- **Dependencies**: [What it needs to function]
+- **Reuses**: [Existing code this builds upon]
+
+### [Component Name]
+
+- **Purpose**: [What this component does]
+- **Location**: `src/path/to/component/`
+- **Interfaces**:
+  - `methodName(param: Type): ReturnType`
+- **Dependencies**: [Dependencies]
+- **Reuses**: [Existing code]
+
+---
+
+## Data Models (if applicable)
+
+### [Model Name]
+
+```typescript
+interface ModelName {
+  id: string
+  field1: string
+  field2: number
+  createdAt: Date
+}
+```
+
+**Relationships**: [How this relates to other models]
+
+### [Model Name]
+
+```typescript
+interface AnotherModel {
+  id: string
+  // ...
+}
+```
+
+---
+
+## Error Handling Strategy
+
+| Error Scenario | Handling      | User Impact      |
+| -------------- | ------------- | ---------------- |
+| [Scenario 1]   | [How handled] | [What user sees] |
+| [Scenario 2]   | [How handled] | [What user sees] |
+
+---
+
+## Risks & Concerns
+
+| Concern | Location (file:line) | Impact | Mitigation |
+| ------- | -------------------- | ------ | ---------- |
+| [Fragile code / tech debt / security / perf / test gap] | `src/path/file.ts:42` | [What breaks or degrades] | [How the design or a follow-up task addresses it] |
+
+> None found — is a valid entry.
+
+---
+
+## Tech Decisions (only non-obvious ones)
+
+| Decision          | Choice          | Rationale     |
+| ----------------- | --------------- | ------------- |
+| [What we decided] | [What we chose] | [Why - brief] |
+
+> **Project-level decisions:** If a decision here sets a convention, pattern, or constraint that future features must follow, append it to `.specs/project/STATE.md` `## Decisions` as the next `AD-NNN` entry. Feature-local decisions stay only in this table.
+
+---
+
+## Tips
+
+- **Load context first** — If context.md exists, decisions there are locked.
+- **Research when uncertain** — 5 minutes of research prevents hours of rework.
+- **Reuse is king** — Every component should reference existing patterns.
+- **Interfaces first** — Define contracts before implementation.
+- **Keep it visual** — Diagrams save 1000 words.
+- **Small components** — If a component does 3+ things, split it.
+- **Flag concerns inline** — Risks found during research go in Risks & Concerns with a mitigation.
+- **Confirm before Tasks** — User approves design before breaking into tasks.
+
+## Done
+
+Design is done when an implementer can execute without inventing architecture or contract decisions, every material requirement or risk has a verification path, the Large/Complex approach choice is confirmed, and active/superseded decisions are explicit.

package/skills/massa-ai/references/spec-driven/discuss.md

@@ -0,0 +1,182 @@
+# Spec-Driven Discuss Gray Areas
+
+Use this reference inside Specify when gray areas or implicit requirements affect behavior, scope, data, security/privacy, compatibility, or acceptance criteria. It captures HOW the user envisions the feature when the spec has ambiguous areas — it is NOT a separate phase; it triggers within Specify when the agent detects gray areas that need user input.
+
+**Goal:** Capture HOW the user envisions the feature when the spec has ambiguous areas. Specifications capture WHAT to build. Design captures the architecture. But neither captures the user's vision for ambiguous areas — layout preferences, interaction patterns, error handling style, content tone. Without this, the agent guesses. With this, the agent builds what the user actually imagined.
+
+The output — `.specs/features/<slug>/context.md` — feeds directly into Design and Tasks:
+
+- **Design reads it** (`references/spec-driven/design.md`) to know what decisions are locked vs. flexible
+- **Tasks reads it** (`references/spec-driven/tasks.md`) to include specific behaviors in task definitions
+
+## Trigger
+
+Automatically when gray areas are detected during spec creation, or explicitly via "discuss feature", "how should this work?", "capture context".
+
+**When to trigger (auto-detect):** The spec contains user-facing behavior that could go multiple ways AND the user hasn't expressed a preference. If the spec is clear and unambiguous, skip this entirely.
+
+**When NOT to trigger:** Genuinely trivial features — a pure read endpoint, a config tweak, features with no [implicit-requirement dimensions](specify.md#implicit-requirement-dimensions) present.
+
+### Trigger Signals
+
+Run Discuss when the request involves any of the following — i.e. a requirement dimension that cannot be honestly marked `N/A because <reason>`:
+
+- persistence/state
+- external calls
+- auth
+- payments
+- concurrency
+- state transitions
+- user-visible workflows
+- permission boundaries
+- migration
+- data loss
+- ambiguous ownership
+- multiple plausible interpretations
+- a requirement dimension not honestly `N/A`
+
+When any dimension is present, trigger discuss. When the dimension is honestly `N/A because <reason>`, mark it so and proceed.
+
+## Process
+
+### 1. Analyze the Feature
+
+Read `.specs/features/<slug>/spec.md` and identify the domain:
+
+| Domain                         | Gray areas to explore                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Something users **SEE**        | Layout, density, interactions, empty states, visual hierarchy |
+| Something users **CALL** (API) | Response format, errors, auth, versioning, rate limiting      |
+| Something users **RUN** (CLI)  | Output format, flags, modes, error handling, verbosity        |
+| Something users **READ**       | Structure, tone, depth, flow, navigation                      |
+| Something being **ORGANIZED**  | Grouping criteria, naming, duplicates, exceptions             |
+| Something with **backend / state / contract** | Failure & partial-failure states, idempotency/retry/dedup, auth boundaries & rate limits, data lifecycle/expiry, concurrency/ordering — see [implicit-requirement dimensions](specify.md#implicit-requirement-dimensions) |
+
+Generate 3-4 **feature-specific** gray areas. Not generic categories, but concrete decisions for THIS feature.
+
+### 2. Present Gray Areas
+
+Present the feature boundary (from `spec.md`) and the gray areas to the user. Let them choose which to discuss. Do NOT include a "skip all" option — the user invoked this phase to discuss.
+
+Any gray area the user **declines** to discuss, or that goes undiscussed, is written to the spec's **Assumptions & Open Questions** section (agent's chosen default + rationale) — never silently dropped. This ensures the spec's closure gate can pass: every gray area is either resolved through discussion or recorded as a signed-off assumption.
+
+### 3. Deep-Dive Each Area
+
+For each selected area:
+
+1. Ask 3-4 concrete questions with specific options (not vague categories)
+2. After the questions, check: "More about [area], or move on?"
+3. If more → ask 3-4 more, check again
+4. After all areas → "Ready to create context?"
+
+**Question design:**
+
+- Options should be concrete ("Card layout" not "Option A")
+- Each answer should inform the next question
+- Include "You decide" as an option when reasonable — captures agent discretion
+
+### 4. Scope Guardrail (CRITICAL)
+
+The feature boundary from `spec.md` is **fixed**. Discussion clarifies HOW to implement, never WHETHER to add new capabilities.
+
+**Allowed:** "How should posts be displayed?" (clarifying ambiguity)
+**Not allowed:** "Should we also add comments?" (new capability)
+
+When user suggests scope creep: "That sounds like a separate feature. I'll note it in Deferred Ideas. Back to [current area]."
+
+### 5. Write `context.md`
+
+Write `.specs/features/<slug>/context.md` (see template below).
+
+## Output
+
+Write `.specs/features/<slug>/context.md` when the discussion is substantial. For small cases, add a compact Discuss section to `spec.md`.
+
+Capture:
+
+- Question ID.
+- Affected requirement IDs.
+- User-confirmed context, decision, or accepted assumption.
+- Concern or risk raised by the gray area.
+- Rejected alternatives.
+- Out-of-scope boundaries.
+- Follow-up needed before Design, Tasks, or Execute.
+
+## Confirmation Gate
+
+Before treating Discuss output as approved context, confirm consequential assumptions with the user or record that the user accepted a default. If the answer changes design, verification, data, security/privacy, or compatibility, update `spec.md` before continuing.
+
+**Artifact-store evidence:** when `context.md` is written, record the active artifact key, version, and checksum after write (see `references/spec-driven/artifact-store.md`).
+
+## Closure
+
+Discuss is done when every gray area is either resolved with the user, recorded as an accepted assumption, or explicitly out of scope. Do not proceed with hidden assumptions.
+
+---
+
+## Template: `.specs/features/<slug>/context.md`
+
+```markdown
+# [Feature] Context
+
+**Gathered:** [date]
+**Spec:** `.specs/features/<slug>/spec.md`
+**Status:** Ready for design
+
+---
+
+## Feature Boundary
+
+[Clear statement of what this feature delivers — the scope anchor from spec.md]
+
+---
+
+## Implementation Decisions
+
+### [Area 1 that was discussed]
+
+- [Specific decision made]
+- [Another decision if applicable]
+
+### [Area 2 that was discussed]
+
+- [Specific decision made]
+
+### [Area 3 that was discussed]
+
+- [Specific decision made]
+
+### Agent's Discretion
+
+[Areas where user explicitly said "you decide" — agent has flexibility here during design/implementation]
+
+### Declined / Undiscussed Gray Areas → Assumptions
+
+[Gray areas the user declined to discuss or that were not covered. Each entry is written to the spec's Assumptions & Open Questions section with the agent's chosen default and rationale — not left silently unresolved.]
+
+---
+
+## Specific References
+
+[Any "I want it like X" moments, product references, specific behaviors, interaction patterns mentioned during discussion]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+---
+
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other features/phases. Captured here so they're not lost, but explicitly out of scope]
+
+[If none: "None — discussion stayed within feature scope"]
+```
+
+---
+
+## Tips
+
+- **Decisions, not vision** — "Card-based layout with subtle shadows" is a decision. "Should feel modern" is not.
+- **Scope is sacred** — Deferred Ideas captures scope creep without losing ideas
+- **User = visionary, Agent = builder** — Ask about how they imagine it, not about technical implementation
+- **Don't ask about:** Technical architecture, performance, implementation details — that's Design's job
+- **Confirm before Design** — User approves `context.md` before moving to design phase