stack/docs/PRD-MS22-P2-AGENT-FLEET.md

PRD: MS22 Phase 2 — Named Agent Fleet

Metadata

• Owner: Jason Woltje
• Date: 2026-03-04
• Status: draft
• Design Doc: ~/src/jarvis-brain/docs/planning/FLEET-EVOLUTION-PLAN.md
• Depends On: MS22 Phase 1 (DB-Centric Architecture) — COMPLETE

Problem Statement

Mosaic Stack has the infrastructure for per-user containers and knowledge layer, but no predefined agent personalities. Users start with a blank slate. For Jason's personal use case, we need named agents with distinct roles, personalities, and tool access that can collaborate through the shared knowledge layer.

Objectives

1. Named agents — jarvis (orchestrator), builder (coding), medic (monitoring)
2. Per-agent model assignment — Opus for jarvis, Codex for builder, Haiku for medic
3. Tool permissions — Restrict dangerous tools to appropriate agents
4. Discord bindings — Route agents to specific channels
5. Mosaic skill — All agents can read/write findings and memory

Scope

In Scope

• Agent personality definitions (SOUL.md for each)
• Agent registry in Mosaic DB
• Per-agent model configuration
• Per-agent tool permission sets
• Discord channel routing
• Default agent templates for new users

Out of Scope

• Matrix observation rooms (nice-to-have)
• WebUI chat improvements (separate phase)
• Cross-agent quality gates (future)
• Team workspaces (future)

Agent Definitions

Jarvis — Orchestrator

Property	Value
Role	Main orchestrator, user-facing assistant
Model	Opus (primary), Sonnet (fallback)
Tools	All tools — full access
Discord	#jarvis
Personality	Capable, direct, proactive. Gets stuff done without hand-holding. Thinks before acting, speaks up when seeing a better way. NOT a yes-man.

Builder — Coding Agent

Property	Value
Role	Code implementation, PRs, refactoring
Model	Codex (primary, uses OpenAI credits), Sonnet (fallback)
Tools	exec, read, write, edit, github, browser
Discord	#builder
Personality	Focused, thorough. Writes clean code. Tests before declaring done. Documents decisions.

Medic — Health Monitoring

Property	Value
Role	System health checks, alerts, monitoring
Model	Haiku (primary), MiniMax (fallback)
Tools	exec (SSH), nodes, cron, message (alerts only)
Discord	#medic-alerts
Personality	Vigilant, concise. Alerts on anomalies. Proactive health checks. Minimal noise.

Database Schema

model AgentTemplate {
  id          String   @id @default(cuid())
  name        String   @unique        // "jarvis", "builder", "medic"
  displayName String                   // "Jarvis", "Builder", "Medic"
  role        String                   // "orchestrator" | "coding" | "monitoring"
  personality String                   // SOUL.md content
  primaryModel String                  // "opus", "codex", "haiku"
  fallbackModels Json @default("[]")   // ["sonnet", "haiku"]
  toolPermissions Json @default("[]")  // ["exec", "read", "write", ...]
  discordChannel String?               // "jarvis", "builder", "medic-alerts"
  isActive    Boolean  @default(true)
  isDefault   Boolean  @default(false) // Include in new user provisioning
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model UserAgent {
  id           String   @id @default(cuid())
  userId       String
  templateId   String?  // null = custom agent
  name         String   // "jarvis", "builder", "medic" or custom
  displayName  String
  role         String
  personality  String   // User can customize
  primaryModel String?
  fallbackModels Json @default("[]")
  toolPermissions Json @default("[]")
  discordChannel String?
  isActive     Boolean  @default(true)
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  @@unique([userId, name])
}

API Endpoints

Agent Templates (Admin)

GET    /api/admin/agent-templates        — List all templates
POST   /api/admin/agent-templates        — Create template
GET    /api/admin/agent-templates/:id    — Get template
PATCH  /api/admin/agent-templates/:id    — Update template
DELETE /api/admin/agent-templates/:id    — Delete template

User Agents

GET    /api/agents                       — List user's agents
POST   /api/agents                       — Create custom agent (or from template)
GET    /api/agents/:id                   — Get agent details
PATCH  /api/agents/:id                   — Update agent (personality, model)
DELETE /api/agents/:id                   — Delete custom agent
POST   /api/agents/:id/chat              — Chat with agent (proxy to container)

Agent Status

GET    /api/agents/status                — All agents status for user
GET    /api/agents/:id/status            — Single agent status

Task Breakdown

Task ID	Phase	Description	Scope	Dependencies	Estimate
P2-DB-001	schema	Prisma models: AgentTemplate, UserAgent	api	P1a	10K
P2-SEED-001	seed	Seed default agents (jarvis, builder, medic)	api	P2-DB-001	5K
P2-API-001	api	Agent template CRUD endpoints	api	P2-DB-001	15K
P2-API-002	api	User agent CRUD endpoints	api	P2-DB-001	15K
P2-API-003	api	Agent status endpoints	api	P2-DB-001	10K
P2-PROXY-001	api	Agent chat routing (select agent by name)	api	P2-API-002	15K
P2-DISCORD-001	discord	Route Discord messages to correct agent	api	P2-PROXY-001	15K
P2-UI-001	web	Agent list/selector in WebUI	web	P2-API-002	15K
P2-UI-002	web	Agent detail/edit page	web	P2-UI-001	15K
P2-TEST-001	test	Unit tests for agent services	api	P2-API-002	15K
P2-VER-001	verify	End-to-end: Discord → correct agent → response	stack	all	10K

Total Estimate: ~140K tokens

Success Criteria

1. ✅ User can list available agents in WebUI
2. ✅ User can select agent and chat with it
3. ✅ Discord messages in #jarvis go to jarvis agent
4. ✅ Discord messages in #builder go to builder agent
5. ✅ Each agent uses its assigned model
6. ✅ Each agent has correct tool permissions
7. ✅ Agents can read/write findings via mosaic skill

Risks

Risk	Mitigation
Agent routing complexity	Keep it simple: map Discord channel → agent name
Tool permission enforcement	OpenClaw config generation respects permissions
Model fallback failures	Log and alert, don't block user

Next Steps

1. Review this PRD with Jason
2. Create Mission MS22-P2 in TASKS.md
3. Begin with P2-DB-001 (schema)