.cursorrules

# 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