@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/references/rfc/document-contract.md

@@ -0,0 +1,85 @@
+# RFC Document Contract
+
+Load this reference when drafting or revising an RFC. Preserve the full decision structure while tailoring detail to the RFC type and impact.
+
+## Section Contract
+
+Every RFC contains **7 mandatory sections** and should contain the **4 recommended sections** when relevant.
+
+### Mandatory Sections
+
+1. **Header And Metadata**
+   - Title, `HIGH / MEDIUM / LOW` impact and justification, `NOT STARTED / IN PROGRESS / COMPLETE` status, Created, Last Updated, Due Date, and related resources.
+   - Full RACI: Driver, Approver or Approvers, Contributors, and Informed parties. Keep unknown required values as `TBD` rather than deleting fields.
+2. **Background**
+   - Current state, specific problem or opportunity, why now, evidence, and cost or consequence of inaction.
+3. **Assumptions**
+   - Table with assumption, owner, `High / Medium / Low` confidence, and invalidation trigger. Include at least one explicit assumption.
+4. **Decision Criteria**
+   - Define criteria before options. Separate non-negotiable must-haves from scored criteria.
+   - Use numeric `Weight (%)` values that sum to 100 across scored criteria. Explain scoring scale and disqualification rules.
+5. **Options Considered**
+   - At least two credible options. Explicitly evaluate the status quo and include it as "Do Nothing" unless it is impossible; explain any omission.
+   - For every option include description, how it works, honest pros and cons, dependencies, reversibility, `Estimated Cost`, effort, financial cost when applicable, and `HIGH / MEDIUM / LOW` risk.
+   - Generated estimates are required when exact estimates are unavailable. Label them as rough estimates, state assumptions, and use ranges where appropriate.
+6. **Action Items**
+   - Concrete post-decision actions with owner, due date, and status. Include review, communication, proof-of-concept, downstream TDD, or policy rollout actions when applicable.
+7. **Outcome**
+   - Keep a visible placeholder while the decision is open. After explicit human decision, record chosen/rejected/deferred outcome, date, decision-makers, rationale, key factors, conditions, and follow-up.
+
+### Recommended Sections
+
+8. **Relevant Data**: quantitative evidence, qualitative feedback, prior attempts, external research, and links.
+9. **Pros And Cons**: may live within each option, but each option must receive an honest assessment.
+10. **Estimated Cost**: summarize effort, money, operational load, migration cost, and opportunity cost across options.
+11. **Resources**: related Jira/Linear issues, Confluence pages, RFCs, ADRs, TDDs, dashboards, research, standards, and vendor documentation.
+
+## Option Comparison
+
+After describing options, include a comparison matrix evaluating each option against the predeclared criteria. Use the numeric weights consistently and show enough scoring rationale that stakeholders can challenge the result. The recommendation must identify:
+
+- which must-haves each option satisfies or fails
+- weighted result or qualitative interpretation of the weighted criteria
+- decisive trade-offs and sacrifices
+- why the recommendation wins despite its disadvantages
+- what evidence would change the recommendation
+
+Do not manipulate criteria or weights after seeing which option wins without documenting the change and rerunning every option comparison.
+
+## Conditional Concerns
+
+Add explicit subsections when the RFC type or impact triggers them:
+
+| Trigger | Required concerns |
+|---|---|
+| Technical/architecture change | system impact, dependencies, compatibility, migration, security, observability, rollback or forward recovery |
+| Process/workflow change | affected roles, training, adoption, pilot, enforcement, exceptions, feedback loop, process rollback |
+| Product/feature change | user segments, value hypothesis, metrics, experiment or rollout, go/no-go criteria, support impact |
+| Vendor/tool selection | evaluation method, pricing assumptions, contract terms, lock-in, data portability, support, exit plan |
+| Policy/compliance change | authority, applicable obligations, enforcement, exceptions, audit evidence, review cadence |
+| HIGH impact | broader stakeholder review, explicit risks, stronger evidence, implementation dependencies, decision deadline |
+
+## Required Metadata Shape
+
+Use project conventions when present; otherwise start with this Markdown table:
+
+```markdown
+# RFC: [Clear, Action-Oriented Title]
+
+| Field | Value |
+|---|---|
+| **Impact** | HIGH / MEDIUM / LOW - [justification] |
+| **Status** | NOT STARTED / IN PROGRESS / COMPLETE |
+| **Driver** | @Name |
+| **Approver(s)** | @Name1, @Name2 |
+| **Contributors** | @Name3, @Name4 |
+| **Informed** | @Team, @Stakeholder |
+| **Due Date** | YYYY-MM-DD or TBD |
+| **Resources** | Jira/Linear, Confluence, related RFC/ADR/TDD |
+| **Created** | YYYY-MM-DD |
+| **Last Updated** | YYYY-MM-DD |
+```
+
+## Detail Boundaries
+
+An RFC decides whether and which direction to pursue. Include enough mechanism to compare feasibility, risk, compatibility, cost, and reversibility, but route settled implementation contracts and task sequencing to a TDD. Keep option descriptions concise and comparable rather than turning one preferred option into a complete design while leaving alternatives shallow.

package/skills/massa-ai/references/rfc/quality-and-lifecycle.md

@@ -0,0 +1,101 @@
+# RFC Quality And Lifecycle
+
+Load this reference before challenging, finalizing, saving, updating, or closing an RFC.
+
+## Quality Gate
+
+Verify every item before finalization:
+
+- Title is clear, action-oriented, and specific.
+- Impact is `HIGH`, `MEDIUM`, or `LOW` with justification.
+- Background states current state, problem or opportunity, why now, evidence, and cost of inaction.
+- Full RACI identifies Driver, Approver or Approvers, Contributors, and Informed parties, using `TBD` only when the user cannot resolve a role.
+- Assumptions include owner, confidence, and invalidation trigger.
+- Decision criteria were defined before options, include must-haves, and use numeric weights summing to 100.
+- At least two credible options are evaluated, with explicit status quo consideration.
+- Every option has honest pros, cons, dependencies, reversibility, generated or supplied estimates, financial cost where applicable, and risk.
+- Comparison uses the declared criteria rather than isolated sales arguments.
+- Recommendation traces directly to criteria, evidence, and trade-offs.
+- Action items identify concrete post-decision work.
+- Outcome remains a placeholder until an explicit human decision exists.
+- Technical, process, product, vendor, or policy concerns are included according to the classified RFC type.
+
+If a blocking item fails, use `AskQuestion`, research the missing evidence, or keep the required field visibly unresolved. Do not silently weaken the document contract.
+
+## Anti-Patterns
+
+### Predetermined Conclusion Disguised As RFC
+
+Reject a proposal where the preferred option receives detailed benefits while alternatives are caricatures. Steelman every credible option, include disconfirming evidence, and state what would change the recommendation.
+
+### Criteria Chosen After Options
+
+Define and weight criteria first. If stakeholder feedback changes criteria or weights, record the revision and reevaluate every option.
+
+### Status Quo Treated As Free
+
+Compare the cost, risk, and opportunity loss of inaction. "Do Nothing" may have low immediate effort and high long-term cost.
+
+### Hidden Assumptions Or False Precision
+
+Expose assumptions with invalidation triggers. Generated estimates must be labeled, use ranges where useful, and state the capacity, pricing, volume, or complexity assumptions behind them.
+
+### Implementation Document Masquerading As RFC
+
+Keep focus on whether and which direction should be selected. Route detailed implementation architecture and delivery planning to TDD after decision.
+
+## Plan Challenge Gate
+
+Run the full configured Plan Challenge Gate after the draft exists. Challenge at least:
+
+- strongest counterargument to the recommendation
+- evidence quality and interested-party or vendor bias
+- status quo, sunk cost, authority, confirmation, and planning biases
+- criteria or weights that favor a predetermined answer
+- weak generated estimates or missing cost categories
+- assumption most likely to invalidate the recommendation
+- reversibility, migration, adoption, security, compliance, and operational failure where relevant
+
+Revise valid critical or high findings without deleting required RFC sections or stakeholder fields.
+
+## Lifecycle
+
+Use the preserved states honestly:
+
+- `NOT STARTED`: initial proposal shell or discovery has not produced a reviewable draft.
+- `IN PROGRESS`: reviewable proposal exists, feedback is open, or required decision input remains unresolved.
+- `COMPLETE`: an explicit human decision is recorded in Outcome as accepted, rejected, or deferred.
+
+When updating an existing RFC:
+
+1. Read the current RFC and linked decisions.
+2. Identify new evidence, feedback, assumptions, criteria, weights, options, or cost changes.
+3. Preserve still-valid context and rejected-option rationale.
+4. Update Last Updated and status honestly.
+5. Record material changes so reviewers can identify what moved.
+6. Never overwrite an existing RFC unless the user explicitly requested an update or confirmed replacement.
+
+## Completion And Suggested Next Steps
+
+After generating or updating the RFC, report title, impact, status, included sections, options compared, unresolved fields, and artifact path. Preserve these suggestions when relevant:
+
+- Share with Contributors for feedback and Approvers for decision.
+- Set or confirm a decision deadline and review meeting.
+- Link or create related Jira or Linear work items.
+- Create a follow-up TDD after the direction is approved.
+- Publish or update the proposal in Confluence when the user wants shared publication.
+- Update status to `IN PROGRESS` when review begins and `COMPLETE` only after the decision is recorded.
+
+Do not claim a Jira/Linear link, Confluence publication, meeting, approval, or decision occurred unless the corresponding action or authoritative evidence exists.
+
+## Deterministic Checks
+
+Before completion:
+
+1. Check Markdown structure, metadata, and local links.
+2. Confirm all 7 mandatory sections and relevant recommended sections exist.
+3. Confirm numeric criterion weights sum to 100 and each option appears in the comparison.
+4. Confirm the Outcome placeholder remains unresolved for open proposals.
+5. Run repository-specific documentation checks when available.
+6. Persist only the memory tier appropriate to current lifecycle state.
+7. Complete the shared Evidence Gate.

package/skills/massa-ai/references/root-cause-scripts.md

@@ -0,0 +1,97 @@
+# Root-Cause Proof Scripts
+
+Use this reference the moment an implementation or fix stops converging. It is a
+circuit breaker, not a diagnosis method: it fires mid-implementation in any
+workflow — `feature`, `debug`, `refactor`, `spec-driven`, any `*-fix` — including
+the ones that never opened a reproduction loop.
+
+`references/debug-diagnosis-loop.md` is where a `debug` investigation *starts*.
+This file is where any implementation *stops guessing*.
+
+## Principle
+
+An agent that has failed twice on the same symptom does not have a code-reading
+problem. It has a data problem. Reading the same source a third time produces a
+third theory with the same evidence base as the first two. The only way out is
+to make the program tell you what it is actually doing.
+
+## Trigger
+
+The circuit breaks when **any** of these holds:
+
+1. **Two consecutive failed fix attempts** against the same symptom. Attempt
+   three does not begin until a probe has run.
+2. A hypothesis already ruled out is being re-tested without new evidence.
+3. Three or more edits have been made to the same file without the symptom
+   changing.
+4. The explanation for the failure has changed twice while the observed failure
+   has not changed at all.
+
+Two is the threshold, not three. The second failure is where the cost of a probe
+first drops below the cost of another guess.
+
+## Forbidden Next Actions
+
+Once the circuit breaks, these do **not** count as progress and must not be the
+next action:
+
+- Reading more source files, or re-reading a file already read this session.
+- Reasoning about what the code "should" do.
+- Another speculative edit "to see if it helps".
+- Adding a defensive guard, try/catch, or null check that hides the symptom.
+- Asking the user what is wrong before producing any observation.
+- Rerunning the identical failing command with no added instrumentation.
+
+## Required Next Action — Build The Probe
+
+Write and run an executable artifact that emits **real runtime data** from the
+failing path. Acceptable forms, cheapest first:
+
+| Form | Use when |
+| --- | --- |
+| A failing test at the suspected seam | The seam is reachable from the existing test harness |
+| A standalone script (`bun`/`node`/`python`/shell) | The path needs setup the test harness does not provide |
+| Instrumented run with structured logging at the divergence point | The failure only reproduces in the full system |
+| A one-shot query against the real data store | The hypothesis is about persisted state, not control flow |
+| Recorded request/response or device trace | The boundary is a network or platform call |
+
+### Probe contract
+
+A probe is valid only if all of these hold:
+
+1. **Deterministic** — same input, same output, runnable twice with the same result.
+2. **Observational** — prints the *observed* value beside the *expected* value.
+   "It printed something" is not an observation; the comparison is.
+3. **Signalling** — exits non-zero (or fails) while the bug is present.
+4. **Narrow** — probes exactly one hypothesis. A probe that answers three
+   questions answers none of them cleanly.
+5. **Non-destructive** — never mutates production data or shared state. Scratch
+   paths, temp databases, and fixtures only.
+6. **Disposable or promoted** — either delete it when the bug is closed, or
+   promote it into a real regression test under
+   `references/code-annotation.md`. Do not leave orphan scripts in the tree.
+
+Record the probe's output as evidence. The output — not the reasoning about it —
+is what closes the hypothesis.
+
+## After The Probe
+
+| Probe result | Next action |
+| --- | --- |
+| Confirms the hypothesis | Fix the divergence point the probe located, then rerun the probe to prove the fix |
+| Refutes the hypothesis | Record it as ruled out with the observed data, and probe the next-ranked hypothesis |
+| Inconclusive | Narrow the probe. An inconclusive probe was too broad, not the wrong idea |
+| Cannot be built | Stop. Report `Blocked`, name the specific obstacle (no test seam, no access, no reproduction), and ask for direction. Do not resume guessing |
+
+## Escalation
+
+If two probes both come back inconclusive, the problem is scoped wrong, not
+understood wrong. Stop, report what the probes did observe, and re-scope with the
+user before writing a third.
+
+## Delegation Note
+
+A subagent dispatched to implement or fix inherits this contract. Its capability
+packet states the trigger and the probe requirement, and its report must include
+either "no circling" or the probe output that broke the loop. A subagent that
+returns a third theory with no runtime data has not completed its task.

package/skills/massa-ai/references/spec-driven/artifact-store.md

@@ -0,0 +1,98 @@
+# Spec-Driven Artifact Store
+
+Use this reference before any spec-driven workflow reads or writes feature registry, progress, handoff, phase artifacts, validation reports, or lessons. `.specs/` files are the canonical state layer for spec-driven logical artifacts.
+
+## Source Of Truth
+
+- Canonical state lives in `.specs/` files tracked in the repository, not massa-ai records, semantic memories, or root aliases.
+- Current repository source remains authoritative for implementation/code evidence.
+- `search`, `recall`, and durable memories may discover context, decisions, or reusable patterns, but must never reconstruct canonical artifact state.
+- If `.specs/` is unavailable or not writable, block spec-driven state mutation and record the blocker.
+
+## STATE Precedence Chain
+
+Artifact reads resolve conflicts in this strict order (first match wins): fresh user instruction > approved `.specs/` artifact > STATE/HANDOFF > massa-ai memory. massa-ai memory and external summaries are discovery, not authority. Canonical ownership and full section rules live in `references/spec-driven/memory.md`; this store mirrors the chain so reads and writes stay consistent.
+
+## Logical Paths
+
+Use these logical paths:
+
+- `.specs/project/FEATURES.json` — feature registry, `active_feature`, status, dependencies
+- `.specs/project/STATE.md` — current objective, progress, blockers, decisions, next step
+- `.specs/HANDOFF.md` — session handoff state
+- `.specs/features/<slug>/spec.md` — feature specification
+- `.specs/features/<slug>/context.md` — feature context
+- `.specs/features/<slug>/design.md` — feature design
+- `.specs/features/<slug>/tasks.md` — feature tasks
+- `.specs/features/<slug>/validation.md` — feature validation report
+- `.specs/quick/NNN-slug/TASK.md` — quick-mode task (one-line intent + acceptance)
+- `.specs/quick/NNN-slug/SUMMARY.md` — quick-mode result (files changed + gate evidence)
+- `.specs/lessons.json` — machine-owned lesson state (managed by `lessons.py`)
+- `.specs/LESSONS.md` — rendered lesson playbook (read-only, generated by `lessons.py`)
+
+## Quick Artifacts
+
+Quick-mode tasks (Quick mode guardrails in `workflows/spec-driven.md`) live under `.specs/quick/NNN-slug/`. `NNN` is zero-padded and sequential per project; `slug` is the short kebab-case intent. Each quick task has exactly two files:
+
+**`.specs/quick/NNN-slug/TASK.md`:**
+
+```markdown
+# Quick NNN: <one-line intent>
+
+## Acceptance
+- <single testable criterion — the gate the Execute step must pass>
+```
+
+**`.specs/quick/NNN-slug/SUMMARY.md`:**
+
+```markdown
+# Quick NNN: <one-line intent>
+
+## Result
+- Status: Complete | Blocked | Partial
+- Files changed: <list or "none">
+- Gate: <command + pass/fail evidence>
+- SPEC_DEVIATION: <none | what diverged and why>
+```
+
+Quick tasks are also listed in the STATE.md Quick Tasks table (see `references/spec-driven/memory.md`). When 5+ quick tasks accumulate in one area, promote to a feature: move the work under `.specs/features/<slug>/` and record the promotion in STATE. Quick artifacts are canonical `.specs/` state — same precedence chain, same section-scoped write rules; they are not a second store.
+
+## Reading Artifacts
+
+Load only what you need. Prefer metadata-only inspection before loading full content.
+
+- **Feature registry status:** `cat .specs/project/FEATURES.json | python3 -c "import json,sys; d=json.load(sys.stdin); print('active:', d.get('active_feature')); [print(f['id'], f['status']) for f in d.get('features',[])]"`
+- **Full feature registry:** `cat .specs/project/FEATURES.json`
+- **Project state:** `cat .specs/project/STATE.md`
+- **Handoff:** `cat .specs/HANDOFF.md`
+- **Feature spec:** `cat .specs/features/<slug>/spec.md`
+- **Confirmed lessons:** `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]`
+
+## Writing Artifacts
+
+Write artifacts directly to `.specs/` files. Use a here-doc or `printf` for Markdown, or `python3 -c` for JSON mutations.
+
+- **Update state:** `printf '...' > .specs/project/STATE.md`
+- **Update handoff:** `printf '...' > .specs/HANDOFF.md`
+- **Write feature artifact:** `printf '...' > .specs/features/<slug>/design.md`
+- **Update feature registry:** use `python3 -c` to read-modify-write `FEATURES.json`
+
+Feature activate/complete flows update `.specs/project/FEATURES.json`, `.specs/project/STATE.md`, and `.specs/HANDOFF.md` through file writes.
+
+## Versioning
+
+- Feature artifacts under `.specs/features/<slug>/` are versioned by design (one file per slug).
+- `.specs/project/FEATURES.json` and `.specs/project/STATE.md` are append-only versioned by their git history.
+- `lessons.json` versioning is managed automatically by `lessons.py`.
+- When content must be superseded (e.g., a decision), update the existing file and rely on git history for the prior version.
+
+## Debug Exports
+
+Exports under `.specs-exports/` are optional, untracked review aids. Use `cp -r .specs/ .specs-exports/` for human inspection. Exports are never runtime fallback, never canonical input, and never completion evidence.
+
+## Failure Handling
+
+- `.specs/` directory missing or not writable: block spec-driven state mutation; do not fall back to memory or chat.
+- Required artifact missing: create it on first write or block unless it is an approved initial creation.
+- `lessons.py` unavailable: skip lessons loading/recording, record skipped reason in validation report.
+.specs/ files

package/skills/massa-ai/references/spec-driven/code-analysis.md

@@ -0,0 +1,119 @@
+# Spec-Driven Code Analysis
+
+Use this reference when Specify, Design, Tasks, Execute, or Validate needs source inspection or structural code search.
+
+<!-- validator anchors: current repository source and approved .specs/ artifacts override stale memory -->
+
+## Tool Priority
+
+Use graceful degradation, starting from massa-ai indexed tooling and falling back to structural, then text, search:
+
+1. `list_projects` (or equivalent index metadata) before indexed reads, to verify project ID, path, status, and freshness.
+2. `search` (or indexed symbol reads) when available and fresh for the current repository path and worktree state. Prefer `search_definitions`, `get_references`, or `optimized_context` for symbol- and reference-shaped queries.
+3. `sg` / ast-grep for structural pattern-based search when installed.
+4. `rg` (ripgrep) for fast context-aware text and file search.
+5. `grep` or direct file reads as the final, always-available fallback.
+
+## Freshness And Source Precedence
+
+- Current repository source and approved `.specs/` artifacts override stale memory, old search results, external summaries, debug exports, and generated plans.
+- `project_map`, `search`, and `optimized_context` are discovery evidence, not proof, until confirmed against source files read in this session or returned with current freshness evidence.
+- If indexed results conflict with current files, or the index is stale, incomplete, missing the target path, or older than relevant local changes, trust current files and record the stale-index observation when it affects decisions.
+- Use massa-ai durable memory for prior decisions, rejected approaches, reusable patterns, and verification recipes; do not use it as codebase evidence without current-source confirmation.
+
+## Rules
+
+- Inspect current codebase and project docs before external docs.
+- Prefer structural or symbol search for definitions, call sites, schemas, routes, test files, and public contract fields.
+- Limit search scope to affected modules, source sets, tests, fixtures, schemas, and docs that define behavior.
+- Record source evidence as files, symbols, line numbers, and commands in `design.md`, `tasks.md`, or `validation.md`.
+- If a tool is unavailable, use the next fallback and state the skipped tool only when it affects confidence.
+
+## Detection
+
+Check tool availability before use. Run the massa-ai tier first; only probe `sg` / `rg` when you are about to rely on them:
+
+```bash
+# Check for ast-grep
+if command -v sg >/dev/null 2>&1; then
+  # Use ast-grep for structural search
+elif command -v rg >/dev/null 2>&1; then
+  # Fall back to ripgrep
+else
+  # Use standard grep as final fallback
+fi
+```
+
+## Usage Examples
+
+**Finding function definitions:**
+
+```bash
+# ast-grep (best - structural)
+sg -p 'function $NAME($$$) { $$$ }'
+
+# ripgrep (fallback - fast text)
+rg '^function\s+\w+\(' --type-add 'source:*.[extension]' -t source
+
+# grep (last resort - basic)
+grep -r '^function ' --include="*.[extension]"
+```
+
+**Finding imports/requires:**
+
+```bash
+# ast-grep
+sg -p 'import { $$$ } from "$MODULE"'
+
+# ripgrep
+rg '^import .* from' --type-add 'source:*.[extension]' -t source
+
+# grep
+grep -r '^import ' --include="*.[extension]"
+```
+
+**Finding class/component definitions:**
+
+```bash
+# ast-grep
+sg -p 'class $NAME { $$$ }'
+
+# ripgrep
+rg '^(class|export class)\s+\w+' --type-add 'source:*.[extension]' -t source
+
+# grep
+grep -r '^class ' --include="*.[extension]"
+```
+
+## Search Scope
+
+**Best practices:**
+
+- Limit to source file extensions relevant to project
+- Exclude directories: `node_modules`, `vendor`, `dist`, `build`, `.git`
+- Focus on source directories: `src`, `lib`, `app`
+- Use file type filters when available
+
+**Performance tips:**
+
+- Use specific patterns over broad searches
+- Limit directory depth with `--max-depth` (ripgrep/grep)
+- Cache results for repeated queries
+
+## Fallback Notice
+
+If ast-grep is unavailable, display once per session:
+
+```
+⚠️ ast-grep not detected. Install for more precise structural code analysis.
+   https://ast-grep.github.io/guide/quick-start.html
+```
+
+## When To Use
+
+- Finding usage patterns across the codebase
+- Identifying code structure and organization
+- Locating function/class/component definitions
+- Analyzing import/dependency patterns
+- Refactoring impact analysis
+- Code navigation in unfamiliar codebases

package/skills/massa-ai/references/spec-driven/coding-principles.md

@@ -0,0 +1,80 @@
+# Spec-Driven Coding Principles
+
+Use this reference before writing or changing implementation, tests, fixtures, validation assets, scripts, or docs during Execute.
+
+Behavioral bias, not checklist. Read before every implementation.
+
+---
+
+## Pre-Implementation Statement
+
+Before edits, state:
+
+- Assumptions: accepted assumptions and remaining uncertainty.
+- Files to touch: only files required for the current task or validation.
+- Success criteria: deterministic command, artifact check, or validation report that proves the task.
+
+Artifact-store evidence: active artifact key, version, and checksum after write (specify, tasks, design phases).
+
+---
+
+## Before Coding
+
+- State assumptions explicitly. If uncertain, ask.
+- Multiple interpretations exist? Present all—don't pick silently.
+- Simpler approach exists? Say so. Push back when warranted.
+- Something unclear? Stop. Name what's confusing. Ask.
+- User's approach seems wrong? Disagree honestly. Don't be sycophantic.
+
+---
+
+## During Implementation
+
+### Simplicity
+
+- No features beyond what was asked
+- No abstractions for single-use code
+- No "flexibility" or "configurability" not requested
+- No error handling for impossible scenarios
+- 200 lines that could be 50? Rewrite it.
+
+### Surgical Changes
+
+- Don't "improve" adjacent code, comments, or formatting
+- Don't refactor things that aren't broken
+- Match existing style, even if you'd do differently
+- Unrelated dead code noticed? Mention it—don't delete it
+- Remove ONLY imports/variables/functions YOUR changes orphaned
+- Don't remove pre-existing dead code unless asked
+
+### Test Integrity
+
+- NEVER weaken an existing test assertion to make it pass
+- NEVER delete a test to reduce failure count
+- NEVER use the test framework's skip/disable/pending mechanism to bypass a failing test
+- NEVER modify a task's tests afterward to make the implementation pass
+- If a test is genuinely wrong, STOP and confirm with the user before changing it
+- Tests are the spec — implementation conforms to tests, not the other way around
+
+### Goal-Driven
+
+- Transform vague tasks into verifiable goals
+- Multi-step work? State brief plan with verify checkpoints
+- Every changed line must trace directly to user's request
+
+### Rules
+
+- Implement the simplest complete change that satisfies the approved requirement.
+- Touch only listed files unless a new requirement or design decision forces a return to Specify or Design.
+- Match existing style and local helpers.
+- Do not add speculative flexibility, broad refactors, or unrelated cleanup.
+- Do not weaken tests, specs, fixtures, snapshots, schemas, or checks to make work pass.
+- Derive tests from acceptance criteria and spec-defined outcomes, not from current implementation.
+- Re-run the task gate after any code or validation-asset change.
+
+---
+
+## After Each Change
+
+Ask: "Would senior engineer call this overcomplicated?"
+If yes → simplify before proceeding.

package/skills/massa-ai/references/spec-driven/context-limits.md

@@ -0,0 +1,64 @@
+# Spec-Driven Context Limits
+
+Use this reference when planning context loading for a spec-driven feature or when `.specs/features/<slug>/` artifacts grow large enough to reduce implementation quality.
+
+## Targets
+
+- Loaded working context target: under 40k tokens (20% of the window).
+- Warning range: 40k to 60k tokens.
+- Critical range: above 60k tokens.
+- Reserve: 160k+ tokens for work, reasoning, and outputs.
+
+## Base Load Set
+
+The deterministic starting context for a spec-driven task is a ~15k-token base set, loaded once before deeper artifacts:
+
+- The selected workflow (`workflows/spec-driven.md`) — routing and phase contracts.
+- `references/spec-driven/memory.md` and `references/spec-driven/artifact-store.md` — state layer + precedence.
+- `.specs/project/STATE.md` and `.specs/HANDOFF.md` — current position and decisions.
+- The active feature's `spec.md` (requirements + ACs) — the source of truth for the work.
+
+Load additional phase references (`specify.md`, `design.md`, `tasks.md`, `execute.md`, `validate.md`) only when the active phase needs them, and unload/summarize when the phase closes. The base set keeps the starting footprint predictable; phase references are additive and bounded.
+
+## File Size Limits
+
+| File          | Max Tokens | ~Words | Warning At |
+| ------------- | ---------- | ------ | ---------- |
+| `spec.md`     | 5,000      | 3,000  | 4,000      |
+| `design.md`   | 8,000      | 4,800  | 6,400      |
+| `tasks.md`    | 10,000     | 6,000  | 8,000      |
+
+## Artifact Budgets
+
+| Artifact   | Target              |
+| ---------- | ------------------- |
+| `spec.md`  | 5k tokens or less   |
+| `design.md`| 8k tokens or less   |
+| `tasks.md` | 10k tokens or less  |
+
+## Context Zones
+
+- 🟢 **Healthy** (<40k total): Silent.
+- 🟡 **Moderate** (40-60k): Discrete footer note.
+- 🔴 **Critical** (>60k): Active warning, suggest optimization.
+
+## Monitoring
+
+Display context status in footer when loaded context exceeds 40k:
+
+```
+📊 Context: 52k tokens (moderate)
+  - tasks.md: 11k (ok)
+  - design.md: 6k (ok)
+  - Total: 52k / 200k (26%)
+```
+
+## Rules
+
+- Load one active feature's `.specs/features/<slug>/` artifacts at a time.
+- Never load multiple feature specs or architecture docs simultaneously — cross-feature loading invites stale-requirement bleed and blows the context budget. If a second feature's context is needed, summarize the first, persist position to `.specs/HANDOFF.md`, then load the next feature alone.
+- Prefer summaries, targeted sections, and file ranges over full broad dumps.
+- Use `references/context-firewall.md` before raw logs, raw transcripts, raw search output, generated reports, screenshots, large diffs, subagent output, or external research.
+- Report context pressure as a compact status or `.specs/HANDOFF.md` field when loaded context approaches warning or critical range; do not paste raw context dumps to explain pressure.
+- If context exceeds the warning range, compact artifact summaries before adding more source.
+- If context exceeds the critical range, stop and produce a restartable handoff (`.specs/HANDOFF.md`) before continuing.