docs(PRD): remove hardcoded OPENBRAIN_URL — must be user-configured

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

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 <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: ${OPENBRAIN_URL}  # required — no default
+  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

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 | | |