Jason Woltje
9bd1450f90
Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
111 lines
3.1 KiB
Markdown
111 lines
3.1 KiB
Markdown
# PRD: mosaic-queue
|
|
|
|
**Version:** 0.0.1
|
|
**Status:** Approved
|
|
**Source:** ~/src/jarvis-brain/docs/planning/MOSAIC-QUEUE-PRD.md
|
|
|
|
---
|
|
|
|
## Problem Statement
|
|
|
|
Current task management relies on HEARTBEAT.md + MEMORY.md files (fragile, manual), with no cross-agent coordination, no transactional guarantees, state lost on session crash/compaction, and AI drift in task state management.
|
|
|
|
## Solution
|
|
|
|
A Valkey/Redis-backed task queue exposed via MCP (and optional REST), providing atomic task claims with TTL, cross-agent visibility, crash recovery, and zero AI involvement in state management.
|
|
|
|
## Core Interface
|
|
|
|
### Task Schema
|
|
```typescript
|
|
interface Task {
|
|
id: string;
|
|
project: string;
|
|
mission: string;
|
|
taskId: string;
|
|
title: string;
|
|
description?: string;
|
|
status: 'pending' | 'claimed' | 'in-progress' | 'completed' | 'failed' | 'blocked';
|
|
priority: 'critical' | 'high' | 'medium' | 'low';
|
|
dependencies: string[];
|
|
lane: 'planning' | 'coding' | 'any';
|
|
claimedBy?: string;
|
|
claimedAt?: number;
|
|
claimTTL?: number;
|
|
completedAt?: number;
|
|
failedAt?: number;
|
|
failureReason?: string;
|
|
retryCount: number;
|
|
metadata?: object;
|
|
createdAt: number;
|
|
updatedAt: number;
|
|
}
|
|
```
|
|
|
|
### CLI Commands (Phase 1)
|
|
```bash
|
|
mosaic queue create <project> <mission> <taskId> --title "..." [--priority high] [--lane coding]
|
|
mosaic queue list [--project X] [--mission Y] [--status pending]
|
|
mosaic queue show <taskId>
|
|
mosaic queue claim <taskId> --agent <agentId> --ttl 3600
|
|
mosaic queue heartbeat <taskId>
|
|
mosaic queue release <taskId>
|
|
mosaic queue complete <taskId> [--summary "..."]
|
|
```
|
|
|
|
### MCP Tools (Phase 1)
|
|
- `queue_list` — list tasks with filters
|
|
- `queue_get` — single task details
|
|
- `queue_claim` — atomic claim
|
|
- `queue_heartbeat` — extend TTL
|
|
- `queue_release` — release claim
|
|
- `queue_complete` — mark complete
|
|
- `queue_fail` — mark failed with reason
|
|
- `queue_status` — queue health/stats
|
|
|
|
## State Machine
|
|
`pending` → `claimed` (via claim) → `in-progress` (via start) → `completed` | `failed`
|
|
`claimed` → `pending` (TTL expiry, via watchdog)
|
|
|
|
## Configuration
|
|
```yaml
|
|
redis:
|
|
url: redis://localhost:6379
|
|
defaults:
|
|
claimTTL: 3600
|
|
maxRetries: 3
|
|
deadLetterAfter: 3
|
|
lanes:
|
|
planning:
|
|
maxConcurrent: 2
|
|
coding:
|
|
maxConcurrent: 4
|
|
watchdog:
|
|
interval: 60
|
|
openbrain:
|
|
url: https://brain.woltje.com
|
|
autoCapture: false
|
|
```
|
|
|
|
## Tech Stack
|
|
- TypeScript (Node.js)
|
|
- ioredis for Valkey/Redis
|
|
- @modelcontextprotocol/sdk for MCP server
|
|
- commander for CLI
|
|
- Valkey instance: existing mosaic-stack deployment
|
|
|
|
## Phases
|
|
- **Phase 1 (this milestone):** Core queue, CLI, MCP server
|
|
- **Phase 2:** TTL watchdog, dead letter queue, TASKS.md sync
|
|
- **Phase 3:** Coordinator integration, lane enforcement
|
|
- **Phase 4:** OpenBrain integration (finding capture)
|
|
|
|
## Acceptance Criteria (Phase 1)
|
|
1. `mosaic queue create` creates a task in Valkey
|
|
2. `mosaic queue claim` atomically claims (no double-claim race)
|
|
3. `mosaic queue list` filters by project/mission/status
|
|
4. `mosaic queue complete` marks done, optionally with summary
|
|
5. MCP server exposes all tools above
|
|
6. TypeScript strict, ESLint clean, tests green
|
|
7. README with setup + usage docs
|