From 9bd1450f907499f39989837a8419f25c7eaa8f65 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Fri, 6 Mar 2026 14:08:09 +0000 Subject: [PATCH] chore(orchestrator): Bootstrap PRD + TASKS.md v0.0.1 (#1) Co-authored-by: Jason Woltje Co-committed-by: Jason Woltje --- docs/PRD.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/TASKS.md | 12 ++++++ 2 files changed, 122 insertions(+) create mode 100644 docs/PRD.md create mode 100644 docs/TASKS.md diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..02d8e89 --- /dev/null +++ b/docs/PRD.md @@ -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 --title "..." [--priority high] [--lane coding] +mosaic queue list [--project X] [--mission Y] [--status pending] +mosaic queue show +mosaic queue claim --agent --ttl 3600 +mosaic queue heartbeat +mosaic queue release +mosaic queue complete [--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 diff --git a/docs/TASKS.md b/docs/TASKS.md new file mode 100644 index 0000000..9368f80 --- /dev/null +++ b/docs/TASKS.md @@ -0,0 +1,12 @@ +# Tasks — mosaic-queue v0.0.1 + +| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes | +|---|---|---|---|---|---|---|---|---|---|---|---|---|---| +| MQ-001 | not-started | Init: pnpm monorepo, TypeScript strict, ESLint, vitest | TASKS:P1 | queue | feat/core-queue | | MQ-002 | | | | 8K | | | +| MQ-002 | not-started | Valkey/Redis connection module with health check | TASKS:P1 | queue | feat/core-queue | MQ-001 | MQ-003 | | | | 5K | | | +| MQ-003 | not-started | Task CRUD: create, get, list, update (ioredis + JSON serialization) | TASKS:P1 | queue | feat/core-queue | MQ-002 | MQ-004 | | | | 12K | | | +| MQ-004 | not-started | Atomic claim/release/heartbeat/complete/fail operations | TASKS:P1 | queue | feat/core-queue | MQ-003 | MQ-005 | | | | 15K | | | +| MQ-005 | not-started | CLI: commander wiring for create/list/show/claim/release/complete | TASKS:P1 | queue | feat/core-queue | MQ-004 | MQ-006 | | | | 10K | | | +| MQ-006 | not-started | MCP server: queue_list/get/claim/heartbeat/release/complete/fail/status tools | TASKS:P1 | queue | feat/core-queue | MQ-005 | MQ-007 | | | | 15K | | | +| MQ-007 | not-started | Unit tests for claim atomicity + state transitions + MCP tool schemas | TASKS:P1 | queue | feat/core-queue | MQ-006 | MQ-008 | | | | 15K | | | +| MQ-008 | not-started | README, package.json bin entry, npm publish prep | TASKS:P1 | queue | feat/core-queue | MQ-007 | | | | | 5K | | |