queue/docs/PRD.md

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

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)

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

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