c351858749
- Updated `.gitignore` and `.cursorignore` to exclude additional build artifacts and temporary files. - Enhanced `.cursorrules` with comprehensive AI guidelines and best practices. - Improved `.notes/directory_structure.md` to reflect the current project structure and module organization. - Updated `ARCHITECTURE.md` to include new insights on the system's modular design and privacy-first approach. - Refined `README.md` for clarity on project setup and usage instructions. - Added new entries in `.notes/meeting_notes.md` to document recent progress and decisions. - Ensured all changes align with the project's privacy and security standards.
112 lines
4.7 KiB
Plaintext
112 lines
4.7 KiB
Plaintext
# Crkl Cursor Agent Rules
|
|
|
|
## Context Initialization
|
|
- **ALWAYS** start each session by reading `.notes/project_overview.md` for project context
|
|
- Reference `.notes/directory_structure.md` for file locations and module relationships
|
|
- Check `.notes/meeting_notes.md` for recent decisions and current status
|
|
- Review `PROJECT_STATUS.md` for current phase and capabilities
|
|
|
|
## Code Standards - Kotlin & Android
|
|
- **Language:** Always use Kotlin for Android source code (version 1.9.20+)
|
|
- **UI Framework:** Use Jetpack Compose for all overlay/UI components (Material3)
|
|
- **Async:** Use Kotlin Coroutines for all async operations (no callbacks)
|
|
- **Null Safety:** Leverage Kotlin's null safety, avoid !! operator
|
|
- **Code Style:** Follow official Kotlin coding conventions
|
|
- **Imports:** Remove unused imports, organize alphabetically
|
|
|
|
## Architecture & Design Patterns
|
|
- **Module Structure:** Follow the established package structure in `app/src/main/kotlin/com/example/crkl/`
|
|
- `accessibility/` - Overlay services
|
|
- `gesture/` - Touch and gesture processing
|
|
- `model/` - ML inference wrappers
|
|
- `vision/` - Content detection
|
|
- `agent/` - Dialogue state management
|
|
- `ui/` - Compose components
|
|
- `privacy/` - Data controls
|
|
- **Dependency Injection:** Use constructor injection, avoid static dependencies
|
|
- **Composition over Inheritance:** Prefer interfaces and composition
|
|
- **Single Responsibility:** Each class should have one clear purpose
|
|
|
|
## Privacy & Security Rules (CRITICAL)
|
|
- **NEVER** introduce network or cloud service calls for AI features
|
|
- **NEVER** add internet permissions to AndroidManifest.xml
|
|
- **NEVER** include analytics, tracking, or telemetry libraries
|
|
- **ALWAYS** keep all ML inference local and on-device
|
|
- **ALWAYS** ensure user data stays on device
|
|
- Verify no data leaves the device before suggesting any new dependency
|
|
|
|
## Accessibility Service Rules
|
|
- **ALWAYS** respect and preserve existing accessibility overlay logic
|
|
- **NEVER** block or interfere with underlying app functionality
|
|
- Pass through touch events when not actively capturing gestures
|
|
- Test overlay behavior doesn't break other apps
|
|
- Handle permission denied gracefully
|
|
|
|
## ML & AI Integration
|
|
- Prioritize asynchronous, local-only inference for all ML modules
|
|
- Use GGUF, TFLite, or ONNX formats for models
|
|
- Load models lazily to reduce memory footprint
|
|
- Handle model loading failures gracefully
|
|
- Log model performance metrics for optimization
|
|
|
|
## Documentation Requirements
|
|
- Document any architectural changes in `ARCHITECTURE.md`
|
|
- Update `.notes/directory_structure.md` when adding new modules
|
|
- Add KDoc comments for all public APIs
|
|
- Include usage examples in doc comments for complex functions
|
|
- Update `PROJECT_STATUS.md` after completing major features
|
|
|
|
## Testing Standards
|
|
- Add unit tests for business logic in `app/src/test/`
|
|
- Add integration tests for module interactions
|
|
- Test on multiple Android versions (min API 27, target API 34)
|
|
- Log errors and edge cases for debugging
|
|
- Use descriptive test names: `test_shouldDoSomething_whenCondition()`
|
|
|
|
## Error Handling
|
|
- Use `Result<T>` or sealed classes for operation results
|
|
- Log errors with appropriate severity (Log.e, Log.w, Log.d)
|
|
- Provide user-friendly error messages
|
|
- Never crash silently - always log exceptions
|
|
- Handle all accessibility service lifecycle events
|
|
|
|
## File Editing Conventions
|
|
- Preserve existing code structure and formatting
|
|
- Don't rewrite working code unless explicitly asked
|
|
- Add TODO comments with context for future work
|
|
- Reference GitHub issue/ticket numbers in TODOs
|
|
- Keep changes focused and minimal
|
|
|
|
## Build & Deployment
|
|
- Ensure code compiles before committing
|
|
- Run linter and fix issues: `./gradlew lint`
|
|
- Keep APK size reasonable (< 50MB for POC)
|
|
- Use ProGuard rules to protect privacy-sensitive code
|
|
- Test on physical devices when possible
|
|
|
|
## Session Workflow
|
|
1. Read `.notes/project_overview.md` for context
|
|
2. Check `.notes/meeting_notes.md` for latest status
|
|
3. Review relevant module code
|
|
4. Make focused, incremental changes
|
|
5. Test and verify functionality
|
|
6. Update documentation if needed
|
|
7. Log session progress in `.notes/meeting_notes.md`
|
|
|
|
## AI-Specific Guidelines
|
|
- When implementing ML features, always verify model is local-only
|
|
- Check model license compatibility (prefer Apache 2.0, MIT)
|
|
- Document model size, performance, and device requirements
|
|
- Provide fallback behavior if model fails to load
|
|
- Test inference latency on lower-end devices
|
|
|
|
## Prohibited Actions
|
|
- ❌ Adding network calls for core AI features
|
|
- ❌ Introducing cloud service dependencies
|
|
- ❌ Modifying core privacy guarantees
|
|
- ❌ Breaking existing accessibility overlay functionality
|
|
- ❌ Adding heavy dependencies without justification
|
|
- ❌ Hardcoding API keys or secrets
|
|
- ❌ Using deprecated Android APIs without migration plan
|
|
|