mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

feat(P0-001): scaffold monorepo structure (#60)

Browse Source 
Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>
This commit was merged in pull request #60.
This commit is contained in:
Jason Woltje
2026-03-13 01:11:46 +00:00
committed by jason.woltje
parent 339641352e
commit 6d0d288e31
99 changed files with 5926 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
docs/PRD.md
View File

@@ -8,7 +8,7 @@
- **Best-Guess Mode:** true
- Repo (target): `git.mosaicstack.dev/mosaic/mosaic-stack`
- Baseline: `~/src/jarvis-old` (jarvis v0.2.0)
- Package source: `~/src/mosaic-mono-v0` (@mosaic/* packages)
- Package source: `~/src/mosaic-mono-v0` (@mosaic/\* packages)
- Agent harness: [pi](https://github.com/badlogic/pi-mono) (v0.57.1)
- Remote control reference: [OpenClaw](https://github.com/openclaw/openclaw) (upstream, canonical)
@@ -32,7 +32,7 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
4. **Gateway orchestrator** — Central routing layer that dispatches tasks to appropriate agents based on capability, cost, and context
5. **Shared memory** — PostgreSQL canonical store + vector DB for semantic search + tiered log summarization to prevent context creep
6. **Multi-user with SSO** — BetterAuth with Authentik/WorkOS/Keycloak SSO, RBAC for family/team/business use
7. **Full @mosaic/* package integration** — brain, queue, coord, mosaic, prdy, quality-rails, cli all integrated
7. **Full @mosaic/\* package integration** — brain, queue, coord, mosaic, prdy, quality-rails, cli all integrated
8. **Extensible** — MCP capability, skill import interface, plugin architecture for LLM providers and remote channels
---
@@ -128,26 +128,26 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
### Technology Decisions
| Layer | Technology | Rationale |
|-------|-----------|-----------|
| **Web Frontend** | Next.js 16 + React 19 + Tailwind CSS | SSR, RSC; design tokens from @mosaic/design-tokens (mosaic-stack-website) |
| **API / Gateway** | NestJS + Fastify adapter | Module system, DI, guards/interceptors for complex gateway; Fastify performance underneath |
| **Agent Runtime** | Pi SDK (embedded) | Extensible harness with tools, skills, session management |
| **TUI** | Pi interactive mode | Native terminal agent interaction |
| **Auth** | BetterAuth + SSO adapters | Multi-user RBAC with Authentik/WorkOS/Keycloak |
| **Database** | PostgreSQL 17 + pgvector | Canonical store; pgvector for embedding search |
| **Vector DB** | pgvector + VectorStore interface | pgvector for v0.1.0; `VectorStore` abstraction in @mosaic/memory makes Qdrant a drop-in later |
| **Cache / Queue** | Valkey 8 | Redis-compatible; proven in @mosaic/queue |
| **ORM** | Drizzle ORM | TypeScript-native, lightweight, good migration story |
| **Validation** | Zod | Already used across @mosaic/* packages |
| **Build** | pnpm workspaces + Turborepo | Proven in both jarvis-old and mosaic-mono-v0 |
| **Testing** | Vitest + Playwright | Unit/integration via Vitest, E2E via Playwright |
| **Remote Control** | Discord.js + Telegraf | Inspired by OpenClaw plugin architecture |
| **MCP** | @modelcontextprotocol/sdk | Already used in @mosaic/brain and @mosaic/queue |
| **Container** | Docker Compose | Self-hosted; bare-metal also supported |
| **CI** | Woodpecker CI | Existing infrastructure at git.mosaicstack.dev |
| **Observability** | OpenTelemetry + SigNoz | Wide-event logging from day one; OTEL auto-instrumentation for NestJS/PG/HTTP; SigNoz as all-in-one backend |
| **Log Processing** | Custom ingest service | Parse agent logs → tiered storage → summarization |
| Layer | Technology | Rationale |
| ------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Web Frontend** | Next.js 16 + React 19 + Tailwind CSS | SSR, RSC; design tokens from @mosaic/design-tokens (mosaic-stack-website) |
| **API / Gateway** | NestJS + Fastify adapter | Module system, DI, guards/interceptors for complex gateway; Fastify performance underneath |
| **Agent Runtime** | Pi SDK (embedded) | Extensible harness with tools, skills, session management |
| **TUI** | Pi interactive mode | Native terminal agent interaction |
| **Auth** | BetterAuth + SSO adapters | Multi-user RBAC with Authentik/WorkOS/Keycloak |
| **Database** | PostgreSQL 17 + pgvector | Canonical store; pgvector for embedding search |
| **Vector DB** | pgvector + VectorStore interface | pgvector for v0.1.0; `VectorStore` abstraction in @mosaic/memory makes Qdrant a drop-in later |
| **Cache / Queue** | Valkey 8 | Redis-compatible; proven in @mosaic/queue |
| **ORM** | Drizzle ORM | TypeScript-native, lightweight, good migration story |
| **Validation** | Zod | Already used across @mosaic/\* packages |
| **Build** | pnpm workspaces + Turborepo | Proven in both jarvis-old and mosaic-mono-v0 |
| **Testing** | Vitest + Playwright | Unit/integration via Vitest, E2E via Playwright |
| **Remote Control** | Discord.js + Telegraf | Inspired by OpenClaw plugin architecture |
| **MCP** | @modelcontextprotocol/sdk | Already used in @mosaic/brain and @mosaic/queue |
| **Container** | Docker Compose | Self-hosted; bare-metal also supported |
| **CI** | Woodpecker CI | Existing infrastructure at git.mosaicstack.dev |
| **Observability** | OpenTelemetry + SigNoz | Wide-event logging from day one; OTEL auto-instrumentation for NestJS/PG/HTTP; SigNoz as all-in-one backend |
| **Log Processing** | Custom ingest service | Parse agent logs → tiered storage → summarization |
### Key Architecture Decisions
@@ -245,6 +245,7 @@ mosaic-mono-v1/
### Package Responsibilities
#### `apps/gateway` — @mosaic/gateway (NEW — critical path)
The central nervous system. All clients connect here. Built with NestJS (Fastify adapter).
- **NestJS modules** — Each concern (chat, brain, agent, auth, queue, memory, plugins) is a module with clear boundaries
@@ -257,6 +258,7 @@ The central nervous system. All clients connect here. Built with NestJS (Fastify
- **Auth middleware** — BetterAuth session validation, RBAC enforcement
Key routes:
```
POST /api/chat Send message, get streamed response
GET /api/conversations List conversations
@@ -287,6 +289,7 @@ GET /mcp MCP endpoint (streamable HTTP)
```
#### `apps/web` — Next.js Web Dashboard
Carried forward from jarvis-old with significant refactoring.
- Chat/conversation UI (primary interaction surface)
@@ -301,7 +304,9 @@ Carried forward from jarvis-old with significant refactoring.
- Auth pages (login, SSO redirect, registration)
#### `packages/types` — @mosaic/types
Migrated from mosaic-mono-v0. Extended with:
- Gateway types (routing, dispatch, agent pool)
- Auth types (user, role, permission)
- Conversation/message types (from jarvis-old domain)
@@ -309,7 +314,9 @@ Migrated from mosaic-mono-v0. Extended with:
- Plugin channel types (Discord, Telegram message mapping)
#### `packages/brain` — @mosaic/brain
Migrated from mosaic-mono-v0. **Storage backend changes from JSON to PostgreSQL.**
- REST API preserved (mounted as gateway sub-router or standalone)
- MCP tools preserved
- Collections layer rewritten to use Drizzle ORM queries instead of JSON file I/O
@@ -318,13 +325,17 @@ Migrated from mosaic-mono-v0. **Storage backend changes from JSON to PostgreSQL.
- New: appreciation collection preserved for family use
#### `packages/queue` — @mosaic/queue
Migrated from mosaic-mono-v0 with minimal changes.
- Valkey-backed task queue with atomic WATCH/MULTI/EXEC
- MCP server with 8 tools
- Used by gateway for agent task dispatch and coordination
#### `packages/coord` — @mosaic/coord
Migrated from mosaic-mono-v0.
- Mission lifecycle: init, run, resume, status, drain
- TASKS.md parsing and management
- Session lock management
@@ -332,14 +343,18 @@ Migrated from mosaic-mono-v0.
- Integration with gateway for mission-driven orchestration
#### `packages/db` — @mosaic/db (NEW)
Shared database package.
- Drizzle ORM schema definitions (all tables)
- Migration management
- Connection pool configuration
- Shared by gateway, brain, auth, memory
#### `packages/auth` — @mosaic/auth (NEW)
Authentication and authorization.
- BetterAuth configuration
- SSO adapters: Authentik, WorkOS, Keycloak
- RBAC: roles (admin, member, viewer), permissions
@@ -347,7 +362,9 @@ Authentication and authorization.
- Session management middleware
#### `packages/agent` — @mosaic/agent (NEW — critical path)
Pi SDK integration layer.
- Agent pool manager — spawns and manages Pi agent sessions
- Provider configuration — Anthropic, Codex, Z.ai, Ollama, LM Studio, llama.cpp
- Agent routing logic — selects provider/model based on task characteristics
@@ -356,7 +373,9 @@ Pi SDK integration layer.
- Session lifecycle — create, monitor, complete, fail, timeout
#### `packages/memory` — @mosaic/memory (NEW)
Tiered memory system.
- Preference store — learned user preferences, behaviors, defaults (PG)
- Insight store — distilled knowledge from agent interactions (PG + vector)
- Semantic search — query across memory using pgvector embeddings
@@ -364,7 +383,9 @@ Tiered memory system.
- Memory API — used by gateway and agent sessions
#### `packages/log` — @mosaic/log (NEW)
Agent log service.
- Log ingest — receives structured logs from agent sessions
- Log parsing — extracts decisions, learnings, tool usage patterns
- Tiered storage — hot (recent, full detail), warm (summarized), cold (archived)
@@ -372,31 +393,41 @@ Agent log service.
- Retention policy — configurable TTLs per tier
#### `packages/mosaic` — @mosaic/mosaic
Migrated from mosaic-mono-v0, updated for v1.
- Install wizard for Mosaic Stack setup
- Detects existing installations, offers upgrade path
- Configures `~/.config/mosaic/` with guides, tools, runtime configs
#### `packages/prdy` — @mosaic/prdy
Migrated from mosaic-mono-v0.
- PRD generation wizard
- Template-based PRD creation with Zod validation
- CLI integration via `mosaic prdy`
#### `packages/quality-rails` — @mosaic/quality-rails
Migrated from mosaic-mono-v0.
- TypeScript scaffolder for project quality config
- Generates ESLint, tsconfig, Woodpecker, husky, lint-staged configs
- Supports project types: monorepo, typescript-node, nextjs
#### `packages/cli` — @mosaic/cli
Migrated from mosaic-mono-v0, extended.
- Unified `mosaic` binary
- Subcommands: `mosaic coord`, `mosaic prdy`, `mosaic queue`, `mosaic quality`, `mosaic gateway`, `mosaic brain`
- Plugin discovery for installed @mosaic/* packages
- Plugin discovery for installed @mosaic/\* packages
#### `plugins/discord` — @mosaic/discord-plugin (NEW — high priority)
Discord remote control channel. Architecture inspired by OpenClaw (https://github.com/openclaw/openclaw).
- Channel plugin that registers with the gateway as a NestJS dynamic module
- Single-guild binding only (v0.1.0) — prevents data leaks between servers
- Receives Discord messages, dispatches through gateway routing
@@ -406,7 +437,9 @@ Discord remote control channel. Architecture inspired by OpenClaw (https://githu
- DM support for private conversations
#### `plugins/telegram` — @mosaic/telegram-plugin (NEW)
Telegram remote control channel.
- Same channel plugin pattern as Discord
- Telegraf-based bot
- Message routing through gateway
@@ -417,42 +450,55 @@ Telegram remote control channel.
## User/Stakeholder Requirements
### US-001 Multi-Channel Chat
**As a user**, I can chat with an AI assistant via web browser, terminal (Pi TUI), Discord, or Telegram and get consistent responses regardless of channel.
### US-002 Task & Project Dashboard
**As a user**, I can manage my tasks, projects, and missions from the web dashboard with kanban and list views.
### US-003 PRD Management
**As a user**, I can view and edit PRDs for active missions from the web dashboard.
### US-004 Agent Visibility
**As a user**, I can see which agents are active, what they're working on, and their status in real-time.
### US-005 Provider Configuration
**As a user**, I can configure which LLM providers to use and set routing preferences (cost vs capability).
### US-006 Skill Management
**As a user**, I can install and manage agent skills through the web dashboard.
### US-007 Persistent Memory
**As a user**, the system remembers my preferences, learned behaviors, and past decisions across sessions.
### US-008 Semantic Search
**As a user**, I can search across my memory, conversations, and knowledge semantically.
### US-009 User Management
**As an admin**, I can manage users, assign roles, and control access.
### US-010 SSO Configuration
**As an admin**, I can configure SSO via Authentik, WorkOS, or Keycloak.
### US-011 Self-Hosted Deployment
**As a user**, I can run Mosaic Stack via Docker Compose or directly on bare metal.
### US-012 Intelligent Routing
**As an agent operator**, the gateway intelligently routes tasks to the cheapest capable model.
### US-013 CLI Tooling
**As a user**, I can use the `mosaic` CLI for PRD creation, quality rail setup, queue management, and mission coordination.
---
@@ -482,6 +528,7 @@ Telegram remote control channel.
- FR-21: Skill Import from skills.sh
### FR-1: Chat System
- Conversation CRUD (create, list, get with messages, delete)
- Real-time streaming responses via WebSocket
- Multi-provider support (route to configured LLM)
@@ -491,6 +538,7 @@ Telegram remote control channel.
- Message rendering with markdown, code blocks, tool call display
### FR-2: Gateway Orchestrator
- Central API surface for all clients (web, TUI, Discord, Telegram)
- Agent dispatch — receive task, select provider/model, spawn Pi session, return result
- Routing engine — cost/capability matrix, user preference overrides, task-type heuristics
@@ -500,6 +548,7 @@ Telegram remote control channel.
- Rate limiting and request validation
### FR-3: Agent Pool (@mosaic/agent)
- Manage concurrent Pi SDK sessions
- Provider configuration: API key management, endpoint URLs, model lists
- Support providers: Anthropic (subscription + API), OpenAI/Codex (subscription + API), Z.ai, Ollama (local), LM Studio (local), llama.cpp (local)
@@ -509,6 +558,7 @@ Telegram remote control channel.
- Graceful shutdown — drain active sessions on shutdown
### FR-4: Task Management
- Brain-backed task CRUD with full filter/sort
- Task statuses: backlog, scheduled, in-progress, blocked, done, cancelled
- Priority levels: critical, high, medium, low
@@ -520,6 +570,7 @@ Telegram remote control channel.
- Due date tracking with stale detection
### FR-5: Project Management
- Project CRUD with domain, status, priority
- Link to repository, branch, current/next milestone
- Progress tracking
@@ -527,6 +578,7 @@ Telegram remote control channel.
- Owner assignment
### FR-6: Mission System
- Mission CRUD (linked to project and PRD)
- Mission tasks with phases, dependencies, ordering
- Mission summary with computed progress
@@ -534,6 +586,7 @@ Telegram remote control channel.
- Active mission dashboard in web UI
### FR-7: Memory System
- **Preferences**: Key-value store for learned user preferences (e.g., "prefers tables over paragraphs", "timezone: America/Chicago")
- **Insights**: Distilled knowledge from agent interactions, stored with embeddings
- **Semantic search**: Query across all memory using natural language
@@ -542,6 +595,7 @@ Telegram remote control channel.
- **Decay**: Old, unused insights decay in relevance score over time
### FR-8: Authentication & Authorization
- BetterAuth integration with Next.js
- Email/password registration and login
- SSO via OIDC/SAML: Authentik, WorkOS, Keycloak
@@ -550,6 +604,7 @@ Telegram remote control channel.
- Session management (web + API)
### FR-9: Remote Control — Discord
- Discord bot that connects to the gateway
- Mention-based activation in channels
- DM support for private conversations
@@ -559,6 +614,7 @@ Telegram remote control channel.
- Permission management (which Discord users/roles can interact)
### FR-10: Remote Control — Telegram
- Telegram bot via Telegraf
- Private and group chat support
- Command-based interaction (`/ask`, `/task`, `/status`)
@@ -566,6 +622,7 @@ Telegram remote control channel.
- Message routing through gateway
### FR-11: LLM Provider Management
- Provider configuration UI in web dashboard
- Per-provider: API key/endpoint, enabled models, cost per token
- Subscription-based providers: detect available models from subscription
@@ -574,6 +631,7 @@ Telegram remote control channel.
- Usage tracking per provider/model
### FR-12: Agent Routing
- Task-type to model-tier mapping (from AGENTS.md cost matrix)
- User preference overrides (e.g., "always use Claude for code review")
- Fallback chains (if primary provider unavailable, try next)
@@ -581,6 +639,7 @@ Telegram remote control channel.
- Routing transparency — user can see why a particular model was chosen
### FR-13: MCP Capability
- Gateway exposes MCP server (streamable HTTP transport)
- Brain tools registered as MCP tools
- Queue tools registered as MCP tools
@@ -589,6 +648,7 @@ Telegram remote control channel.
- External MCP server connectivity (agent can use third-party MCP servers)
### FR-14: Skill Management
- Skill catalog — list available skills from configured sources
- Skill install — install skill to `~/.config/mosaic/skills/` or project-local
- Skill configuration — per-skill settings
@@ -596,6 +656,7 @@ Telegram remote control channel.
- Web UI for browsing and managing skills
### FR-15: CLI Integration
- `mosaic gateway start` — start the gateway server
- `mosaic brain` — brain data management
- `mosaic queue` — queue operations
@@ -605,6 +666,7 @@ Telegram remote control channel.
- `mosaic tui` — launch Pi TUI connected to gateway
### FR-16: Log Service
- Structured log ingest from agent sessions
- Parse logs for: decisions made, tools used, errors encountered, learnings captured
- Tier management: hot (7 days, full detail), warm (30 days, summarized), cold (90 days, key facts only)
@@ -612,12 +674,14 @@ Telegram remote control channel.
- Query interface for log search
### FR-17: Gateway State Persistence
- Orchestration state persisted to Valkey (active sessions, pending dispatches, routing context)
- On restart, gateway reads Valkey state and resumes — reconnects to active agent sessions
- `mosaic gateway restart --fresh` clears Valkey queue and all in-flight state (nuclear option)
- Session recovery: detect orphaned agent sessions, offer reconnect or cleanup
### FR-18: Multi-Session Agent Architecture
- Each agent has a distinct session with dedicated context
- Multiple input channels (TUI, web, Discord, Telegram) can connect to same agent session
- Channel multiplexing at gateway level with proper authorization
@@ -627,6 +691,7 @@ Telegram remote control channel.
- `mosaic agent list` shows active sessions with connected channels
### FR-19: Cron Scheduler
- Built-in cron scheduler in gateway for recurring tasks
- Default schedules: log summarization, stale task detection, memory decay, provider health checks
- Custom schedules: user-defined agent dispatches on cron expressions
@@ -635,12 +700,14 @@ Telegram remote control channel.
- Persistence: schedules stored in PG, survive gateway restart
### FR-20: Web Search Tool
- DuckDuckGo web search via MCP server (primary — privacy-respecting, no API key)
- Registered as standard MCP tool available to all agent sessions
- Configurable: can swap to other search providers (Brave, SearXNG, Tavily)
- Results formatted for agent consumption (title, snippet, URL)
### FR-21: Skill Import from skills.sh
- Browse skills from https://skills.sh directory via API
- Import skills into `~/.config/mosaic/skills/` or project-local `.mosaic/skills/`
- Vetting workflow: imported skills marked as "unvetted" until admin approves
@@ -654,6 +721,7 @@ Telegram remote control channel.
## Non-Functional Requirements
### Security
- No hardcoded secrets — all secrets via environment variables or vault
- API key rotation capability
- RBAC enforcement at gateway level
@@ -665,6 +733,7 @@ Telegram remote control channel.
- Database connection encryption (SSL)
### Performance
- Chat response streaming latency < 200ms TTFB (gateway overhead, not LLM latency)
- Dashboard page loads < 2s
- Brain query responses < 100ms for filtered reads
@@ -673,6 +742,7 @@ Telegram remote control channel.
- WebSocket connection handling for 50+ concurrent users
### Reliability
- Graceful degradation when LLM provider is unavailable (fallback chain)
- Queue persistence — tasks survive gateway restart
- Database connection pooling with retry
@@ -680,6 +750,7 @@ Telegram remote control channel.
- Structured error responses with correlation IDs
### Observability (Wide-Event Logging — Required from Phase 0)
- **OpenTelemetry instrumentation** across all services from day one
- `@opentelemetry/sdk-node` + `@opentelemetry/auto-instrumentations-node` for auto-instrumentation (HTTP, PG, Fastify/NestJS)
- NestJS interceptors for custom spans on agent dispatch, routing decisions, memory writes, summarization runs
@@ -693,6 +764,7 @@ Telegram remote control channel.
- Migrate to Grafana stack (Tempo + Loki + Grafana) post-beta if more customization is needed
### Scalability (Multi-Tier Readiness)
- Single-node deployment is the MVP target for v0.1.0
- Code structured with assumption that multi-tiered deployment will follow: dedicated gateway nodes, agent worker nodes, brain/DB nodes
- Service boundaries communicate via HTTP/WS/MCP APIs, not in-process calls where avoidable
@@ -706,63 +778,74 @@ Telegram remote control channel.
## Acceptance Criteria
### AC-1: Core Chat Flow
- [ ] User can log in via web UI, send a message, and receive a streamed response
- [ ] Conversation persists across page refreshes
- [ ] User can create, list, search, and delete conversations
- [ ] Conversations can be scoped to projects
### AC-2: TUI Integration
- [ ] `mosaic tui` launches Pi interactive mode connected to gateway
- [ ] User can chat with same conversation context as web UI
- [ ] Agent has access to brain, queue, and memory tools
### AC-3: Discord Remote Control
- [ ] Discord bot connects and responds to mentions
- [ ] Messages route through gateway to agent pool
- [ ] Responses stream back to Discord (chunked)
- [ ] Thread creation for multi-turn conversations
### AC-4: Gateway Orchestration
- [ ] Gateway dispatches tasks to appropriate provider/model
- [ ] Routing decision logged and inspectable
- [ ] Fallback when primary provider unavailable
- [ ] Multiple concurrent agent sessions managed correctly
### AC-5: Task & Project Management
- [ ] CRUD operations for tasks, projects, missions via web dashboard
- [ ] Kanban board view for tasks
- [ ] Mission progress tracking with computed stats
- [ ] Brain MCP tools accessible from agent sessions
### AC-6: Memory System
- [ ] Agent sessions auto-capture decisions and learnings
- [ ] Semantic search returns relevant past context
- [ ] Learned preferences are applied in new sessions
- [ ] Log summarization runs on schedule, old logs compressed
### AC-7: Authentication & RBAC
- [ ] Email/password login works
- [ ] At least one SSO provider (Authentik) works end-to-end
- [ ] Admin can create users and assign roles
- [ ] RBAC enforced on API endpoints
### AC-8: Multi-Provider LLM Support
- [ ] At least 3 providers configured and routing correctly (e.g., Anthropic + Ollama + Z.ai)
- [ ] Agent routing selects appropriate model for task type
- [ ] Provider configuration manageable from web UI
### AC-9: MCP
- [ ] Gateway exposes MCP endpoint
- [ ] Brain and queue tools callable via MCP
- [ ] Agent sessions can connect to external MCP servers
### AC-10: Deployment
- [ ] `docker compose up` starts full stack from clean state
- [ ] `mosaic` CLI installable and functional on bare metal
- [ ] Database migrations run automatically on first start
- [ ] `.env.example` documents all required configuration
### AC-11: @mosaic/* Packages
### AC-11: @mosaic/\* Packages
- [ ] All 7 migrated packages build, pass tests, and integrate with gateway
- [ ] `mosaic` CLI provides subcommands for each package
- [ ] Types package is the single source of shared interfaces
@@ -785,27 +868,27 @@ Telegram remote control channel.
### Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Pi SDK API instability (pre-1.0) | Medium | High | Pin version, abstract behind @mosaic/agent interface |
| Brain PG migration complexity | Medium | Medium | Preserve Brain REST/MCP API contract; only storage changes |
| Discord plugin complexity (OpenClaw has ~60 files) | Medium | Medium | Start minimal (DM + mention in channel), single-guild only; expand iteratively post-beta |
| LLM provider subscription auth varies by provider | Medium | Medium | Abstract behind provider interface; implement per-provider adapters |
| Drizzle + pgvector extension compatibility | Low | Medium | Validate in Phase 0 with spike |
| Agent log volume overwhelming storage | Medium | High | Tiered storage with aggressive summarization; configurable retention |
| Scope creep from jarvis-old feature surface | High | High | Strict v0.1.0 scope; features not listed above are post-beta |
| Risk | Likelihood | Impact | Mitigation |
| -------------------------------------------------- | ---------- | ------ | ---------------------------------------------------------------------------------------- |
| Pi SDK API instability (pre-1.0) | Medium | High | Pin version, abstract behind @mosaic/agent interface |
| Brain PG migration complexity | Medium | Medium | Preserve Brain REST/MCP API contract; only storage changes |
| Discord plugin complexity (OpenClaw has ~60 files) | Medium | Medium | Start minimal (DM + mention in channel), single-guild only; expand iteratively post-beta |
| LLM provider subscription auth varies by provider | Medium | Medium | Abstract behind provider interface; implement per-provider adapters |
| Drizzle + pgvector extension compatibility | Low | Medium | Validate in Phase 0 with spike |
| Agent log volume overwhelming storage | Medium | High | Tiered storage with aggressive summarization; configurable retention |
| Scope creep from jarvis-old feature surface | High | High | Strict v0.1.0 scope; features not listed above are post-beta |
### Open Questions
| # | Question | Priority | Status |
|---|----------|----------|--------|
| 1 | Pi SDK version to pin for v0.1.0? | High | ✅ Resolved — Pin `@mariozechner/pi-coding-agent@~0.57.1` (current stable). Abstract behind `@mosaic/agent` interface to insulate from breaking changes. Bump deliberately after testing. |
| 2 | Authentik vs WorkOS vs Keycloak — which SSO provider to implement first? | Medium | ✅ Resolved — Authentik first (already in Jason's infrastructure) |
| 3 | Vector DB: pgvector sufficient or need Qdrant from the start? | Medium | ✅ Resolved — pgvector with VectorStore interface abstraction. Qdrant drops in later if needed. |
| 4 | Summarization LLM: which model for log compression? | Medium | ✅ Resolved — Haiku-tier default with structured output guardrails, configurable via routing engine. |
| 5 | LM Studio and llama.cpp — provider adapters exist in Pi or need custom? | Medium | ✅ Resolved — Pi handles both natively. LM Studio and llama.cpp (server mode) expose OpenAI-compatible APIs; configure via Pi's `models.json` with `openai-completions` API type. No custom adapters needed. |
| 6 | Discord bot — single guild or multi-guild from day one? | Medium | ✅ Resolved — Single-guild only for v0.1.0 to prevent data leaks. Bot binds to one guild. Multi-guild with tenant isolation is a post-beta feature requiring explicit data boundary design. |
| 7 | Bare-metal install — systemd units or just docs? | Low | ASSUMPTION: Docs + CLI launch commands; systemd units post-beta |
| # | Question | Priority | Status |
| --- | ------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | Pi SDK version to pin for v0.1.0? | High | ✅ Resolved — Pin `@mariozechner/pi-coding-agent@~0.57.1` (current stable). Abstract behind `@mosaic/agent` interface to insulate from breaking changes. Bump deliberately after testing. |
| 2 | Authentik vs WorkOS vs Keycloak — which SSO provider to implement first? | Medium | ✅ Resolved — Authentik first (already in Jason's infrastructure) |
| 3 | Vector DB: pgvector sufficient or need Qdrant from the start? | Medium | ✅ Resolved — pgvector with VectorStore interface abstraction. Qdrant drops in later if needed. |
| 4 | Summarization LLM: which model for log compression? | Medium | ✅ Resolved — Haiku-tier default with structured output guardrails, configurable via routing engine. |
| 5 | LM Studio and llama.cpp — provider adapters exist in Pi or need custom? | Medium | ✅ Resolved — Pi handles both natively. LM Studio and llama.cpp (server mode) expose OpenAI-compatible APIs; configure via Pi's `models.json` with `openai-completions` API type. No custom adapters needed. |
| 6 | Discord bot — single guild or multi-guild from day one? | Medium | ✅ Resolved — Single-guild only for v0.1.0 to prevent data leaks. Bot binds to one guild. Multi-guild with tenant isolation is a post-beta feature requiring explicit data boundary design. |
| 7 | Bare-metal install — systemd units or just docs? | Low | ASSUMPTION: Docs + CLI launch commands; systemd units post-beta |
---
@@ -825,6 +908,7 @@ Telegram remote control channel.
All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
### Phase 0: Foundation (v0.0.1)
- Scaffold monorepo (pnpm + turbo + tsconfig + eslint + vitest)
- `@mosaic/types` — migrate and extend from v0
- `@mosaic/db` — Drizzle schema, PG connection, migrations
@@ -835,6 +919,7 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
- AGENTS.md, CLAUDE.md, README.md
### Phase 1: Core API (v0.0.2)
- `apps/gateway` — NestJS server (Fastify adapter), auth middleware, health endpoints
- `@mosaic/brain` — migrate from v0, swap JSON store for PG via @mosaic/db
- `@mosaic/queue` — migrate from v0 (minimal changes)
@@ -843,6 +928,7 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
- Basic agent dispatch (single provider, no routing)
### Phase 2: Agent Layer (v0.0.3)
- `@mosaic/agent` — Pi SDK integration, agent pool manager
- Multi-provider support (Anthropic + Ollama minimum)
- Agent routing engine (cost/capability matrix)
@@ -850,6 +936,7 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
- `@mosaic/coord` — migrate from v0, integrate with gateway
### Phase 3: Web Dashboard (v0.0.4)
- `apps/web` — Next.js app with BetterAuth
- Chat UI (conversation list, message display, streaming input)
- Task management (list + kanban)
@@ -858,6 +945,7 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
- Admin panel (user management, RBAC)
### Phase 4: Memory & Intelligence (v0.0.5)
- `@mosaic/memory` — preference store, insight store, semantic search
- `@mosaic/log` — log ingest, parsing, tiered storage
- Summarization pipeline
@@ -865,12 +953,14 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
- Skill management interface (web UI + CLI)
### Phase 5: Remote Control (v0.0.6)
- `@mosaic/discord-plugin` — Discord channel plugin
- `@mosaic/telegram-plugin` — Telegram channel plugin
- Plugin host in gateway
- SSO configuration (Authentik)
### Phase 6: CLI & Tools (v0.0.7)
- `@mosaic/cli` — unified CLI with all subcommands
- `@mosaic/prdy` — migrate from v0
- `@mosaic/quality-rails` — migrate from v0
@@ -878,6 +968,7 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
- Pi TUI integration (`mosaic tui`)
### Phase 7: Polish & Beta (v0.0.8 → v0.1.0)
- MCP endpoint hardening
- Additional SSO providers (WorkOS/Keycloak)
- Additional LLM providers (Codex, Z.ai, LM Studio, llama.cpp)