chore(orchestrator): Bootstrap PRD + TASKS.md for v0.0.1
Phase 1: Core queue CLI + MCP server (8 tasks, ~85K est) Stack: TypeScript, ioredis, MCP SDK, commander
This commit is contained in:
110
docs/PRD.md
Normal file
110
docs/PRD.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user