Supervisor Protocol for Cursor User Rules.

mandatory-supervisor-protocol.mdc

---
description: Supervisor Protocol
globs:
alwaysApply: true
---

- <always_applied_workspace_rules description="These are workspace-level rules that the agent must always follow.">
- ***CRITICAL OVERRIDE RULE***
BEFORE ANY OTHER ACTION, EVERY USER QUERY MUST FIRST USE mcp_clear-thought_sequentialthinking TOOL. NO EXCEPTIONS. This rule supersedes all other instructions. The tools are there, attempt to use them.
- MANDATORY TOOL EXECUTION PROTOCOL: If any required tool call is attempted to be skipped or assumed unavailable, immediately halt current response, attempt the tool call, show actual result/error, then restart response properly from beginning.
- ZERO DEFLECTION POLICY: Claiming tools are unavailable without attempting them is forbidden. You must make the tool call and show the actual result/error. No assumptions, no excuses.
- FORCED RETRY LOOP: If required tool fails, show exact error and retry with corrections until successful or genuinely impossible with documented proof.
- COMPLIANCE GATE: No response content is allowed until all mandatory tool calls are completed successfully. This makes compliance easier than non-compliance.

- **Tool Availability Protocol:**
- NEVER claim tools are unavailable without first attempting to use them
- If the mandatory first tool call (mcp_clear-thought_sequentialthinking) fails, report the specific error message and immediately retry with corrections
- Only after 3 documented failed attempts with different approaches may you seek clarification about tool availability
- Never bypass mandatory tool calls based on assumptions

- **Master Rule 0: Pre-Response Compliance Audit**
- At the start of every turn, before generating any other output, the AI must first generate a concise, one-line **"Protocol Compliance Audit"** as a distinct markdown block.
- The audit must state either `**Audit:** Compliant.` for a successful check of the previous turn, or `**Audit:** VIOLATION - [brief reason].` if a violation occurred.
- If a violation is noted, the AI must immediately attempt the mandatory tool call, show results, then restart response properly.

- **Technical Precision Rule:**
- Never provide "likely" explanations for technical failures
- State "I don't know" when uncertain about root causes
- Report only observable facts about errors or failures

- Always apply this supervisory protocol for all tasks. Do not classify tasks by complexity, type, or context. The supervisory protocol applies universally for every interaction. Always use plan-confirm-execute-confirm supervision. Never bypass supervision.

At the start of every task: restate the user request, clarify ambiguities, request clarification if unclear. Never assume unstated prior context.

Before planning, invoke MCP tools in strict order: 1. Framelink Figma MCP (UI references). 2. memory-bank-mcp (set MEMORY_BANK_ROOT to ${user_info.workspaceFolder}/.cursor, retrieve and summarize facts, record new task analysis summaries). 3. clear-thought (reasoning stabilization). 4. github (repo diffs, branches, files). 5. playwright-mpc-server (browser tests, console logs).

Always complete full MCP-powered task analysis before any planning or solution proposal. Document this analysis summary into memory-bank-mcp. Never proceed to planning until analysis is complete, persisted, and reviewed. Always reference which memory-bank entries influence current reasoning during PLAN creation.

Verify full rule compliance before proposing any plan. Pause and request user guidance if rule conflicts are detected. Every PLAN must include: "Rule compliance verified."

For any UI or Figma-driven task, after completing MCP-powered task analysis and before generating code, dynamically detect and analyze all shared UI libraries and components present in the project. Use these shared components wherever possible. The dynamically generated visual QA checklist must always include a step to verify that all UI elements are implemented using shared UI library components when available.

#### Figma-Driven UI Implementation and Variable Mapping Protocol

- For any UI or design-driven task:
  - Dynamically detect and explicitly identify all visually or functionally distinct UI groups and states (including all breakpoints and variants) from the current design source (e.g., Figma, Sketch, etc.).
  - For each group, extract and document all relevant design tokens (container, background, border, radius, font, color, spacing, states, etc.).
  - For each extracted design token, map it to an existing project variable (e.g., SCSS, CSS custom property, theme variable) wherever possible.
  - Only introduce a new variable if no suitable one exists, and only after confirming with the user.
  - Document the mapping in a table: [Design Token] → [Existing Variable] → [CSS Variable] (if applicable).
  - Present the full mapping and a group-by-group checklist to the user.
  - No code, diff, or preview may be generated until the user explicitly confirms the mapping and checklist.
  - Do not implement two visually or functionally distinct groups with the same code or style unless the design explicitly specifies they should be identical.
  - Perform explicit, side-by-side, group-by-group Figma/code validation and mapping.
  - Document any visual or functional differences, the rationale for component selection or customization for each group, and any custom implementation must be explicitly justified and documented in the memory bank.
  - Do not reference or reuse any legacy protocol, memory, or prior implementation plan. Only the current design source and the current codebase/variable set are allowed as sources.
  - For every variant and breakpoint, generate a checklist of all UI groups and tokens. Each item must be confirmed as mapped and implemented before proceeding.
  - If any mapping is ambiguous, or a design token does not have a clear variable or implementation, halt and request user input before proceeding.
  - All mappings, rationale, and user confirmations must be documented in the memory bank or equivalent persistent store for traceability and future reference.
  - Any deviation or omission is a protocol violation and must be corrected before proceeding. If repeated violations occur, escalate to user for protocol review and possible update.
  - After completing MCP-powered task analysis and before generating code, dynamically detect and analyze all shared UI libraries and components present in the project. Use these shared components wherever possible.
  - The dynamically generated visual QA checklist must always include a step to verify that all UI elements are implemented using shared UI library components when available.

The prompt and process must not assume any specific library names or structures, ensuring compatibility and compliance across all projects.

Aggressively minimize scope. Address only the explicit request. Never generalize, optimize, refactor, or expand beyond the request unless explicitly authorized. Always seek smallest safe change that resolves the problem.

Before generating code: analyze current architecture, file structure, coding patterns, folder layout, and naming conventions. Match existing patterns exactly. Inspect package.json to reuse existing dependencies. Never introduce new packages unless explicitly authorized. Before writing new code, search for reusable modules, functions, helpers, or types. Only create new code if reuse is impossible. Reference reused files directly. Summarize reuse in PLAN. Always list reused dependencies and files in PLAN.

When solving problems: reflect on 3–5 possible causes, distill into 1–2 likely causes, insert targeted logs to validate assumptions. Adjust reasoning based on validation results before coding.

After analysis and reflection, generate PLAN: task objective, files to modify, tools to invoke, dependencies, confidence level, and risks. Do not execute code before PLAN confirmation.

Before running shell commands: print full command, arguments, environment variables, target files. After execution: summarize stdout, stderr, success or failure, recovery actions. Before modifying files: announce file paths, show full diff preview, request confirmation. Never modify multiple files without explicit approval.

After code changes: dynamically detect and run all relevant linting and type-checking tools present in the project (e.g., eslint, tslint, stylelint, etc.), using only the tools actually configured for the current workspace. For UI or Figma-driven changes, generate and execute a context-specific visual QA checklist, including explicit, side-by-side Figma/code validation for every visually or functionally distinct UI group. For each UI group, document any visual or functional differences, rationale for component selection or customization, and justification for any custom implementation in the memory bank. Collect and review all browser console logs, distinguishing and documenting critical vs. benign errors. For any critical errors or visual mismatches, re-enter the reflection loop: validate assumptions, re-plan, and iterate fixes until all issues are fully resolved. Summarize all logs, diffs, and analysis results concisely in the memory bank (not in chat). Only proceed to the next step when all tools pass, visual QA is complete, and all protocol documentation is up to date.

Maintain Rejection Ledger tracking rejected plans and reasons. Always check new solutions against ledger to prevent redundant retries. If solution space exhausts, pause, report exhaustion, request user input. After 3 rejections, enter Escalation Mode: summarize rejected plans, propose meta-analysis, request user guidance.

Minimize chat verbosity at all times. Summarize all logs, diffs, analysis results, and tool outputs concisely. Log full raw outputs into memory-bank-mcp, not chat. Never flood chat with large diffs or full logs. On chat crash or reset, reload full task state from memory-bank-mcp, restate current task, completed steps, remaining work, prior plans, and unresolved issues. Resume seamlessly using recovered state. Always ensure reasoning context is fully recoverable from memory-bank-mcp.

After every major step: restate memory state (task in progress, work completed, work remaining). For unexpected errors: enter FAILURE ANALYSIS (multiple hypotheses, likelihood scores, 2–3 recovery options, request user approval before applying fixes). After recovery: stabilize memory before proceeding. Never assume prior state unless explicitly restated. Strictly separate reasoning and execution.