moai/.planning/milestones/v1.0-ROADMAP.md

Milestone v1.0: MVP

Status: ✅ SHIPPED 2026-01-17 Phases: 1-6 Total Plans: 16

Overview

Build a Telegram bot where multiple AI models (Claude, GPT, Gemini) collaborate on discussions. Start with project scaffolding and tooling, add bot infrastructure, then layer in project management, single-model queries, multi-model discussions, and finally consensus/export features.

Phases

Phase 1: Foundation ✓

Goal: Complete project scaffolding with pyproject.toml, ruff, pre-commit, src layout, and SQLAlchemy models Depends on: Nothing (first phase) Plans: 3 plans

Plans:

• 01-01: Project scaffolding (pyproject.toml, ruff, pre-commit)
• 01-02: SQLAlchemy models (Project, Discussion, Round, Message, Consensus)
• 01-03: Database session management and tests

Completed: 2026-01-16

Phase 2: Bot Core ✓

Goal: Working Telegram bot responding to /help and /status commands Depends on: Phase 1 Plans: 2 plans

Plans:

• 02-01: Bot infrastructure (Application, config, lifecycle)
• 02-02: /help and /status command handlers

Completed: 2026-01-16

Phase 3: Project CRUD ✓

Goal: Full project management via Telegram (/projects, /project new/select/delete/models/info) Depends on: Phase 2 Plans: 3 plans

Plans:

• 03-01: Project service layer, /projects and /project new
• 03-02: /project select and /project info
• 03-03: /project delete and /project models

Completed: 2026-01-16

Phase 4: Single Model Q&A ✓

Goal: Query a single AI model through the bot with abstracted AI client layer Depends on: Phase 3 Plans: 2 plans

Plans:

• 04-01: AI client abstraction layer (Requesty/OpenRouter)
• 04-02: /ask command handler

Completed: 2026-01-16

Phase 5: Multi-Model Discussions ✓

Goal: Open mode (parallel), discuss mode (sequential rounds), and @mention direct messages Depends on: Phase 4 Plans: 4 plans

Plans:

• 05-01: Discussion service (CRUD operations)
• 05-02: /open command (parallel mode)
• 05-03: /discuss, /next, /stop commands (sequential mode)
• 05-04: @mention message handler

Completed: 2026-01-16

Phase 6: Consensus & Export ✓

Goal: Consensus generation from discussions and markdown export Depends on: Phase 5 Plans: 2 plans

Plans:

• 06-01: /consensus command (AI-generated synthesis)
• 06-02: /export command (markdown file)

Completed: 2026-01-17

---

Milestone Summary

Decimal Phases: None (clean milestone)

Key Decisions:

• hatchling as build backend with explicit src layout config
• String(36) for UUID storage (SQLite compatibility)
• Module-level singletons for database and AI client
• OpenAI SDK for router abstraction (Requesty/OpenRouter compatible)
• Service layer pattern for business logic
• asyncio.gather for parallel model queries
• user_data dict for discussion state across commands
• JSON format for consensus AI output
• BytesIO for in-memory markdown export

Issues Resolved:

• None (greenfield development)

Issues Deferred:

• Comprehensive error handling (retry/timeout logic)
• User allowlist middleware enforcement
• Test coverage for database error paths

Technical Debt Incurred:

• get_round_messages defined but unused
• Inconsistent get_selected_project pattern in export.py
• Missing re-exports in services/init.py

---

For current project status, see .planning/PROJECT.md