mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
156ea1438b5f3064f9b3fde9634eb61b52a10400
stack/docs/PRD.md

6.8 KiB
Raw Blame History

PRD: MS22 Phase 2 — Named Agent Fleet

Metadata

  • Owner: Jason Woltje
  • Date: 2026-03-04
  • Status: in-progress
  • Mission: ms22-p2-named-agent-fleet-20260304
  • Design Doc: docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md
  • Depends On: MS22 Phase 1 (DB-Centric Architecture) — COMPLETE

Problem Statement

Mosaic Stack has the infrastructure for per-user containers and a knowledge layer, but no predefined agent personalities. Users start with a blank slate. For Jason's personal use case, the system needs named agents — jarvis, builder, medic — with distinct roles, personalities, and tool access that can collaborate through the shared knowledge layer and respond in dedicated Discord channels.

Currently:

  • No agent registry exists in the database
  • No per-agent model configuration is possible
  • Discord channels are not routed to specific agents
  • Chat routing is model-agnostic (no agent context)

Scope

In Scope

  • AgentTemplate and UserAgent Prisma models
  • Admin CRUD endpoints for managing agent templates
  • User agent CRUD endpoints for personal agent instances
  • Agent chat proxy routing (select agent by name)
  • Discord channel → agent routing (#jarvis, #builder, #medic-alerts)
  • WebUI agent selector and agent detail view
  • Unit tests and E2E verification

Non-Goals

  • Matrix observation rooms
  • Cross-agent quality gates
  • Team/multi-user agent sharing
  • Agent-to-agent communication
  • Token metering per agent

User Stories

US-001

As Jason, I can list my available agents in the WebUI so I know what's configured.

US-002

As Jason, I can select an agent and chat with it directly via WebUI.

US-003

As Jason, I can send a message in #jarvis on Discord and Jarvis responds.

US-004

As Jason, I can send a message in #builder on Discord and Builder responds.

US-005

As Jason, I can send a message in #medic-alerts and Medic responds.

US-006

As an admin, I can create, update, and delete agent templates.

US-007

As Jason, I can customize an agent's personality without affecting the shared template.

US-008

As Jason, I can see which agents are active vs inactive at a glance.

Functional Requirements

  • FR-1: The system SHALL provide an AgentTemplate model with: name, displayName, role, personality, primaryModel, fallbackModels, toolPermissions, discordChannel, isActive, isDefault
  • FR-2: The system SHALL provide a UserAgent model that extends or customizes an AgentTemplate per user
  • FR-3: The system SHALL seed three default templates on startup: jarvis (orchestrator/opus), builder (coding/codex), medic (monitoring/haiku)
  • FR-4: Admin endpoints SHALL exist at GET/POST/PATCH/DELETE /admin/agent-templates protected by AdminGuard
  • FR-5: User agent endpoints SHALL exist at GET/POST/PATCH/DELETE /agents protected by AuthGuard
  • FR-6: Agent status endpoints SHALL return active/inactive state per agent for the authenticated user
  • FR-7: The chat proxy SHALL route messages to the correct agent based on agent name or ID in the request
  • FR-8: Incoming Discord messages in a configured channel SHALL be routed to the matching agent
  • FR-9: The WebUI SHALL display a list of available agents with role, model, and status
  • FR-10: The WebUI SHALL allow selecting an agent and opening a chat session with it

Non-Functional Requirements

  • All API endpoints must pass NestJS ValidationPipe (value imports for DTOs, not import type)
  • All new modules must be registered in app.module.ts
  • Prisma schema changes must include a migration file
  • Code must pass pnpm turbo run lint typecheck build before merge
  • Tests must pass pnpm turbo run test with no regressions
  • No direct pushes to main — PR + squash merge only

Acceptance Criteria

  • AgentTemplate and UserAgent tables exist in production DB after migration
  • GET /admin/agent-templates returns jarvis, builder, medic (seeded)
  • POST /admin/agent-templates creates a new template (admin only, 403 for non-admin)
  • GET /agents returns the authenticated user's agents
  • POST /agents creates a user agent from a template
  • GET /agents/:id/chat proxies to the correct agent
  • Discord message in #jarvis channel routes to jarvis agent and responds
  • Discord message in #builder channel routes to builder agent and responds
  • WebUI shows agent list with name, role, model, status
  • WebUI allows selecting an agent and sending a message
  • All CI checks green on main after final PR merge

Technical Considerations

  • DTOs must use value imports (never import type) for NestJS ValidationPipe compatibility — see MEMORY.md
  • AgentTemplate.fallbackModels and toolPermissions are stored as Json (Prisma) — treat as string[] in TypeScript
  • Discord routing requires mapping discordChannel string to a channel ID in OpenClaw config
  • Chat proxy must be stateless — agent selection passed per-request
  • Use AdminGuard from src/auth/guards/admin.guard for admin endpoints (existing pattern)
  • Use AuthGuard from src/auth/guards/auth.guard for user endpoints (existing pattern)

Risks / Open Questions

Risk Likelihood Mitigation
Discord channel ID mapping not yet configured in OpenClaw Medium Manual config step; document in MISSION-MANIFEST
Agent routing adds latency to chat proxy Low Agent lookup is a single DB read; cache if needed
exactOptionalPropertyTypes TS strictness on Prisma creates Medium Use conditional spread for optional fields
Seed idempotency failure (duplicate name) Low Use upsert — already implemented

Success Metrics / Testing

  • Unit tests cover: AgentTemplateService CRUD, UserAgentService CRUD, chat routing logic
  • E2E test: send Discord message in #jarvis → verify response comes from jarvis agent
  • Manual smoke test: WebUI agent selector loads, chat works with selected agent
  • CI pipeline green on all three apps (api, web, orchestrator)

Milestones / Delivery

Milestone Tasks Status Target
M1: Schema + Seed P2-001, P2-002 ✅ done (PR #675, #677) 2026-03-04
M2: Admin CRUD P2-003 ✅ done (PR #678) 2026-03-04
M3: User CRUD P2-004 ⬜ next 2026-03-05
M4: Agent Routing P2-005, P2-006 ⬜ pending 2026-03-05
M5: Discord + UI P2-007, P2-008 ⬜ pending 2026-03-06
M6: Verification P2-009, P2-010 ⬜ pending 2026-03-06
Reference in New Issue View Git Blame Copy Permalink