mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs(ms22): add Phase 2 PRD and TASKS for Named Agent Fleet

Browse Source
This commit is contained in:
Jason Woltje
2026-03-04 14:17:57 -06:00
parent d7d8c3c88d
commit a777f1f695
2 changed files with 199 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
docs/PRD-MS22-P2-AGENT-FLEET.md Normal file
View 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)

17
docs/TASKS.md
View File

@@ -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-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 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 | — | |