# Cursor Agent Rules
## Environment Setup
IMPORTANT: Always activate the cursor_tools conda environment before using or developing tools:
```bash
conda activate cursor_tools
```
If you encounter import errors, this is likely because the environment is not activated.
IMPORTANT: Never modify the base environment under any circumstances. If you find yourself in the base environment, always activate the correct environment instead of installing packages in base.
IMPORTANT: Never install packages directly using pip or conda. Instead:
- Add Python package dependencies to pyproject.toml
- Add development/data science dependencies to environment.yml
- Then reinstall the project using `pip install -e .`
The environment.yml file is mostly for developer and data science dependencies. The pyproject.toml file is for the package dependencies.
Prefer adding the dependencies to the pyproject.toml file.
The package is installed in editable mode (`pip install -e .`), so any changes to the code will be immediately reflected without reinstallation.
## Output and Logging
IMPORTANT: Tools must follow these output and logging guidelines:
- Never use print() statements. Use click.echo() for command output
- Use the logging module for all debug/info/warning/error messages
- Tools should only output their results on stdout so they can be composed in command pipelines
- Verbose logging must be explicitly enabled before tools can emit logging messages
- Keep stdout clean and predictable for command composition
- Use stderr for warnings and errors
- Never log sensitive data (API keys, tokens) in plaintext
- Use structured logging format for better debugging
- Include timestamp, logger name, and log level in log format
## Cross-Platform Compatibility
IMPORTANT: Tools must work across different platforms:
- Handle SSL/certificate verification properly (especially on Windows)
- Use certifi for SSL certificate verification
- Create proper SSL contexts when needed
- Handle filesystem paths correctly
- Test on all target platforms
- Document platform-specific requirements
## Error Handling
IMPORTANT: Implement proper error handling:
- Create custom exception hierarchies for better error handling
- Handle errors from most specific to most generic
- Provide clear error messages to users
- Log detailed error information for debugging
- Always set timeouts for external operations
- Implement proper input validation
- Handle API errors gracefully
- Use appropriate exit codes
## Agent Workspace
Agents have access to a local `scratchpad/` directory for maintaining state and notes about:
- Current goals and tasks
- Observations and learnings
- Progress tracking
- Any other persistent information needed across sessions
This directory is ignored by git (via .gitignore) since it contains agent-specific working data.
## Agent Guidance
IMPORTANT: Before taking ANY action, the agent MUST first assume a role by reading and internalizing the corresponding guidance file from the `agent_prompts/` directory. For example:
- For backend development tasks: Read and assume the role from `senior_backend_developer.md`
- For architecture decisions: Read and assume the role from `principal_architect.md`
- For testing/QA tasks: Read and assume the role from `senior_qa_manager.md`
The agent should explicitly state which role it is assuming before proceeding with any actions. The guidance in these files represents senior-level expertise that should inform all decisions and ensure high quality output.
These role-specific prompts provide expert-level guidance for maintaining high standards in:
- Architecture decisions
- Code quality and patterns
- Testing strategies
- Security considerations
- Performance optimization
- System design
Never proceed with modifications or tool usage without first assuming an appropriate role from the available guidance files.
## Tool Development Instructions
1. All new tools should be created in the `cursor_tools` directory
2. Each tool should be a separate Python module
3. Tools must implement the base Tool interface
4. Tools should be self-contained and focused on a single responsibility
5. All tools must include proper documentation and type hints
6. Use httpx instead of requests for all HTTP operations - it's faster, more modern, and has better async support
7. Use click for CLI interfaces - all tools should be accessible via `cursor-tools [tool-name] [args] [flags]`
## Tool Requirements
- Each tool must have a clear purpose and description
- Tools must handle errors gracefully
- Tools should be stateless unless absolutely necessary
- Include unit tests for each tool
- Follow PEP 8 style guidelines
- Implement click-based CLI interface
## Development Process
1. When a new capability is needed, create a new tool
2. Document the tool's purpose and usage
3. Implement the tool with proper error handling
4. Add tests to verify functionality
5. Register the tool in the tools registry
## Security Guidelines
- No destructive operations without explicit confirmation
- Validate all inputs
- Handle sensitive data appropriately
- Log all critical operations
- Never log sensitive data in plaintext
- Use environment variables for secrets
- Implement proper SSL/TLS handling
- Validate API keys before use
## Usage
Tools can be accessed via the command line:
```bash
cursor-tools [tool-name] [args] [flags]
```
Example:
```bash
cursor-tools example-tool --message "Hello World"
```
golang
less
python
