# 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 |
