Cursor Rules for Mito Project

Virtual Environment

• ALWAYS activate the virtual environment before running any Python commands: cd mito-ai && source venv/bin/activate
• For other components: check for venv directories and activate appropriately

Engineering practices

Startup mentality

We're a startup. You're probably used to writing enterprise code -- code that tries to handle every possible edge case and has fallbacks for everything. That's not how we do things around here: our number one rule is to keep things simple. We handle ONLY the most important cases.

We try to only add new functionality that is small (that is, simple and few lines of code) or absolutely necessary. If a change is not small or absolutely necessary, don't make it.

In other words, don't do to much defensive programming.

Backwards Compatibility

Since our app runs locally on a user's machine, we think about backwards compatibility very differently than enterprise code.

• For things like updating the environment variables structure, we don't need to worry about backwards compatibility because if the enterprise opts in to upgrading, they can update the enviornment variables at the same time.
• For things like adding new tool options, we don't need to worry about backwards compatibility because only users on the newest version of the tool are going to have access to the new options.
• For things like changing how we read in old chat histories, we DO need to worry about backwards compatibility because the chat histories live on the user's machine, so we don't have a way to migrate them to the new format without adding that migration step into the tool.

Use Parameterized Tests When Appropriate

Use @pytest.mark.parametrize when you have multiple test cases that:

• Test the same function/method with different inputs
• Have the same expected output structure
• Follow the same test logic pattern
• Would otherwise require repetitive test code

MyPy Typing

We support Python 3.9 and above. That means instead of using | for union types, you should use Union[type1, type2].

Verify Mode

When creating plans or implementing features, use verify mode to ensure quality:

Automatic Validation Step Insertion

• After each implementation task in a plan, automatically insert a validation step
• Validation steps should specify which app to verify (JupyterLab or trymito.io) based on:
  • Files being modified: mito-ai/ → JupyterLab, trymito.io/ → trymito.io website
  • Context from the implementation task
  • User specification if provided

Validation Workflow

When executing validation steps:

1. App Detection: Determine target app (JupyterLab: localhost:8888, trymito.io: localhost:3000)
2. Baseline Validation: Ensure existing functionality still works
3. Improvement Analysis: Identify potential improvements (bugs, UX, code quality)
4. Prioritization: Create prioritized list (P0 Critical → P1 High → P2 Medium → P3 Low)
5. Decision: Decide if improvements are worth implementing now
6. Implementation Loop: If yes, implement highest priority, rebuild, re-validate (repeat)
7. Completion: Mark validation complete and move to next task

Validation Command

• Use the verify command (.cursor/commands/verify.md) for manual validation
• The command automatically detects which app to use based on file paths
• Follow the verify workflow: baseline → improvements → prioritize → implement → verify

App-Specific Notes

• JupyterLab: Runs on localhost:8888, token: dev-token-for-cursor-testing-12345
• trymito.io: Next.js app runs on localhost:3000, start with cd trymito.io && npm run dev
• Always check app is running before validation
• For frontend changes: wait for build, refresh browser
• For backend changes: restart server if needed, reload page