# 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