183 lines
8.8 KiB
Markdown
183 lines
8.8 KiB
Markdown
# 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)
|