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.
111 lines
4.6 KiB
Markdown
111 lines
4.6 KiB
Markdown
# Atlas Project
|
|
|
|
## Overview
|
|
|
|
Atlas is a local, privacy-focused home voice agent system. This repository contains the project planning, architecture documentation, and kanban tickets for building the system.
|
|
|
|
The project uses a kanban-based workflow (Vibe Kanban) for task management, with tickets organized in the `tickets/` directory structure.
|
|
|
|
## Project Goals
|
|
|
|
Build a complete voice agent system with:
|
|
- **Separate work and family agents** running on dedicated hardware (RTX 4080 and RTX 1050)
|
|
- **Local, private operation** - no external APIs for core ASR/LLM (weather is exception)
|
|
- **Voice I/O** - wake-word detection, ASR, and TTS
|
|
- **MCP tools** - weather, tasks, timers, reminders, notes
|
|
- **Safety controls** - boundary enforcement, confirmation flows, admin tools
|
|
- **Long-term memory** - personal facts, preferences, routines
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
atlas/
|
|
├── .cursorrules # Cursor IDE configuration and rules
|
|
├── README.md # This file
|
|
├── ARCHITECTURE.md # Architecture documentation
|
|
├── tickets/ # Kanban tickets and task management
|
|
│ ├── backlog/ # Backlog items
|
|
│ ├── todo/ # Items ready to work on
|
|
│ ├── in-progress/ # Currently active work
|
|
│ ├── review/ # Items awaiting review
|
|
│ └── done/ # Completed items
|
|
└── [project code] # Your project code will go here
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
1. Review the [ARCHITECTURE.md](./ARCHITECTURE.md) for project design and patterns
|
|
2. Check [tickets/TICKETS_SUMMARY.md](./tickets/TICKETS_SUMMARY.md) for an overview of all 46 tickets
|
|
3. Read [tickets/QUICK_START.md](./tickets/QUICK_START.md) for recommended starting order
|
|
4. Follow the guidelines in [.cursorrules](./.cursorrules) for development
|
|
|
|
## Project Tracks
|
|
|
|
The project is organized into 5 parallel tracks:
|
|
|
|
1. **Voice I/O** (12 tickets): Wake-word detection, ASR (Automatic Speech Recognition), TTS (Text-to-Speech)
|
|
2. **LLM Infrastructure** (11 tickets): Model selection, servers for 4080 (work) and 1050 (family), routing, prompts
|
|
3. **Tools/MCP** (11 tickets): Model Context Protocol server, weather, tasks, timers, reminders, notes, optional integrations
|
|
4. **Clients/UI** (2 tickets): Phone PWA and web LAN dashboard
|
|
5. **Safety/Memory** (6 tickets): Long-term memory, conversation management, boundary enforcement, confirmations
|
|
|
|
Plus **Project Setup** (4 tickets) for foundation work.
|
|
|
|
## Kanban Workflow
|
|
|
|
This project uses a kanban board (Vibe Kanban) for task management. **46 tickets** are organized in the `tickets/` directory:
|
|
|
|
- **backlog/**: 46 tickets ready to start
|
|
- **todo/**: Ready to work on (dependencies met)
|
|
- **in-progress/**: Currently being worked on
|
|
- **review/**: Awaiting review or testing
|
|
- **done/**: Completed items
|
|
|
|
### Working with Tickets
|
|
|
|
1. **Start with Milestone 1**: Foundation tickets (TICKET-002, TICKET-003, TICKET-004)
|
|
2. **Move tickets as you work**: `backlog/` → `todo/` → `in-progress/` → `review/` → `done/`
|
|
3. **Reference ticket IDs in commits**: `git commit -m "TICKET-002: Define repo structure"`
|
|
4. **Sync with Vibe Kanban**: Import tickets using ticket IDs, tag by track and milestone
|
|
5. **Use ticket template**: See `tickets/TICKET_TEMPLATE.md` for new tickets
|
|
|
|
### Milestones
|
|
|
|
- **Milestone 1 - Survey & Architecture**: Foundation, technology evaluations
|
|
- **Milestone 2 - Voice Chat + Weather + Tasks MVP**: Core functionality working
|
|
- **Milestone 3 - Memory, Reminders, Safety**: Advanced features and safety
|
|
- **Milestone 4 - Optional Integrations**: Email, calendar, smart home
|
|
|
|
## Development Guidelines
|
|
|
|
- Follow the rules defined in `.cursorrules`
|
|
- Maintain code quality and documentation
|
|
- Write tests for new features
|
|
- Update architecture docs for significant changes
|
|
- Reference ticket numbers in all commits
|
|
- Keep tickets in sync with Vibe Kanban board
|
|
|
|
## Repository Structure
|
|
|
|
This repository (`atlas/`) contains:
|
|
- **Planning and documentation**: Architecture, tickets, project management
|
|
- **Kanban tickets**: 46 tickets organized by status and track
|
|
|
|
The actual implementation will be in separate repositories:
|
|
- `home-voice-agent/`: Main mono-repo with all services and clients
|
|
- `family-agent-config/`: Separate config repo for prompts, tools, secrets (no work content)
|
|
|
|
See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed repository structure.
|
|
|
|
## Contributing
|
|
|
|
1. Check existing tickets in `tickets/` before starting work
|
|
2. Create a ticket for new features or bugs using the template
|
|
3. Follow the established code style and patterns
|
|
4. Update documentation as needed
|
|
5. Move tickets through the workflow as you progress
|
|
|
|
## License
|
|
|
|
[Add your license here]
|