docs: establish fresh planning foundation with new features
- Update PROJECT.md: Add Android, visualizer, and avatar to v1 - Update REQUIREMENTS.md: 99 requirements across 15 phases (fresh slate) - Add comprehensive README.md with setup, architecture, and usage - Add PROGRESS.md for Discord forum sharing - Add .gitignore for Python/.venv and project artifacts - Note: All development via Claude Code/OpenCode workflow - Note: Python deps managed via .venv virtual environment Core value: Mai is a real collaborator, not a tool. She learns from you, improves herself, has boundaries and opinions, and becomes more *her* over time. v1 includes: Model interface, Safety, Resources, Memory, Conversation, CLI, Self-Improvement, Approval, Personality, Discord, Offline, Voice Visualization, Avatar, Android App, Device Sync.
This commit is contained in:
Mai Development
187
.planning/PROGRESS.md
Normal file
187
.planning/PROGRESS.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Mai Development Progress
|
||||
|
||||
**Last Updated**: 2026-01-26
|
||||
**Status**: Fresh Slate - Roadmap Under Construction
|
||||
|
||||
## Project Description
|
||||
|
||||
Mai is an autonomous conversational AI companion that runs locally-first and can improve her own code. She's not a rigid chatbot, but a genuinely intelligent collaborator with a distinct personality, long-term memory, and real agency. Mai learns from your interactions, analyzes her own performance, and proposes improvements for your review before auto-applying them.
|
||||
|
||||
**Key differentiators:**
|
||||
- **Real Collaborator**: Mai actively contributes ideas, has boundaries, and can refuse requests
|
||||
- **Learns & Evolves**: Conversation patterns inform personality layers; she remembers you
|
||||
- **Completely Local**: All inference, memory, and decision-making on your device—no cloud, no tracking
|
||||
- **Visual Presence**: Desktop avatar (image or VRoid) with real-time voice visualization
|
||||
- **Cross-Device**: Works on desktop and Android with seamless synchronization
|
||||
- **Self-Improving**: Analyzes her own code, generates improvements, and gets your approval before applying
|
||||
|
||||
**Core Value**: Mai is a real collaborator, not a tool. She learns from you, improves herself, has boundaries and opinions, and actually becomes more *her* over time.
|
||||
|
||||
---
|
||||
|
||||
## Phase Breakdown
|
||||
|
||||
### Status Summary
|
||||
- **Total Phases**: 15
|
||||
- **Completed**: 0
|
||||
- **In Progress**: 0
|
||||
- **Planned**: 15
|
||||
- **Requirements Mapped**: 99/99 (100%)
|
||||
|
||||
### Phase Details
|
||||
|
||||
| # | Phase | Goal | Requirements | Status |
|
||||
|---|-------|------|--------------|--------|
|
||||
| 1 | Model Interface | Connect to local models and intelligently switch | MODELS (7) | 🔄 Planning |
|
||||
| 2 | Safety System | Sandbox code execution and implement review workflow | SAFETY (8) | 🔄 Planning |
|
||||
| 3 | Resource Management | Monitor CPU/RAM/GPU and adapt model selection | RESOURCES (6) | 🔄 Planning |
|
||||
| 4 | Memory System | Persistent conversation storage with vector search | MEMORY (8) | 🔄 Planning |
|
||||
| 5 | Conversation Engine | Multi-turn dialogue with reasoning and context | CONVERSATION (9) | 🔄 Planning |
|
||||
| 6 | CLI Interface | Terminal-based chat with history and commands | CLI (8) | 🔄 Planning |
|
||||
| 7 | Self-Improvement | Code analysis, change generation, and auto-apply | SELFMOD (10) | 🔄 Planning |
|
||||
| 8 | Approval Workflow | User approval via CLI and Dashboard for changes | APPROVAL (9) | 🔄 Planning |
|
||||
| 9 | Personality System | Core values, behavior configuration, learned layers | PERSONALITY (8) | 🔄 Planning |
|
||||
| 10 | Discord Interface | Bot integration with DM and approval reactions | DISCORD (10) | 🔄 Planning |
|
||||
| 11 | Offline Operations | Full local-only functionality with graceful degradation | OFFLINE (7) | 🔄 Planning |
|
||||
| 12 | Voice Visualization | Real-time audio waveform and frequency display | VISUAL (5) | 🔄 Planning |
|
||||
| 13 | Desktop Avatar | Visual presence with image or VRoid model support | AVATAR (6) | 🔄 Planning |
|
||||
| 14 | Android App | Native mobile app with local inference and UI | ANDROID (10) | 🔄 Planning |
|
||||
| 15 | Device Sync | Synchronization of state and memory between devices | SYNC (6) | 🔄 Planning |
|
||||
|
||||
---
|
||||
|
||||
## Current Focus
|
||||
|
||||
**Phase**: Infrastructure & Planning
|
||||
**Work**: Establishing project structure and execution approach
|
||||
|
||||
### What's Happening Now
|
||||
- [x] Codebase mapping complete (7 architectural documents)
|
||||
- [x] Project vision and core value defined
|
||||
- [x] Requirements inventory (99 items across 15 phases)
|
||||
- [x] README with comprehensive setup and features
|
||||
- [ ] Roadmap creation (distributing requirements across phases)
|
||||
- [ ] First phase planning (Model Interface)
|
||||
|
||||
### Next Steps
|
||||
1. Create detailed ROADMAP.md with phase dependencies
|
||||
2. Plan Phase 1: Model Interface & Switching
|
||||
3. Begin implementation of LMStudio/Ollama integration
|
||||
4. Setup development infrastructure and CI/CD
|
||||
|
||||
---
|
||||
|
||||
## Recent Milestones
|
||||
|
||||
### 🎯 Project Initialization (2026-01-26)
|
||||
- Codebase mapping with 7 structured documents (STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS)
|
||||
- Deep questioning and context gathering completed
|
||||
- PROJECT.md created with core value and vision
|
||||
- REQUIREMENTS.md with 99 fully mapped requirements
|
||||
- Feature additions: Android app, voice visualizer, desktop avatar included in v1
|
||||
- README.md with comprehensive setup and architecture documentation
|
||||
- Progress report framework for regular updates
|
||||
|
||||
### 📋 Planning Foundation
|
||||
- All v1 requirements categorized into logical phases
|
||||
- Cross-device synchronization included as core feature
|
||||
- Safety and self-improvement as phase 2 priority
|
||||
- Offline capability planned as phase 11 (ensures all features work locally first)
|
||||
|
||||
---
|
||||
|
||||
## Development Methodology
|
||||
|
||||
**All phases are executed through Claude Code** (`/gsd` workflow) which provides:
|
||||
- Automated phase planning with task decomposition
|
||||
- Code generation with test creation
|
||||
- Atomic git commits with clear messages
|
||||
- Multi-agent verification (research, plan checking, execution verification)
|
||||
- Parallel task execution where applicable
|
||||
- State tracking and checkpoint recovery
|
||||
|
||||
Each phase follows the standard GSD pattern:
|
||||
1. `/gsd:plan-phase N` → Creates detailed PHASE-N-PLAN.md
|
||||
2. `/gsd:execute-phase N` → Implements with automatic test coverage
|
||||
3. Verification and state updates
|
||||
|
||||
This ensures **consistent quality**, **full test coverage**, and **clean git history** across all 15 phases.
|
||||
|
||||
## Technical Highlights
|
||||
|
||||
### Stack
|
||||
- **Primary**: Python 3.10+ (core/desktop) with `.venv` virtual environment
|
||||
- **Mobile**: Kotlin (Android)
|
||||
- **UI**: React/TypeScript (eventual web)
|
||||
- **Model Interface**: LMStudio/Ollama
|
||||
- **Storage**: SQLite (local)
|
||||
- **IPC/Sync**: Local network (no server)
|
||||
- **Development**: Claude Code (OpenCode) for all implementation
|
||||
|
||||
### Key Architecture Decisions
|
||||
| Decision | Rationale | Status |
|
||||
|----------|-----------|--------|
|
||||
| Local-first, no cloud | Privacy and independence from external services | ✅ Approved |
|
||||
| Second-agent review for all changes | Safety without blocking innovation | ✅ Approved |
|
||||
| Personality as code + learned layers | Unshakeable core + authentic growth | ✅ Approved |
|
||||
| Offline-first design (phase 11 early) | Ensure full functionality before online features | ✅ Approved |
|
||||
| Android in v1 | Mobile-first future vision | ✅ Approved |
|
||||
| Cross-device sync without server | Privacy-preserving multi-device support | ✅ Approved |
|
||||
|
||||
---
|
||||
|
||||
## Known Challenges & Solutions
|
||||
|
||||
| Challenge | Current Approach |
|
||||
|-----------|------------------|
|
||||
| Memory efficiency at scale | Auto-compressing conversation history with pattern distillation (phase 4) |
|
||||
| Model switching without context loss | Standardized context format + token budgeting (phase 1) |
|
||||
| Personality consistency across changes | Personality as code + test suite for behavior (phases 7-9) |
|
||||
| Safety vs. autonomy balance | Dual review system: agent checks breaking changes, user approves (phase 2/8) |
|
||||
| Android model inference | Quantized models + resource scaling (phase 14) |
|
||||
| Cross-device sync without server | P2P sync on local network + conflict resolution (phase 15) |
|
||||
|
||||
---
|
||||
|
||||
## How to Follow Progress
|
||||
|
||||
### Discord Forum
|
||||
Regular updates posted in the `#mai-progress` forum channel with:
|
||||
- Weekly milestone summaries
|
||||
- Blocker alerts if any
|
||||
- Community feedback requests
|
||||
|
||||
### Git & Issues
|
||||
- All work tracked in git with atomic commits
|
||||
- Phase plans in `.planning/PHASE-N-PLAN.md`
|
||||
- Progress in git commit history
|
||||
|
||||
### Local Development
|
||||
- Run `make progress` to see current status
|
||||
- Check `.planning/STATE.md` for live project state
|
||||
- Review `.planning/ROADMAP.md` for phase dependencies
|
||||
|
||||
---
|
||||
|
||||
## Get Involved
|
||||
|
||||
### Providing Feedback
|
||||
- React to forum posts with 👍 / 👎 / 🎯
|
||||
- Reply with thoughts on design decisions
|
||||
- Suggest priorities for upcoming phases
|
||||
|
||||
### Contributing
|
||||
- Development contributions coming as phases execute
|
||||
- Code review and testing needed starting Phase 1
|
||||
- Security audit important for self-improvement system
|
||||
|
||||
### Questions?
|
||||
- Ask in the Discord thread
|
||||
- Reply to this forum post with questions
|
||||
- Issues/discussions: https://github.com/yourusername/mai
|
||||
|
||||
---
|
||||
|
||||
**Mai's development is transparent and community-informed. Updates will continue as phases progress.**
|
||||
|
||||
Next Update: After Phase 1 Planning Complete (target: next week)
|
||||
Reference in New Issue
Block a user