# 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

```prisma
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)
