Merge pull request 'docs(ms22): add Phase 2 PRD and TASKS for Named Agent Fleet' (#673) from docs/ms22-p2-agent-fleet-prd into main
This commit was merged in pull request #673.
This commit is contained in:
182
docs/PRD-MS22-P2-AGENT-FLEET.md
Normal file
182
docs/PRD-MS22-P2-AGENT-FLEET.md
Normal file
@@ -0,0 +1,182 @@
|
|||||||
|
# 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)
|
||||||
@@ -89,3 +89,20 @@ Design doc: `docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md`
|
|||||||
| MS22-P1i | done | phase-1i | Chat proxy: route WebUI chat to user's OpenClaw container (SSE) | — | api+web | feat/ms22-p1i-chat-proxy | P1c,P1d | — | — | — | — | 20K | — | |
|
| MS22-P1i | done | phase-1i | Chat proxy: route WebUI chat to user's OpenClaw container (SSE) | — | api+web | feat/ms22-p1i-chat-proxy | P1c,P1d | — | — | — | — | 20K | — | |
|
||||||
| MS22-P1j | done | phase-1j | Docker entrypoint + health checks + core compose | — | docker | feat/ms22-p1j-docker | P1c | — | — | — | — | 10K | — | |
|
| MS22-P1j | done | phase-1j | Docker entrypoint + health checks + core compose | — | docker | feat/ms22-p1j-docker | P1c | — | — | — | — | 10K | — | |
|
||||||
| MS22-P1k | done | phase-1k | Idle reaper cron: stop inactive user containers | — | api | feat/ms22-p1k-idle-reaper | P1d | — | — | — | — | 10K | — | |
|
| MS22-P1k | done | phase-1k | Idle reaper cron: stop inactive user containers | — | api | feat/ms22-p1k-idle-reaper | P1d | — | — | — | — | 10K | — | |
|
||||||
|
|
||||||
|
## MS22 Phase 2: Named Agent Fleet
|
||||||
|
|
||||||
|
PRD: `docs/PRD-MS22-P2-AGENT-FLEET.md`
|
||||||
|
|
||||||
|
| Task ID | Status | Phase | Description | Issue | Scope | Branch | Depends On | Blocks | Assigned Worker | Started | Completed | Est Tokens | Act Tokens | Notes |
|
||||||
|
| ----------- | ----------- | -------- | -------------------------------------------- | -------- | ----- | --------------------------- | ------------- | ------------- | --------------- | ------- | --------- | ---------- | ---------- | ----- |
|
||||||
|
| MS22-P2-001 | not-started | p2-fleet | Prisma schema: AgentTemplate, UserAgent | TASKS:P2 | api | feat/ms22-p2-agent-schema | MS22-P1a | P2-002,P2-003 | — | — | — | 10K | — | |
|
||||||
|
| MS22-P2-002 | not-started | p2-fleet | Seed default agents (jarvis, builder, medic) | TASKS:P2 | api | feat/ms22-p2-agent-seed | P2-001 | P2-004 | — | — | — | 5K | — | |
|
||||||
|
| MS22-P2-003 | not-started | p2-fleet | Agent template CRUD endpoints (admin) | TASKS:P2 | api | feat/ms22-p2-agent-api | P2-001 | P2-005 | — | — | — | 15K | — | |
|
||||||
|
| MS22-P2-004 | not-started | p2-fleet | User agent CRUD endpoints | TASKS:P2 | api | feat/ms22-p2-agent-api | P2-002,P2-003 | P2-006 | — | — | — | 15K | — | |
|
||||||
|
| MS22-P2-005 | not-started | p2-fleet | Agent status endpoints | TASKS:P2 | api | feat/ms22-p2-agent-api | P2-003 | P2-008 | — | — | — | 10K | — | |
|
||||||
|
| MS22-P2-006 | not-started | p2-fleet | Agent chat routing (select agent by name) | TASKS:P2 | api | feat/ms22-p2-agent-routing | P2-004 | P2-007 | — | — | — | 15K | — | |
|
||||||
|
| MS22-P2-007 | not-started | p2-fleet | Discord channel → agent routing | TASKS:P2 | api | feat/ms22-p2-discord-router | P2-006 | P2-009 | — | — | — | 15K | — | |
|
||||||
|
| MS22-P2-008 | not-started | p2-fleet | Agent list/selector UI in WebUI | TASKS:P2 | web | feat/ms22-p2-agent-ui | P2-005 | — | — | — | — | 15K | — | |
|
||||||
|
| MS22-P2-009 | not-started | p2-fleet | Unit tests for agent services | TASKS:P2 | api | test/ms22-p2-agent-tests | P2-007 | P2-010 | — | — | — | 15K | — | |
|
||||||
|
| MS22-P2-010 | not-started | p2-fleet | E2E verification: Discord → agent → response | TASKS:P2 | stack | — | P2-009 | — | — | — | — | 10K | — | |
|
||||||
|
|||||||
Reference in New Issue
Block a user