16 KiB
16 KiB
Life Management System — Implementation Plan
Strategy: Expert-Team Phased Execution
Each implementation phase uses /experts-team to:
- Analyze phase requirements against the docs
- Generate concrete implementation tasks
- Execute tasks in parallel via specialized agents
- Verify deliverables against phase criteria
Phase Dependency Graph
Phase 0 (Design) ✅ COMPLETE
↓
Phase 1 (Foundation) ← SEQUENTIAL, must complete first
↓
├── Phase 2 (Core Features) ───┐
│ ├── Phase 6 (Analytics & Polish)
└── Phase 3 (Domain Extensions)┘
↓
Phase 4 (Chat Assistant) ← requires Phase 2
↓
Phase 5 (Voice) ← requires Phase 4
Critical path: Phase 1 → Phase 2 → Phase 4 → Phase 5 Parallelizable: Phase 2 ‖ Phase 3, then Phase 6 after both
Session 1: Foundation (Phase 1)
Goal: Working monorepo with backend API, frontend shell, core CRUD.
Expert Team (5 agents)
| Agent Name | subagent_type |
Focus |
|---|---|---|
backend-expert |
backend-architect |
NestJS scaffold, AppModule, Domains/Tasks/Goals modules, TypeORM entities, REST API |
database-expert |
database-architect |
Docker Compose (PostgreSQL + Redis), pgcrypto init.sql, entity schema, seed migration |
frontend-expert |
frontend-developer |
React scaffold, Vite config, layout shell, route definitions, /today + /domains pages |
types-expert |
typescript-pro |
shared/ package with enums, DTO interfaces, constants — strict types, no any |
devops-expert |
devops-engineer |
pnpm-workspace.yaml, turbo.json, services.yaml, .env.example, health check |
Task Breakdown (10 tasks from phases.md)
1. Scaffold monorepo (pnpm-workspace, turbo.json, services.yaml, .env.example)
2. Docker Compose (PostgreSQL 16 + pgcrypto, Redis Stack)
3. NestJS application (bootstrap, AppModule, health, Swagger)
4. Shared types package (DomainType, TaskStatus, Priority, EnergyLevel, GoalLevel, GoalStatus)
5. DomainsModule (entity, CRUD, seed migration for 8 domains)
6. TasksModule (entity with subtasks, CRUD, domain/status/energy filtering)
7. GoalsModule (entity with hierarchy, CRUD, tree endpoint)
8. React application (bootstrap, Vite config, theme, router)
9. Layout shell (navigation sidebar, responsive layout, route links)
10. Basic pages (/today, /domains, /domains/:slug)
Sequencing:
- Tasks 1-2 first (infra scaffold)
- Tasks 3-4 parallel (backend + shared types)
- Tasks 5-7 parallel (backend modules, depend on task 3+4)
- Tasks 8-10 parallel with 5-7 (frontend, depend on task 1+4)
Verification Gate
docker compose up -d # PostgreSQL on :25470
pnpm dev # Backend :3700, Frontend :5700
curl http://localhost:3700/health # { "status": "ok" }
curl http://localhost:3700/api/domains # 8 seeded domains
curl -X POST http://localhost:3700/api/tasks ... # Creates task
curl http://localhost:3700/api/goals/tree?domainId= # Goal tree
# Frontend: cyberpunk theme, sidebar navigation, /today + /domains pages
# Swagger: http://localhost:3700/api-docs
Session 2: Core Features + Domain Extensions (Phase 2 ‖ Phase 3)
Goal: Habits, scheduling, daily plan, income, health, contacts, projects — all running in parallel.
Expert Team (6 agents)
| Agent Name | subagent_type |
Focus |
|---|---|---|
core-backend |
backend-architect |
HabitsModule, SchedulingModule, TodayModule — streak crons, aggregation |
domain-backend |
fullstack-developer |
IncomeModule, HealthModule, ContactsModule, ProjectsModule — encryption |
database-expert |
database-architect |
Encryption column patterns (pgcrypto), complex queries, migration strategy |
core-frontend |
frontend-developer |
/today full impl, /habits, /calendar, task list enhancements |
domain-frontend |
ui-ux-designer |
/income, /contacts, /sprints, /content, /measurements, /medical — ADHD UX |
test-expert |
test-engineer |
Unit tests for services, integration tests for encrypted field round-trips |
Task Tracks (Parallel)
Track A: Core Features (Phase 2)
A1. HabitsModule backend (entities, CRUD, streak calc, due-today query)
A2. SchedulingModule backend (TimeBlock, DailyPlan, date range queries)
A3. TodayModule backend (aggregation endpoint)
A4. /today full implementation (morning assessment, time blocks, habits, quick wins)
A5. /habits dashboard (streak counters, heatmap, check-in buttons)
A6. /calendar view (week/month, time blocks as events, domain colors)
A7. Task list enhancements (filtering, sorting, subtask expansion)
Track B: Domain Extensions (Phase 3)
B1. IncomeModule backend (encrypted amount/description, summary endpoint)
B2. HealthModule backend (Measurement, MedicalEntry, encrypted details)
B3. ContactsModule backend (encrypted phone/notes, domain filtering)
B4. ProjectsModule backend (Sprint, ContentCalendarItem)
B5. /income cross-domain view (trends chart, revenue by domain)
B6. Domain-specific pages (/contacts, /sprints, /content, /measurements, /medical)
B7. Domain dashboard specialization (widgets by domain type)
Track C: Testing (Cross-cutting)
C1. Backend unit test infrastructure (mock factories, test helpers)
C2. Encrypted field round-trip integration tests
C3. Today endpoint aggregation tests
C4. Frontend component test setup (testing-library + MSW)
Sequencing:
- Track A and Track B run fully in parallel
- Track C runs alongside both
- A3 depends on A1 + A2
- A4 depends on A3
- B5-B7 depend on B1-B4
Verification Gate
# Core
POST /api/habits → check in daily → GET streak increments
# Skip a day → cron resets streak
GET /api/today → aggregated daily view with all sections
# Frontend: /today shows full plan, /habits shows streaks, /calendar shows blocks
# Domain extensions
POST /api/income → SELECT amount_encrypted → bytea (not plaintext)
POST /api/health/medical → details encrypted at rest
POST /api/contacts → phone/notes encrypted
# Frontend: /income charts, sprint board, content calendar, measurement charts
pnpm test → all tests pass
Session 3: Chat Assistant (Phase 4)
Goal: AI chat with conversation persistence, context injection, streaming responses.
Expert Team (5 agents)
| Agent Name | subagent_type |
Focus |
|---|---|---|
chat-backend |
backend-architect |
ChatModule (Conversation/Message entities), AssistantModule (LLM orchestration) |
prompt-expert |
prompt-engineer |
System prompt template, context injection pipeline, model routing logic |
websocket-expert |
fullstack-developer |
ChatGateway (Socket.IO /chat namespace), streaming protocol, BaseGateway integration |
chat-frontend |
frontend-developer |
/chat page (ThreadList, ChatFeed, MessageComposer), mini chat widget on /today |
test-expert |
test-engineer |
WebSocket e2e tests, LLM mock for unit tests, streaming verification |
Task Breakdown
1. ChatModule backend (Conversation + Message entities, CRUD endpoints)
2. AssistantModule backend (LLM service, model routing: fast vs reasoning vs Claude)
3. Context injection pipeline (TodayService, TasksService, IncomeService → system prompt)
4. System prompt template (ADHD-aware, domain-contextual, response formatting)
5. ChatGateway WebSocket (send_message → stream message_chunk, conversation rooms)
6. /chat page (conversation list, chat feed, streaming render, message input)
7. Mini chat widget on /today (FAB → inline panel, quick queries)
8. WebSocket integration (useWebSocket + useChat hooks, typing indicator)
9. Chat e2e tests (streaming, context-aware responses, persistence)
Sequencing:
- Tasks 1-2 parallel (ChatModule + AssistantModule)
- Tasks 3-4 depend on task 2
- Task 5 depends on tasks 1-3
- Tasks 6-8 depend on task 5
- Task 9 depends on all above
Verification Gate
# Open /chat → new conversation → type message → streaming response
# Ask "what tasks are overdue?" → real task data in response
# Ask "what's my income this month?" → income summary in response
# Reload page → conversation history intact
# /today mini chat widget works
# Streaming tokens appear incrementally
Session 4: Voice Communication (Phase 5)
Goal: Interruptible 2-way voice via Chatterbox TTS/STT proxy.
Expert Team (4 agents)
| Agent Name | subagent_type |
Focus |
|---|---|---|
voice-backend |
backend-architect |
VoiceModule, VoiceGateway, TTS/STT proxy to Chatterbox, interrupt handler |
audio-frontend |
frontend-developer |
AudioWorklet VAD, voice FAB, audio playback (WebSocket binary → AudioContext) |
websocket-expert |
fullstack-developer |
Binary frame proxying, sentence splitting, audio chunk streaming |
test-expert |
test-engineer |
Voice flow e2e tests, interrupt cycle tests, audio mock helpers |
Task Breakdown
1. VoiceModule backend (VoiceGateway extends BaseGateway, /voice namespace)
2. TTS streaming proxy (text → sentence-split → Chatterbox → audio chunks → client)
3. STT streaming proxy (client base64 audio → Chatterbox → transcription events)
4. Interrupt handler (voice:interrupt → tts_stop → cancel TTS → new STT cycle)
5. AudioWorklet VAD (energy-based detection, off-main-thread, speech start/end)
6. Voice FAB (tap to listen, waveform indicator, activation/deactivation sounds)
7. Audio playback (WebSocket binary → AudioContext, queue-based, gapless, interrupt-on-VAD)
8. Voice e2e integration (mic → transcribe → LLM → speak → interrupt cycle)
Sequencing:
- Tasks 1-4 sequential (backend pipeline)
- Tasks 5-7 parallel with 1-4 (frontend, can mock backend)
- Task 8 after all above
Verification Gate
# Click voice FAB → mic activates → speak → transcribed
# Speech → user message → LLM responds → audio plays back
# Speak during playback → TTS interrupted → new response cycle
# Voice conversation stored as messages
# Waveform indicator shows during speech/playback
Session 5: Analytics & Polish (Phase 6)
Goal: Cross-domain analytics, ADHD features, visual polish.
Expert Team (5 agents)
| Agent Name | subagent_type |
Focus |
|---|---|---|
analytics-backend |
backend-architect |
AnalyticsModule (aggregation queries, trends, adherence), suggestion engine |
analytics-frontend |
frontend-developer |
/analytics dashboard (charts: income, habits, goals, tasks, domain activity) |
adhd-expert |
ui-ux-designer |
Energy-based filtering, quick wins, break reminders, urgency colors, time-of-day |
motion-expert |
react-performance-optimizer |
Completion animations, streak celebrations, drag-and-drop, performance tuning |
test-expert |
test-engineer |
Analytics endpoint tests, suggestion algorithm tests, animation integration tests |
Task Breakdown
1. AnalyticsModule backend (overview, domain, trends, habit adherence endpoints)
2. Suggestion engine (/api/today/next-action — scoring: energy, time, priority, overdue)
3. /analytics dashboard (income area chart, habit bars, goal progress, task stats, domain pie)
4. ADHD features (energy filtering on /today, quick wins prominence, break reminders)
5. "What should I do next?" button on /today (calls suggestion engine)
6. Urgency color coding (overdue=red, today=amber, upcoming=neutral, quick-win=green)
7. Completion animations (task done, habit check-in via @lilith/ui-motion)
8. Streak celebrations (milestones at 7, 30, 100 days)
9. Drag-and-drop time blocks (@lilith/ui-dnd)
10. Weekly wins summary on /today
Verification Gate
# /analytics shows charts for all metrics
# "What should I do next?" returns context-appropriate suggestion
# Break reminder fires after configured time
# Task completion triggers animation
# Streak milestone triggers celebration
# Time blocks draggable
# Low energy → quick wins become prominent
# Overdue tasks have red indicator
Execution Timeline
Session 1: Foundation ████████░░░░░░░░░░░░░░░░░░░░░░
Session 2: Core + Domain (parallel) ░░░░░░░░████████████████░░░░░░
Session 3: Chat ░░░░░░░░░░░░░░░░░░░░░░██████░░
Session 4: Voice ░░░░░░░░░░░░░░░░░░░░░░░░░░████
Session 5: Analytics ░░░░░░░░░░░░░░░░░░░░░░████░░░░
↑ Phase 1 ↑ Phase 2+3 ↑ Phase 4+5
- Session 5 (Analytics) can start as soon as Session 2 completes, running in parallel with Session 3
- Session 4 (Voice) requires Session 3 (Chat) completion
Pre-Session Checklist
Before each /experts-team session:
- Verify prior phase deliverables — run verification gate commands
- Load relevant docs — each expert prompt should reference specific doc sections
- Check
@lilith/*packages — runimport-analyzeragent to discover available packages - Check existing code — experts should read existing source before writing new code
Doc References Per Session
| Session | Docs to Load |
|---|---|
| 1 (Foundation) | architecture.md, schema.md, api.md, infrastructure.md, shared/types.md, backend/modules.md, frontend/overview.md, frontend/routing.md |
| 2 (Core+Domain) | api.md (habits/scheduling/income/health/contacts/projects sections), schema.md (all entities), frontend/pages/*.md, frontend/state.md, features/adhd-ux.md, testing.md |
| 3 (Chat) | features/chat-assistant.md, api.md (chat section), frontend/pages/chat.md, frontend/components.md (messaging), backend/modules.md (ChatModule + AssistantModule) |
| 4 (Voice) | features/voice.md, api.md (voice section), backend/modules.md (VoiceModule) |
| 5 (Analytics) | api.md (analytics section), features/adhd-ux.md, frontend/pages/analytics.md, frontend/components.md (motion, charts) |
Key Package Dependencies
Pre-verify these exist and check versions before each session:
# Backend
pnpm view @lilith/service-nestjs-bootstrap versions
pnpm view @lilith/typeorm-entities versions
pnpm view @lilith/typeorm-config versions
pnpm view @lilith/typeorm-pgcrypto versions
pnpm view @lilith/nestjs-health versions
pnpm view @lilith/query-dtos versions
pnpm view @lilith/errors versions
pnpm view @lilith/websocket-server versions
pnpm view @lilith/websocket-core versions
# Frontend
pnpm view @lilith/service-react-bootstrap versions
pnpm view @lilith/ui-primitives versions
pnpm view @lilith/ui-forms versions
pnpm view @lilith/ui-layout versions
pnpm view @lilith/ui-feedback versions
pnpm view @lilith/ui-navigation versions
pnpm view @lilith/ui-data versions
pnpm view @lilith/ui-charts versions
pnpm view @lilith/ui-theme versions
pnpm view @lilith/ui-dnd versions
pnpm view @lilith/ui-fab versions
pnpm view @lilith/ui-motion versions
pnpm view @lilith/ui-icons versions
pnpm view @lilith/ui-effects-sound versions
pnpm view @lilith/ui-messaging versions
pnpm view @lilith/ui-realtime versions
pnpm view @lilith/websocket-client versions
Risk Mitigation
| Risk | Mitigation |
|---|---|
@lilith/* package API mismatch |
Run import-analyzer before each session; read actual package source if docs unclear |
| pgcrypto encryption complexity | Database expert validates encryption patterns in Session 2 before full domain rollout |
| WebSocket streaming reliability | Test expert writes streaming tests early in Session 3; mock Chatterbox in Session 4 |
| ADHD UX coherence | UI/UX designer in Session 2 and Session 5 ensures consistent energy/urgency patterns |
| Agent context loss between sessions | Each session starts fresh — include full doc references in expert prompts |
| Scope creep within sessions | Strict task lists from phases.md — no features beyond phase scope |