cursor_operating_model

Instruction file imported from YahyaElghobashy/cursor-template (.cursor/rules/cursor_operating_model.mdc). Copyright stays with the author.

Cursor Operating Model

This file defines the standard development lifecycle, execution behavior, and system protocols that every Cursor agent must follow when working within this project structure.

🧠 Agent Behavioral Rules

• Always read this file before executing or planning tasks.
• Always read all .mdc files relevant to the current task or feature.
• Always complete these stages in sequence before starting another task:
  1. Read relevant .mdc files
  2. Plan the solution
  3. Suggest or generate required tests
  4. Execute implementation
  5. Run tests with MCP
  6. Summarize changes
  7. Update .mdc files (first), then ask to update .md
  8. Get user approval to continue
• Always use .mdc files for implementation context, not .md files.
• Always suggest tests even if not asked explicitly.
• Never scaffold new components without checking structure in tech_stack_document.mdc, frontend_guidelines_document.mdc, or backend_structure_document.mdc.
• If tests fail or visual/UI bugs are detected, use Browser MCP to:
  • Take screenshots
  • Capture console logs
  • Retry or suggest a fix

🧩 Required Files & Roles

🔁 Task Execution Protocol

Every task must follow this flow:

1. Plan
   Read .mdc context → suggest full approach.
   Prompt:
   “Explain the full approach you’d take to implement this. Just tell, don’t code.”

2. Testify
   If tests don’t exist → ask to write them first
   If tests exist → run them before and after execution

3. Execute
   Write or update code; follow existing folder structures & stack definitions

4. Validate

   • Run all tests
   • Use Browser MCP for front-end visuals if UI changes were made
   • Log test output or errors

5. Document

   • Update .mdc files first (include purpose, location, logic notes)
   • Ask if user wants to sync .md counterparts (human-readable)

6. Control

   • Do not begin another task unless this one is fully tested, validated, and documented

🛠 Cursor Setup Instructions

• Add Browser MCP and Supabase MCP in Settings.
• Ensure .cursor/rules/ is indexed — this enables rule awareness.
• Use Gemini for reading and Sonnet/O1 for executing.
• Hard-cap retries to 3. If still failing → stop and ask user for manual inspection.
• When visual diffs are detected → auto-trigger Browser MCP for screenshots & logs.

🔄 Enhancement Tasks

• Treat every enhancement request like a scoped feature.
• Before execution, update:
  • implementation_plan.mdc to add enhancement entry
  • Any .mdc file that the enhancement touches
• After execution:
  • Run tests
  • Regenerate .mdc and optionally .md
  • Update CHANGELOG.md with summary

✅ Commit & Release Protocol

• All commits must include:

  • Updated .mdc file
  • Optional updated .md file
  • Tests if applicable
  • CHANGELOG.md entry

• A release is complete only when:

  • Code, tests, .mdc, and .md are in sync
  • CHANGELOG.md reflects all changes