ranni-mcp 0.1.0

package/README.md

@@ -0,0 +1,163 @@
+# ranni
+
+Provider-agnostic multi-agent orchestration MCP server. Lets a manager agent (Claude Code, Codex, Copilot) dispatch autonomous worker subprocesses, track their progress via a file-backed task queue, and receive results when workers finish, need help, or error.
+
+The agent you are already talking to is the UI. Ranni is the plumbing.
+
+---
+
+## How it works
+
+```
+You ↔ Manager agent (Claude Code, your existing terminal agent)
+              │
+              │ MCP tools
+              ▼
+         ┌─────────────────────┐
+         │        ranni        │
+         │    (MCP server)     │
+         └──────────┬──────────┘
+                    │ spawns subprocesses
+         ┌──────────┼──────────┐
+         ▼          ▼          ▼
+     [Worker A]  [Worker B]  [Worker C]   ← up to max_workers
+         │          │          │
+         └──────────┴──────────┘
+                    │ structured JSON result
+                    ▼
+         Manager reads callbacks, decides what to do next
+```
+
+Workers run fully autonomously. They never talk to the user directly — they exit with a structured result, ranni queues it, and the manager reads it and decides whether to escalate.
+
+The task queue is a plain JSON file on disk. It survives reboots, is manually editable, and is the single source of truth for all task state.
+
+---
+
+## Install
+
+```bash
+bun add ranni-mcp
+bun node_modules/ranni-mcp/src/init.ts
+```
+
+`init` writes three things into your project:
+
+| File | Behaviour |
+|------|-----------|
+| `.claude/skills/ranni/` | Manager skill for Claude Code — always overwrites |
+| `.agents.yaml` | Starter config — skipped if already exists |
+| `.mcp.json` | Merges the ranni entry, preserving all existing entries |
+
+---
+
+## Configuration
+
+Edit `.agents.yaml` at your repo root:
+
+```yaml
+worker:
+  command: claude
+  args: [--print, --dangerously-skip-permissions]
+
+max_workers: 3
+persist_runs: false   # set true to archive full worker stdout
+
+dirs:
+  root: .
+  backend: ./backend
+  web: ./apps/web
+  mobile: ./apps/mobile
+
+# Optional — injected into every MCP tool response as a reminder
+# manager_context: |
+#   Always call get_pending_results() before dispatching new tasks.
+```
+
+`worker.command` can be any CLI that accepts a prompt on stdin — `claude`, `codex`, `aider`, anything.
+
+---
+
+## MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `dispatch_task` | Push one or more tasks onto the queue |
+| `list_active_workers` | Snapshot of running + queued tasks |
+| `get_pending_results` | Read completed results (drains buffer by default) |
+| `cancel_task` | Cancel a pending task by ID |
+
+### `dispatch_task` input
+
+```ts
+{
+  tasks: Array<{
+    id: string             // unique ID you choose for tracking
+    dir: string            // key from .agents.yaml dirs
+    task: string           // full self-contained task description
+    context?: string       // optional background, constraints
+    links?: string[]       // URLs the worker should read first (tickets, PRs, docs)
+    relevant_files?: string[]  // files already identified — worker starts here
+    depends_on?: string[]  // task IDs that must be "done" before this starts
+  }>
+}
+```
+
+---
+
+## Worker output protocol
+
+Every worker must end its output with this block as the very last thing written:
+
+```
+<orchestrator_result>
+{"status":"done","summary":"one-line summary","files_changed":["relative/path"],"message":"optional"}
+</orchestrator_result>
+```
+
+Valid statuses: `done`, `needs_help`, `error`.
+
+If the marker is absent (crash, unexpected exit), ranni synthesises an `error` result from the last 2000 chars of stdout.
+
+---
+
+## Task statuses
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Queued, not yet started |
+| `running` | Worker subprocess active |
+| `done` | Completed successfully |
+| `done_with_conflict` | Done, but touched a file another worker already modified — resolution task auto-dispatched |
+| `needs_help` | Worker could not proceed — manager must act |
+| `error` | Worker failed — manager may retry or cancel |
+| `cancelled` | Removed before it ran |
+
+Tasks left in `running` state from a crashed session are automatically reset to `pending` on startup.
+
+---
+
+## Task dependencies
+
+```json
+{
+  "id": "web-ui",
+  "depends_on": ["api-endpoint", "mobile-service"]
+}
+```
+
+Ranni skips a task until every ID in `depends_on` has status `done`. IDs not found in the queue are treated as satisfied (completed in a prior session).
+
+---
+
+## Runtime files
+
+- `.agent-queue.json` — task queue state, lives alongside `.agents.yaml` (gitignore this)
+- `tools/ranni/runs/<timestamp>/` — worker output archives when `persist_runs: true` (gitignore this)
+
+---
+
+## Requirements
+
+- [Bun](https://bun.sh) ≥ 1.0
+- A Claude Code (or compatible) setup with MCP support

package/bin/ranni-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/index.ts'

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "ranni-mcp",
+  "version": "0.1.0",
+  "description": "Provider-agnostic multi-agent orchestration MCP server",
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "bin": {
+    "ranni-mcp": "./bin/ranni-mcp.js"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "init": "bun run src/init.ts",
+    "build": "bun build --compile src/index.ts --outfile dist/ranni-mcp",
+    "typecheck": "tsc --noEmit",
+    "publish": "bun run scripts/publish.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "yaml": "^2.4.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.4.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { parse } from 'yaml';
+import { z } from 'zod';
+import type { Config } from './types.js';
+
+const ConfigSchema = z.object({
+  worker: z.object({
+    command: z.string(),
+    args: z.array(z.string()).default([])
+  }),
+  max_workers: z.number().int().min(1).default(3),
+  persist_runs: z.boolean().default(false),
+  dirs: z.record(z.string()),
+  manager_context: z.string().optional()
+})
+
+function findConfigDir(startDir: string): string | null {
+  let dir = startDir
+  while (true) {
+    if (existsSync(join(dir, '.agents.yaml'))) return dir
+    if (existsSync(join(dir, '.git'))) return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+export function loadConfig(startDir = process.cwd()): { config: Config; configDir: string } {
+  const configDir = findConfigDir(startDir)
+  if (!configDir) {
+    throw new Error(
+      `No .agents.yaml found. Walk from "${startDir}" to git root found nothing.\n` +
+        `Create .agents.yaml at your repo root. Run: bun node_modules/ranni-mcp/src/init.ts`
+    )
+  }
+
+  const raw = readFileSync(join(configDir, '.agents.yaml'), 'utf8')
+  const parsed = parse(raw)
+  const result = ConfigSchema.safeParse(parsed)
+
+  if (!result.success) {
+    throw new Error(
+      `.agents.yaml is invalid:\n${result.error.issues.map(i => `  ${i.path.join('.')}: ${i.message}`).join('\n')}`
+    )
+  }
+
+  const config = result.data as Config
+
+  for (const [key, rel] of Object.entries(config.dirs)) {
+    const abs = join(configDir, rel)
+    if (!existsSync(abs)) {
+      throw new Error(`.agents.yaml dirs.${key} = "${rel}" does not exist (resolved to "${abs}")`)
+    }
+    config.dirs[key] = abs
+  }
+
+  return { config, configDir }
+}

package/src/conflict.ts

@@ -0,0 +1,74 @@
+import { enqueue, readQueue, writeQueue } from './queue.js';
+import type { QueueFile, Task, WorkerResult } from './types.js';
+
+export type ConflictInfo = {
+  taskId: string
+  conflictingFiles: Array<{ file: string; previousTaskId: string }>
+}
+
+export function detectConflict(result: WorkerResult, queue: QueueFile, taskId: string): ConflictInfo | null {
+  const conflicts: ConflictInfo['conflictingFiles'] = []
+
+  for (const file of result.files_changed) {
+    const prev = queue.touched_files[file]
+    if (prev && prev !== taskId) {
+      conflicts.push({ file, previousTaskId: prev })
+    }
+  }
+
+  return conflicts.length > 0 ? { taskId, conflictingFiles: conflicts } : null
+}
+
+async function getDiff(file: string, cwd: string): Promise<string> {
+  try {
+    const proc = Bun.spawn(['git', 'diff', 'HEAD', '--', file], {
+      cwd,
+      stdout: 'pipe',
+      stderr: 'pipe'
+    })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    return output || '(no diff available)'
+  } catch {
+    return '(could not generate diff)'
+  }
+}
+
+export async function handleConflict(
+  queueFilePath: string,
+  originalTask: Task,
+  conflict: ConflictInfo,
+  resolvedDir: string
+): Promise<void> {
+  const queue = readQueue(queueFilePath)
+  const original = queue.tasks.find(t => t.id === originalTask.id)
+  if (original) original.status = 'done_with_conflict'
+
+  const existingResolutions = queue.tasks.filter(t => t.id.startsWith(`${originalTask.id}-conflict-`)).length
+
+  const resolutionId = `${originalTask.id}-conflict-${existingResolutions + 1}`
+
+  const diffSections: string[] = []
+  for (const { file, previousTaskId } of conflict.conflictingFiles) {
+    const diff = await getDiff(file, resolvedDir)
+    diffSections.push(`File: ${file}\nFirst modified by task: ${previousTaskId}\n\nRejected diff:\n${diff}`)
+  }
+
+  const resolutionTask = `Resolve file conflict from task "${originalTask.id}".
+
+The following files were already modified by an earlier worker. The first worker's version is on disk. Review the rejected diff below and apply any changes that are safe to merge without breaking the existing work.
+
+${diffSections.join('\n\n---\n\n')}
+
+If the changes cannot be safely merged, set status to "needs_help" and explain what a human needs to decide.`
+
+  writeQueue(queueFilePath, queue)
+
+  enqueue(queueFilePath, [
+    {
+      id: resolutionId,
+      dir: originalTask.dir,
+      task: resolutionTask
+    }
+  ])
+}

package/src/index.ts

@@ -0,0 +1,276 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig } from './config.js';
+import { detectConflict, handleConflict } from './conflict.js';
+import {
+    cancelTask,
+    complete,
+    enqueue,
+    getPendingResults,
+    getSnapshot,
+    queuePath,
+    readQueue,
+    resetInterrupted,
+    startNext
+} from './queue.js';
+import { initRun } from './runs.js';
+import type { Config, Task } from './types.js';
+import { runWorker } from './worker.js';
+
+const DEFAULT_MANAGER_CONTEXT = `ORCHESTRATOR RULES (read before every action):
+1. Always call get_pending_results before dispatching new tasks — read every result first.
+2. Each task must be self-contained: include all file paths, context, and background the worker needs.
+3. Use depends_on when task B genuinely needs task A's output to be on disk first.
+4. When a worker returns needs_help, surface the question to the user before dispatching a follow-up.
+5. When a worker returns error, decide: retry, dispatch a corrected version, or inform the user.`
+
+function formatFooter(managerContext: string): string {
+  return `\n\n---\n${managerContext}`
+}
+
+async function main() {
+  const { config, configDir } = loadConfig()
+  const qPath = queuePath(configDir)
+  const runLogger = initRun(config, configDir)
+
+  resetInterrupted(qPath)
+
+  let activeCount = 0
+
+  async function tickPool() {
+    const available = config.max_workers - activeCount
+    if (available <= 0) return
+
+    for (let i = 0; i < available; i++) {
+      const task = startNext(qPath)
+      if (!task) break
+
+      activeCount++
+      runWorkerAsync(task, config, qPath, runLogger, configDir).finally(() => {
+        activeCount--
+      })
+    }
+  }
+
+  setInterval(tickPool, 200)
+
+  const server = new Server({ name: 'ranni-mcp', version: '0.1.0' }, { capabilities: { tools: {} } })
+
+  const footer = formatFooter(config.manager_context ?? DEFAULT_MANAGER_CONTEXT)
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: 'dispatch_task',
+        description:
+          'Add one or more tasks to the worker queue. Workers run autonomously up to max_workers in parallel.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            tasks: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string', description: 'Unique ID you choose for tracking' },
+                  dir: { type: 'string', description: `One of: ${Object.keys(config.dirs).join(', ')}` },
+                  task: { type: 'string', description: 'Full self-contained task description for the worker' },
+                  context: { type: 'string', description: 'Optional extra context: file paths, background, etc.' },
+                  links: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description:
+                      'URLs the worker should read first (Notion tickets, PRs, docs). Worker is instructed to fetch these before touching any code.'
+                  },
+                  relevant_files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description:
+                      'File paths already identified by the manager. Worker starts investigation here instead of searching from scratch.'
+                  },
+                  depends_on: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Task IDs that must be done before this starts'
+                  }
+                },
+                required: ['id', 'dir', 'task']
+              },
+              minItems: 1
+            }
+          },
+          required: ['tasks']
+        }
+      },
+      {
+        name: 'list_active_workers',
+        description: 'Snapshot of the current queue: running workers, pending tasks, and free slots.',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'get_pending_results',
+        description: 'Read completed worker results since the last call. Call this before dispatching new tasks.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            drain: { type: 'boolean', description: 'Mark results as acknowledged after reading (default: true)' }
+          }
+        }
+      },
+      {
+        name: 'cancel_task',
+        description: 'Cancel a pending (not yet running) task.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Task ID to cancel' }
+          },
+          required: ['id']
+        }
+      }
+    ]
+  }))
+
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    const { name, arguments: args } = request.params
+
+    switch (name) {
+      case 'dispatch_task': {
+        const tasks = (args as any).tasks as Array<{
+          id: string
+          dir: string
+          task: string
+          context?: string
+          links?: string[]
+          relevant_files?: string[]
+          depends_on?: string[]
+        }>
+
+        const unknownDirs = tasks.filter(t => !config.dirs[t.dir]).map(t => t.dir)
+        if (unknownDirs.length > 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Error: unknown dir(s): ${[...new Set(unknownDirs)].join(', ')}. Valid dirs: ${Object.keys(config.dirs).join(', ')}${footer}`
+              }
+            ]
+          }
+        }
+
+        enqueue(qPath, tasks)
+        tickPool()
+
+        const snapshot = getSnapshot(qPath)
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Queued ${tasks.length} task(s). Active workers: ${activeCount}/${config.max_workers}. Queue depth: ${snapshot.queued.length}.${footer}`
+            }
+          ]
+        }
+      }
+
+      case 'list_active_workers': {
+        const snapshot = getSnapshot(qPath)
+        const runningList = snapshot.running
+          .map(t => `  [running] ${t.id} (${t.dir}) — started ${t.started_at}`)
+          .join('\n')
+        const queuedList = snapshot.queued
+          .map(
+            t =>
+              `  [queued]  ${t.id} (${t.dir})${t.depends_on?.length ? ` — waiting on: ${t.depends_on.join(', ')}` : ''}`
+          )
+          .join('\n')
+        const lines = [
+          `Workers: ${activeCount}/${config.max_workers} active`,
+          runningList || '  (none running)',
+          queuedList || '  (queue empty)'
+        ].join('\n')
+        return { content: [{ type: 'text', text: lines + footer }] }
+      }
+
+      case 'get_pending_results': {
+        const drain = (args as any)?.drain !== false
+        const results = getPendingResults(qPath, drain)
+
+        if (results.length === 0) {
+          return { content: [{ type: 'text', text: `No new results.${footer}` }] }
+        }
+
+        const formatted = results
+          .map(t => {
+            const r = t.result
+            const status = r ? r.status : t.status
+            const summary = r ? r.summary : '(no summary)'
+            const files = r?.files_changed?.length ? `\n  Files: ${r.files_changed.join(', ')}` : ''
+            const msg = r?.message ? `\n  Message: ${r.message}` : ''
+            return `[${status.toUpperCase()}] ${t.id} (${t.dir})\n  ${summary}${files}${msg}`
+          })
+          .join('\n\n')
+
+        return { content: [{ type: 'text', text: formatted + footer }] }
+      }
+
+      case 'cancel_task': {
+        const id = (args as any).id as string
+        const cancelled = cancelTask(qPath, id)
+        const msg = cancelled
+          ? `Task "${id}" cancelled.`
+          : `Task "${id}" could not be cancelled — it may be running or already finished.`
+        return { content: [{ type: 'text', text: msg + footer }] }
+      }
+
+      default:
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }] }
+    }
+  })
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  process.stderr.write('Orchestrator MCP server running\n')
+}
+
+async function runWorkerAsync(
+  task: Task,
+  config: Config,
+  qPath: string,
+  runLogger: ReturnType<typeof initRun>,
+  configDir: string
+) {
+  try {
+    const result = await runWorker(task, config)
+
+    complete(qPath, task.id, result)
+
+    runLogger?.updateSummary(readQueue(qPath).tasks)
+
+    const queue = readQueue(qPath)
+    const conflict = detectConflict(result, queue, task.id)
+    if (conflict) {
+      const resolvedDir = config.dirs[task.dir]!
+      await handleConflict(qPath, task, conflict, resolvedDir)
+    }
+
+    if (runLogger) {
+      const stdout = result.message ?? result.summary
+      runLogger.logTask(task.id, stdout)
+      runLogger.updateSummary(readQueue(qPath).tasks)
+    }
+  } catch (err) {
+    complete(qPath, task.id, {
+      status: 'error',
+      summary: 'Worker threw an unexpected error',
+      files_changed: [],
+      message: String(err),
+      exit_code: 1
+    })
+  }
+}
+
+main().catch(err => {
+  process.stderr.write(`Fatal: ${err}\n`)
+  process.exit(1)
+})

package/src/init.ts

@@ -0,0 +1,57 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+
+const templatesDir = join(import.meta.dir, '..', 'templates')
+const cwd = process.cwd()
+
+function copySkill() {
+  const src = join(templatesDir, 'ranni')
+  const dest = join(cwd, '.claude', 'skills', 'ranni')
+  mkdirSync(dirname(dest), { recursive: true })
+  cpSync(src, dest, { recursive: true })
+  console.log('✓ Skill installed at .claude/skills/ranni/')
+}
+
+function copyAgentsYaml() {
+  const dest = join(cwd, '.agents.yaml')
+  if (existsSync(dest)) {
+    console.log('⚠ .agents.yaml already exists — skipped (edit it to configure your dirs)')
+    return
+  }
+  cpSync(join(templatesDir, '.agents.yaml'), dest)
+  console.log('✓ .agents.yaml created — edit dirs to match your project')
+}
+
+function mergeMcpJson() {
+  const dest = join(cwd, '.mcp.json')
+
+  let existing: Record<string, any> = {}
+  if (existsSync(dest)) {
+    try {
+      existing = JSON.parse(readFileSync(dest, 'utf8'))
+    } catch {
+      console.error('✗ .mcp.json exists but contains invalid JSON — fix it manually and re-run')
+      return
+    }
+  }
+
+  if (existing.mcpServers?.['ranni-mcp']) {
+    console.log('⚠ .mcp.json already has a "ranni-mcp" entry — skipped')
+    return
+  }
+
+  existing.mcpServers ??= {}
+  existing.mcpServers['ranni-mcp'] = {
+    command: 'bun',
+    args: ['run', 'node_modules/ranni-mcp/src/index.ts']
+  }
+
+  writeFileSync(dest, JSON.stringify(existing, null, 2) + '\n', 'utf8')
+  console.log('✓ .mcp.json updated with ranni-mcp MCP server entry')
+}
+
+copySkill()
+copyAgentsYaml()
+mergeMcpJson()
+
+console.log('\nDone. Edit .agents.yaml to set your project dirs, then restart Claude Code.')

package/src/queue.ts

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import type { QueueFile, Task, TaskStatus, WorkerResult } from './types.js';
+
+export function queuePath(configDir: string): string {
+  return join(configDir, '.agent-queue.json')
+}
+
+export function readQueue(path: string): QueueFile {
+  if (!existsSync(path)) return { tasks: [], touched_files: {} }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as QueueFile
+  } catch {
+    return { tasks: [], touched_files: {} }
+  }
+}
+
+export function writeQueue(path: string, queue: QueueFile): void {
+  const tmp = path + '.tmp'
+  writeFileSync(tmp, JSON.stringify(queue, null, 2), 'utf8')
+  renameSync(tmp, path)
+}
+
+export function enqueue(
+  path: string,
+  tasks: Omit<Task, 'status' | 'created_at' | 'started_at' | 'finished_at' | 'result' | 'acknowledged'>[]
+): void {
+  const queue = readQueue(path)
+  const now = new Date().toISOString()
+  for (const t of tasks) {
+    queue.tasks.push({
+      ...t,
+      status: 'pending',
+      created_at: now,
+      started_at: null,
+      finished_at: null,
+      result: null,
+      acknowledged: false
+    })
+  }
+  writeQueue(path, queue)
+}
+
+export function startNext(path: string): Task | null {
+  const queue = readQueue(path)
+  const doneIds = new Set(queue.tasks.filter(t => t.status === 'done').map(t => t.id))
+
+  const idx = queue.tasks.findIndex(t => {
+    if (t.status !== 'pending') return false
+    if (!t.depends_on || t.depends_on.length === 0) return true
+    return t.depends_on.every(dep => doneIds.has(dep))
+  })
+
+  if (idx === -1) return null
+
+  queue.tasks[idx]!.status = 'running'
+  queue.tasks[idx]!.started_at = new Date().toISOString()
+  writeQueue(path, queue)
+  return queue.tasks[idx]!
+}
+
+export function complete(path: string, id: string, result: WorkerResult): void {
+  const queue = readQueue(path)
+  const task = queue.tasks.find(t => t.id === id)
+  if (!task) return
+
+  const terminalStatus: TaskStatus = result.status === 'done' ? 'done' : result.status
+  task.status = terminalStatus
+  task.finished_at = new Date().toISOString()
+  task.result = result
+
+  for (const file of result.files_changed) {
+    queue.touched_files[file] = id
+  }
+
+  writeQueue(path, queue)
+}
+
+export function markConflict(path: string, id: string): void {
+  const queue = readQueue(path)
+  const task = queue.tasks.find(t => t.id === id)
+  if (task) {
+    task.status = 'done_with_conflict'
+    writeQueue(path, queue)
+  }
+}
+
+export function resetInterrupted(path: string): void {
+  const queue = readQueue(path)
+  let changed = false
+  for (const task of queue.tasks) {
+    if (task.status === 'running') {
+      task.status = 'pending'
+      task.started_at = null
+      changed = true
+    }
+  }
+  if (changed) writeQueue(path, queue)
+}
+
+export function cancelTask(path: string, id: string): boolean {
+  const queue = readQueue(path)
+  const task = queue.tasks.find(t => t.id === id)
+  if (!task || task.status !== 'pending') return false
+  task.status = 'cancelled'
+  writeQueue(path, queue)
+  return true
+}
+
+export function getPendingResults(path: string, drain: boolean): Task[] {
+  const queue = readQueue(path)
+  const terminal: TaskStatus[] = ['done', 'done_with_conflict', 'needs_help', 'error']
+  const results = queue.tasks.filter(t => terminal.includes(t.status) && !t.acknowledged)
+
+  if (drain && results.length > 0) {
+    const ids = new Set(results.map(t => t.id))
+    for (const task of queue.tasks) {
+      if (ids.has(task.id)) task.acknowledged = true
+    }
+    writeQueue(path, queue)
+  }
+
+  return results
+}
+
+export function getSnapshot(path: string): {
+  running: Task[]
+  queued: Task[]
+  slots_free: number
+  max_workers: number
+} {
+  const queue = readQueue(path)
+  return {
+    running: queue.tasks.filter(t => t.status === 'running'),
+    queued: queue.tasks.filter(t => t.status === 'pending'),
+    slots_free: 0,
+    max_workers: 0
+  }
+}

package/src/runs.ts

@@ -0,0 +1,25 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import type { Config, Task } from './types.js';
+
+export type RunLogger = {
+  logTask(id: string, stdout: string): void
+  updateSummary(tasks: Task[]): void
+}
+
+export function initRun(config: Config, configDir: string): RunLogger | null {
+  if (!config.persist_runs) return null
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-')
+  const runDir = join(configDir, 'tools', 'ranni', 'runs', ts)
+  mkdirSync(runDir, { recursive: true })
+
+  return {
+    logTask(id: string, stdout: string): void {
+      writeFileSync(join(runDir, `${id}.txt`), stdout, 'utf8')
+    },
+    updateSummary(tasks: Task[]): void {
+      writeFileSync(join(runDir, 'summary.json'), JSON.stringify(tasks, null, 2), 'utf8')
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+export type TaskStatus = 'pending' | 'running' | 'done' | 'done_with_conflict' | 'needs_help' | 'error' | 'cancelled'
+
+export type Task = {
+  id: string
+  status: TaskStatus
+  dir: string
+  task: string
+  context?: string
+  links?: string[]
+  relevant_files?: string[]
+  depends_on?: string[]
+  created_at: string
+  started_at: string | null
+  finished_at: string | null
+  result: WorkerResult | null
+  acknowledged: boolean
+}
+
+export type WorkerResult = {
+  status: 'done' | 'needs_help' | 'error'
+  summary: string
+  files_changed: string[]
+  message?: string
+  exit_code: number
+}
+
+export type QueueFile = {
+  tasks: Task[]
+  touched_files: Record<string, string>
+}
+
+export type Config = {
+  worker: { command: string; args: string[] }
+  max_workers: number
+  persist_runs: boolean
+  dirs: Record<string, string>
+  manager_context?: string
+}

package/src/worker.ts

@@ -0,0 +1,119 @@
+import type { Config, Task, WorkerResult } from './types.js';
+
+export const WORKER_SYSTEM_PROMPT = `You are an autonomous coding agent. Complete the task below fully and independently.
+Do not ask for confirmation. Do not stop mid-task.
+
+## Required phases — follow in order
+
+### Phase 1: Investigate before writing any code
+- Read every file relevant to the task. Search by component name, feature name, or symbol.
+- Understand the full structure around the problem: layout hierarchy, data flow, navigation stack, etc.
+- Identify the ROOT CAUSE — not a surface symptom. State your diagnosis explicitly before making changes.
+- If you are fixing a visual/layout bug: trace the actual render tree. Know exactly which element is
+  responsible for the incorrect behavior before touching any file.
+
+### Phase 2: Apply the minimal targeted fix
+- Change only what is needed to address the root cause you identified.
+- Do not add defensive code for unrelated edge cases.
+- Do not refactor surrounding code unless it is blocking the fix.
+
+---
+
+When you are done — whether successful, blocked, or errored — output the following
+as the very last thing you write, with no other text after it:
+
+<orchestrator_result>
+{"status":"done|needs_help|error","summary":"one-line summary","files_changed":["relative/path"],"message":"optional longer message"}
+</orchestrator_result>
+
+Rules:
+- Use "done" when the task is fully complete.
+- Use "needs_help" only when you genuinely cannot proceed without information you do not have.
+- Use "error" when you attempted the task and it failed.
+- "files_changed" must list every file you created or modified, as paths relative to your working directory.
+- "message" is required for "needs_help" and "error"; optional for "done".
+
+---
+`
+
+function buildPrompt(task: Task): string {
+  let prompt = WORKER_SYSTEM_PROMPT
+
+  if (task.links?.length) {
+    prompt += `REFERENCE LINKS (read these first — they contain the original issue description, acceptance criteria, and any screenshots):\n`
+    prompt += task.links.map(l => `  - ${l}`).join('\n') + '\n\n'
+  }
+
+  if (task.relevant_files?.length) {
+    prompt += `RELEVANT FILES (already identified by the manager — start your investigation here):\n`
+    prompt += task.relevant_files.map(f => `  - ${f}`).join('\n') + '\n\n'
+  }
+
+  prompt += `TASK:\n${task.task}\n`
+  if (task.context) prompt += `\nCONTEXT:\n${task.context}\n`
+  return prompt
+}
+
+function parseResult(stdout: string, exitCode: number): WorkerResult {
+  const match = stdout.match(/<orchestrator_result>\s*([\s\S]*?)\s*<\/orchestrator_result>/)
+  if (!match || !match[1]) {
+    return {
+      status: 'error',
+      summary: 'Worker exited without producing an <orchestrator_result> block',
+      files_changed: [],
+      message: stdout.slice(-2000),
+      exit_code: exitCode
+    }
+  }
+
+  try {
+    const parsed = JSON.parse(match[1])
+    return {
+      status: parsed.status ?? 'error',
+      summary: parsed.summary ?? '(no summary)',
+      files_changed: Array.isArray(parsed.files_changed) ? parsed.files_changed : [],
+      message: parsed.message,
+      exit_code: exitCode
+    }
+  } catch {
+    return {
+      status: 'error',
+      summary: 'Worker produced malformed <orchestrator_result> JSON',
+      files_changed: [],
+      message: match[1],
+      exit_code: exitCode
+    }
+  }
+}
+
+export async function runWorker(task: Task, config: Config): Promise<WorkerResult> {
+  const resolvedDir = config.dirs[task.dir]
+  if (!resolvedDir) {
+    return {
+      status: 'error',
+      summary: `Unknown dir key "${task.dir}" — not in .agents.yaml dirs`,
+      files_changed: [],
+      exit_code: 1
+    }
+  }
+
+  const prompt = buildPrompt(task)
+
+  const proc = Bun.spawn([config.worker.command, ...config.worker.args], {
+    cwd: resolvedDir,
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe'
+  })
+
+  proc.stdin.write(prompt)
+  proc.stdin.end()
+
+  const [stdout, , exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited
+  ])
+
+  return parseResult(stdout, exitCode)
+}

package/templates/.agents.yaml

@@ -0,0 +1,17 @@
+worker:
+  command: claude
+  args: [--print, --dangerously-skip-permissions]
+
+max_workers: 3
+persist_runs: false
+
+dirs:
+  root: .
+  # Add your project directories:
+  # backend: ./backend
+  # web: ./apps/web
+  # mobile: ./apps/mobile
+
+# Optional — injected into every MCP tool response as a reminder to the manager
+# manager_context: |
+#   Always call get_pending_results() before dispatching new tasks.

package/templates/ranni/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: orchestrate
+description: >
+  Activates manager mode for the multi-agent orchestrator. Use whenever the user
+  wants to dispatch parallel coding tasks, manage the agent queue, check worker
+  results, break down a feature into parallel work, or ask about the current state
+  of the task queue. Trigger on phrases like "orchestrate this", "dispatch to workers",
+  "add to the queue", "what are the workers doing", "check results", "run this in parallel",
+  "break this into tasks", "manage the agents", or any time the user describes work
+  that should fan out across multiple autonomous workers.
+---
+
+# Orchestrator Manager Skill
+
+You are now the **manager agent** for the multi-agent orchestrator. Your job is to
+understand what the user wants to accomplish, break it into atomic tasks, dispatch
+those tasks to autonomous workers through the orchestrator MCP, and track progress
+until everything is done or escalated.
+
+Workers are fully autonomous — they run code changes without any human approval.
+You are their only interface to the user.
+
+---
+
+## Startup — do this before anything else
+
+### 1. Verify the orchestrator is connected
+
+The orchestrator exposes four MCP tools: `dispatch_task`, `list_active_workers`,
+`get_pending_results`, `cancel_task`.
+
+If these tools are not available:
+- Tell the user the ranni MCP server is not running.
+- Instruct them to start it: `bun run node_modules/ranni-mcp/src/index.ts`
+- Then instruct them to check `.mcp.json` has the ranni entry (run `bun node_modules/ranni-mcp/src/init.ts` if not)
+- Stop here until it is running.
+
+### 2. Read the current queue state
+
+Always call both tools at startup:
+
+```
+get_pending_results(drain: false)   ← see what's waiting without consuming it
+list_active_workers()               ← see what's running and what's queued
+```
+
+Report the state to the user before asking what they want to do.
+
+---
+
+## The manager loop
+
+Every turn follows this exact order — no exceptions:
+
+```
+1. Call get_pending_results()       ← ALWAYS first, every turn
+2. Read every result carefully
+3. Decide what to do next
+4. Either: reply to the user, dispatch more tasks, ask a clarifying question, or escalate
+```
+
+**Never dispatch before reading results.** Workers may have produced output that changes
+what should be dispatched next. A result that says "needs_help" or "error" may block
+or invalidate tasks you were about to queue.
+
+---
+
+## Proactive result monitoring
+
+After dispatching tasks, **do not go silent**. Workers finish asynchronously and the
+user should not have to ask "what happened" — you surface results proactively.
+
+After every dispatch (or any turn where workers are still running), use `ScheduleWakeup`
+to re-enter the manager loop automatically:
+
+```
+ScheduleWakeup({
+  delaySeconds: 90,
+  prompt: "<original skill invocation prompt>",
+  reason: "polling worker results — N tasks still running"
+})
+```
+
+Each wakeup follows the normal manager loop: call `get_pending_results()`, report
+completions/errors to the user, dispatch follow-ups if needed, then reschedule
+if work remains. Stop scheduling once `list_active_workers()` shows an empty queue
+and there are no unacknowledged results.
+
+**Interval guidance:**
+- Workers typically finish in 2–5 min — use 90s while actively running
+- Once the queue is empty, stop rescheduling entirely
+
+---
+
+## Breaking down work
+
+When the user describes something to build or fix, your job is to:
+
+1. **Understand the full scope** — ask one clarifying question if genuinely ambiguous,
+   then proceed. Do not ask multiple questions upfront.
+
+2. **Identify the affected sub-projects** — use the available dirs from `.agents.yaml`.
+
+3. **Split into atomic tasks** — each task must:
+   - Touch only one concern or one sub-project
+   - Be completable without knowledge of what other workers are doing
+   - Be fully self-contained: include file paths, what to change, and why
+
+4. **Express real dependencies** — use `depends_on` only when task B literally cannot
+   run until task A's files are on disk. Do not use it just because tasks are "related."
+
+5. **Dispatch immediately** — push tasks as soon as you know them. Do not wait to
+   describe your whole plan before dispatching.
+
+---
+
+## Writing good task descriptions
+
+Workers have no memory of this conversation. Every task must stand alone.
+
+**Good task:**
+```
+Add a POST /api/notifications endpoint to the Django backend.
+- Create apps/notifications/views.py with a NotificationView class.
+- Register the URL in backend/api/urls.py as /api/notifications/.
+- The endpoint accepts { user_id: string, message: string, type: "push"|"email" }.
+- Return 201 on success, 400 on validation error.
+- Use the existing authentication middleware from apps/core/middleware.py.
+```
+
+**Bad task:**
+```
+Add the notifications endpoint we discussed.
+```
+
+Workers cannot see "we discussed." Repeat every relevant detail in the task field.
+
+---
+
+## Dispatching
+
+```
+dispatch_task({
+  tasks: [
+    {
+      id: "unique-kebab-case-id",
+      dir: "backend",
+      task: "Full self-contained task description...",
+      context: "Optional: file paths, background, constraints",
+      links: ["https://notion.so/..."],
+      relevant_files: ["src/screens/Foo.tsx"],
+      depends_on: ["other-task-id"]
+    }
+  ]
+})
+```
+
+IDs should be descriptive: `notif-api-endpoint`, `notif-mobile-service`.
+Avoid generic IDs like `task-1`, `task-2`.
+
+Always populate `links` and `relevant_files` when you have them — workers start
+investigation here instead of searching from scratch.
+
+---
+
+## Handling results
+
+| Status | What to do |
+|--------|-----------|
+| `done` | Note what changed. Dispatch follow-up work if needed. |
+| `done_with_conflict` | A resolution task was auto-injected — check `list_active_workers()`. |
+| `needs_help` | Surface to user: **"Worker [id] needs your input: [message]"** |
+| `error` | Decide: retry, dispatch a corrected version, or inform the user. Never silently skip. |
+
+---
+
+## Checking the board
+
+```
+list_active_workers()
+get_pending_results(drain: false)
+```
+
+Report format:
+```
+Running (N/max_workers):
+  [notif-api] backend — started 2 min ago
+
+Queued (N waiting):
+  [push-ui] web — waiting on: notif-api
+
+Recent results:
+  ✓ [notif-mobile] done — Created NotificationService.ts
+  ✗ [notif-web] error — "Could not find usePushToken hook"
+```
+
+---
+
+## Session end
+
+When the user is done:
+
+1. Call `list_active_workers()` — if workers are still running, warn the user.
+   Running workers continue even after this session ends.
+
+2. Remind the user the queue persists in `.agent-queue.json` and is safe to resume.