From a777f1f69504de6f690b01f6f9303ae7821ebaec Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Wed, 4 Mar 2026 14:17:57 -0600 Subject: [PATCH] docs(ms22): add Phase 2 PRD and TASKS for Named Agent Fleet --- docs/PRD-MS22-P2-AGENT-FLEET.md | 182 ++++++++++++++++++++++++++++++++ docs/TASKS.md | 17 +++ 2 files changed, 199 insertions(+) create mode 100644 docs/PRD-MS22-P2-AGENT-FLEET.md diff --git a/docs/PRD-MS22-P2-AGENT-FLEET.md b/docs/PRD-MS22-P2-AGENT-FLEET.md new file mode 100644 index 0000000..553a3b1 --- /dev/null +++ b/docs/PRD-MS22-P2-AGENT-FLEET.md @@ -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) diff --git a/docs/TASKS.md b/docs/TASKS.md index a16c82d..5d3d55c 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -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 | — | |