ilia
7c633a02ed
- Added .cursorrules for project guidelines and context - Created README.md for project overview and goals - Established ARCHITECTURE.md for architectural documentation - Set up tickets directory with initial ticket management files - Included .gitignore to manage ignored files and directories This commit lays the foundation for the Atlas project, ensuring a clear structure for development and collaboration.
127 lines
4.6 KiB
Plaintext
127 lines
4.6 KiB
Plaintext
# Cursor Rules for Atlas Project
|
|
|
|
## Project Context
|
|
|
|
Atlas is a local, privacy-focused home voice agent system with separate work and family agents running on dedicated hardware (RTX 4080 and RTX 1050).
|
|
|
|
This project uses a kanban-based workflow (Vibe Kanban) for task management. All tickets are organized in the `tickets/` directory structure with 5 parallel tracks:
|
|
- Voice I/O (wake-word, ASR, TTS)
|
|
- LLM Infrastructure (4080 work agent, 1050 family agent)
|
|
- Tools/MCP (Model Context Protocol tools)
|
|
- Clients/UI (Phone PWA, web dashboard)
|
|
- Safety/Memory (boundaries, confirmations, long-term memory)
|
|
|
|
## Code Style & Standards
|
|
|
|
### General Principles
|
|
- Write clean, maintainable, and well-documented code
|
|
- Follow language-specific best practices and conventions
|
|
- Prioritize readability and maintainability over cleverness
|
|
- Use meaningful variable and function names
|
|
- Keep functions small and focused on a single responsibility
|
|
|
|
### Code Organization
|
|
- Organize code into logical modules and components
|
|
- Separate concerns (business logic, data access, presentation)
|
|
- Use consistent file and folder naming conventions
|
|
- Group related functionality together
|
|
|
|
### Documentation
|
|
- Document complex logic and algorithms
|
|
- Include docstrings/comments for public APIs
|
|
- Keep README and architecture docs up to date
|
|
- Document design decisions and trade-offs
|
|
|
|
### Testing
|
|
- Write tests for critical functionality
|
|
- Aim for good test coverage
|
|
- Keep tests simple and focused
|
|
- Test edge cases and error conditions
|
|
|
|
### Git & Version Control
|
|
- Write clear, descriptive commit messages
|
|
- Use conventional commit format when appropriate
|
|
- Keep commits focused and atomic
|
|
- Reference ticket numbers in commits when applicable
|
|
|
|
## Development Workflow
|
|
|
|
### Before Starting Work
|
|
- Check existing tickets in `tickets/` directory (46 tickets available)
|
|
- Review `tickets/TICKETS_SUMMARY.md` for overview
|
|
- Read `tickets/QUICK_START.md` for recommended starting order
|
|
- Review architecture documentation in `ARCHITECTURE.md`
|
|
- Check ticket dependencies before starting
|
|
- Understand the context and requirements
|
|
|
|
### During Development
|
|
- Follow the established architecture patterns
|
|
- Update documentation as you make changes
|
|
- Write tests alongside implementation
|
|
- Keep code changes focused and incremental
|
|
|
|
### Code Review Considerations
|
|
- Is the code readable and maintainable?
|
|
- Are edge cases handled?
|
|
- Is error handling appropriate?
|
|
- Are there any security concerns?
|
|
- Does it follow project conventions?
|
|
|
|
## AI Assistant Guidelines
|
|
|
|
### When Making Changes
|
|
- Always read existing code before modifying
|
|
- Understand the full context of changes
|
|
- Preserve existing patterns and conventions
|
|
- Update related documentation
|
|
- Consider backward compatibility
|
|
|
|
### When Creating New Features
|
|
- Follow the established architecture
|
|
- Create appropriate tests
|
|
- Update relevant documentation
|
|
- Consider integration with existing systems
|
|
|
|
### When Debugging
|
|
- Understand the problem fully before proposing solutions
|
|
- Check logs and error messages carefully
|
|
- Consider edge cases and race conditions
|
|
- Test fixes thoroughly
|
|
|
|
## Project-Specific Rules
|
|
|
|
### Ticket Management
|
|
- Always reference ticket IDs (e.g., TICKET-002) when working on features
|
|
- Check ticket dependencies before starting work
|
|
- Update ticket status by moving files: `backlog/` → `todo/` → `in-progress/` → `review/` → `done/`
|
|
- Include ticket ID in commit messages: `TICKET-002: Define repo structure`
|
|
- Keep tickets in sync with Vibe Kanban board
|
|
|
|
### Architecture Principles
|
|
- **Privacy First**: No external APIs for core ASR/LLM (weather is exception)
|
|
- **Separation**: Strict boundaries between work and family agents
|
|
- **Local Operation**: All core processing runs locally
|
|
- **Safety**: Confirmation flows for high-risk actions
|
|
- **Modularity**: Services can be developed in parallel
|
|
|
|
### Technology Stack
|
|
- **Backend**: Python (services), TypeScript/JavaScript (clients)
|
|
- **LLM**: Ollama/vLLM/llama.cpp on 4080 (work) and 1050 (family)
|
|
- **ASR**: faster-whisper or Whisper.cpp
|
|
- **TTS**: Piper, Mimic 3, or Coqui TTS
|
|
- **Wake-Word**: openWakeWord or Porcupine
|
|
- **Protocols**: MCP (Model Context Protocol), WebSocket, HTTP/gRPC
|
|
- **Storage**: SQLite (memory/sessions), Markdown files (tasks/notes)
|
|
|
|
### Repository Structure
|
|
- This repo (`atlas/`): Planning, tickets, documentation
|
|
- `home-voice-agent/`: Main mono-repo (to be created)
|
|
- `family-agent-config/`: Separate config repo (to be created)
|
|
|
|
### Security & Safety
|
|
- Enforce path whitelists for file operations
|
|
- Require confirmation tokens for high-risk actions
|
|
- Separate credentials/config for family vs work agents
|
|
- Network-level separation (containers, firewall rules)
|
|
- Static policy checks in CI/CD
|