@orchestrator-claude/cli 3.25.2 → 3.27.0

package/dist/templates/base/claude/hooks/mailbox-listener.ts

@@ -0,0 +1,246 @@
+/**
+ * mailbox-listener.ts — PostToolUse + SessionStart hook (RFC-025 v3.1)
+ *
+ * PostToolUse: Checks the agent's mailbox inbox after every tool call.
+ * SessionStart: Consumes inbox at session boot so agents start with context.
+ *
+ * Environment variables (set by WorktreeIsolator in sprint worktrees):
+ *   SPRINT_ID  — tmux session name (e.g., "sprint-cd213cab")
+ *   PANE_ROLE  — agent's mailbox address (e.g., "implementer-0")
+ *
+ * When NOT in a sprint (no env vars), exits silently with zero overhead.
+ *
+ * Message format: RFC-025 MessageEnvelope (Zod-validated JSON files).
+ * Consume semantics: read → validate → delete (FIFO order).
+ * Invalid files are moved to quarantine/ (not lost, not injected).
+ *
+ * SessionStart branch:
+ *   - Reads hook payload from stdin (JSON with hook_event_name)
+ *   - If hook_event_name === "SessionStart" → consume inbox and outputContext("SessionStart", ...)
+ *   - Backward compat: if process.stdin.isTTY → skip stdin read (PostToolUse path)
+ */
+
+import { readdirSync, readFileSync, unlinkSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { log, outputContext } from "./lib/api-client.js";
+
+const HOOK = "MAILBOX-LISTENER";
+
+// --- Types (minimal, no Zod dependency in hooks) ---
+
+interface MailboxMessage {
+  id: string;
+  from: { role: string; index: number };
+  to: { role: string; index: number };
+  timestamp: string;
+  body: {
+    type: string;
+    taskId?: string;
+    title?: string;
+    description?: string;
+    summary?: string;
+    progress?: number;
+    message?: string;
+    errorCode?: string;
+    acceptanceCriteria?: string[];
+  };
+}
+
+// --- Stdin reader (same pattern as sprint-registry.ts) ---
+
+async function readStdinPayload(): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+// --- Core inbox consumption logic (shared between SessionStart and PostToolUse) ---
+
+function consumeInbox(
+  inboxPath: string,
+  quarantinePath: string,
+  paneRole: string,
+): { consumed: MailboxMessage[]; errors: string[] } {
+  // List .json files (exclude .tmp- in-flight writes)
+  let files: string[];
+  try {
+    files = readdirSync(inboxPath)
+      .filter((f) => f.endsWith(".json") && !f.startsWith(".tmp-"))
+      .sort(); // FIFO by filename (UUID-based, but sorted for determinism)
+  } catch {
+    return { consumed: [], errors: [] }; // Directory read error — fail silently
+  }
+
+  if (files.length === 0) {
+    return { consumed: [], errors: [] };
+  }
+
+  log(HOOK, `${files.length} message(s) in ${paneRole} inbox`);
+
+  const consumed: MailboxMessage[] = [];
+  const errors: string[] = [];
+
+  for (const file of files) {
+    const filePath = join(inboxPath, file);
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(raw) as MailboxMessage;
+
+      // Basic validation (no Zod in hooks — keep deps minimal)
+      if (!parsed.id || !parsed.from || !parsed.to || !parsed.body?.type) {
+        throw new Error(`Invalid envelope: missing required fields`);
+      }
+
+      // Consume: delete after successful parse
+      unlinkSync(filePath);
+      consumed.push(parsed);
+      log(HOOK, `Consumed: ${parsed.id} (${parsed.body.type} from ${parsed.from.role}-${parsed.from.index})`);
+    } catch (err) {
+      // Quarantine malformed message
+      const errMsg = err instanceof Error ? err.message : String(err);
+      errors.push(`${file}: ${errMsg}`);
+      log(HOOK, `Quarantine: ${file} — ${errMsg}`);
+      try {
+        mkdirSync(quarantinePath, { recursive: true });
+        renameSync(filePath, join(quarantinePath, file));
+      } catch {
+        // Best-effort quarantine
+      }
+    }
+  }
+
+  return { consumed, errors };
+}
+
+// --- Context builder (shared between SessionStart and PostToolUse) ---
+
+function buildContext(
+  consumed: MailboxMessage[],
+  errors: string[],
+  paneRole: string,
+): string | null {
+  if (consumed.length === 0 && errors.length === 0) {
+    return null;
+  }
+
+  const parts: string[] = [
+    `[MAILBOX] ${consumed.length} new message(s) for ${paneRole}:`,
+  ];
+
+  for (const msg of consumed) {
+    const from = `${msg.from.role}-${msg.from.index}`;
+    parts.push("");
+    parts.push(`--- Message from ${from} (${msg.body.type}) ---`);
+
+    switch (msg.body.type) {
+      case "task_assignment":
+        parts.push(`Task: ${msg.body.taskId}`);
+        parts.push(`Title: ${msg.body.title}`);
+        if (msg.body.description) parts.push(`Description: ${msg.body.description}`);
+        if (msg.body.acceptanceCriteria?.length) {
+          parts.push(`Acceptance Criteria:`);
+          for (const ac of msg.body.acceptanceCriteria) {
+            parts.push(`  - ${ac}`);
+          }
+        }
+        break;
+
+      case "task_complete":
+        parts.push(`Task: ${msg.body.taskId}`);
+        parts.push(`Summary: ${msg.body.summary}`);
+        break;
+
+      case "status_update":
+        parts.push(`Task: ${msg.body.taskId}`);
+        parts.push(`Progress: ${msg.body.progress}%`);
+        parts.push(`Status: ${msg.body.message}`);
+        break;
+
+      case "error_report":
+        parts.push(`Error: ${msg.body.errorCode}`);
+        parts.push(`Message: ${msg.body.message}`);
+        if (msg.body.taskId) parts.push(`Task: ${msg.body.taskId}`);
+        break;
+
+      case "ping":
+        parts.push(`Ping received — respond with pong if appropriate.`);
+        break;
+
+      case "pong":
+        parts.push(`Pong received — heartbeat confirmed.`);
+        break;
+
+      default:
+        parts.push(`Type: ${msg.body.type}`);
+        parts.push(`Raw: ${JSON.stringify(msg.body)}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    parts.push("");
+    parts.push(`[MAILBOX-WARN] ${errors.length} malformed message(s) quarantined:`);
+    for (const e of errors) {
+      parts.push(`  - ${e}`);
+    }
+  }
+
+  return parts.join("\n");
+}
+
+// --- Main ---
+
+async function main(): Promise<void> {
+  const sprintId = process.env.SPRINT_ID;
+  const paneRole = process.env.PANE_ROLE;
+
+  // Not in a sprint — exit silently (zero overhead path)
+  if (!sprintId || !paneRole) {
+    return;
+  }
+
+  const inboxPath = `/tmp/${sprintId}/mailbox/${paneRole}/inbox`;
+  const quarantinePath = `/tmp/${sprintId}/mailbox/${paneRole}/quarantine`;
+
+  // No inbox directory — sprint may not have mailbox enabled
+  if (!existsSync(inboxPath)) {
+    return;
+  }
+
+  // Determine hook event: read stdin unless this is an interactive TTY (PostToolUse path)
+  let hookEventName: string | undefined;
+  if (!process.stdin.isTTY) {
+    try {
+      const payload = await readStdinPayload();
+      hookEventName = payload.hook_event_name as string | undefined;
+    } catch {
+      // Stdin read failure — fall through to PostToolUse behaviour
+    }
+  }
+
+  // Consume inbox
+  const { consumed, errors } = consumeInbox(inboxPath, quarantinePath, paneRole);
+
+  if (consumed.length === 0 && errors.length === 0) {
+    return;
+  }
+
+  // Build context string
+  const context = buildContext(consumed, errors, paneRole);
+  if (!context) {
+    return;
+  }
+
+  // Emit context with the appropriate hook event name
+  const effectiveEvent = hookEventName === "SessionStart" ? "SessionStart" : "PostToolUse";
+  outputContext(effectiveEvent, context);
+}
+
+void main();

package/dist/templates/base/claude/hooks/sprint-registry.ts

@@ -0,0 +1,85 @@
+/**
+ * sprint-registry.ts — SessionStart self-registration hook (RFC-025 M4)
+ *
+ * Reads SPRINT_ID and PANE_ROLE from environment, then writes a registry
+ * entry to /tmp/sprint-<SPRINT_ID>/registry/<PANE_ROLE>.json.
+ *
+ * IMPORTANT: No imports from scripts/lib/ — uses raw Node.js fs only.
+ * This hook runs in isolated worktree environments where scripts/lib may
+ * not be available on the module resolution path.
+ *
+ * Hook input (stdin): Claude Code SessionStart JSON payload (ignored).
+ * Exit 0 always — registration failure must not block the session.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function log(msg: string): void {
+  process.stderr.write(`[sprint-registry] ${msg}\n`);
+}
+
+/** Read hook JSON payload from stdin (async, same pattern as api-client.ts). */
+async function readStdin(): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  const raw = Buffer.concat(chunks).toString('utf-8').trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+async function main(): Promise<void> {
+  // Read SessionStart payload from stdin — contains session_id
+  const stdin = await readStdin();
+  const sessionId = (stdin.session_id as string) ?? undefined;
+
+
+  // Read required env vars
+  const sprintId = process.env['SPRINT_ID'];
+  const paneRole = process.env['PANE_ROLE'];
+
+  if (!sprintId || !paneRole) {
+    log(`Skipping: SPRINT_ID=${sprintId ?? 'unset'} PANE_ROLE=${paneRole ?? 'unset'}`);
+    process.exit(0);
+  }
+
+  const registryDir = `/tmp/${sprintId}/registry`;
+  const entryPath = join(registryDir, `${paneRole}.json`);
+
+  const workflowId = process.env['WORKFLOW_ID'];
+
+  const entry: Record<string, unknown> = {
+    role: paneRole,
+    sprintId,
+    pid: process.pid,
+    registeredAt: new Date().toISOString(),
+    worktreePath: process.cwd(),
+  };
+
+  if (sessionId) {
+    entry.sessionId = sessionId;
+  }
+
+  if (workflowId) {
+    entry.workflowId = workflowId;
+  }
+
+  try {
+    mkdirSync(registryDir, { recursive: true });
+    writeFileSync(entryPath, JSON.stringify(entry, null, 2), 'utf-8');
+    log(`Registered ${paneRole} for sprint ${sprintId} (pid=${process.pid}, session=${sessionId ?? 'unknown'})`);
+  } catch (err) {
+    // Log but do not fail — registration is best-effort
+    log(`Registration failed: ${err}`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/dist/templates/base/claude/settings.json

@@ -46,6 +46,12 @@
             "command": "npx tsx .claude/hooks/session-start.ts",
             "timeout": 10000,
             "on_failure": "ignore"
+          },
+          {
+            "type": "command",
+            "command": "npx tsx .claude/hooks/sprint-registry.ts",
+            "timeout": 5000,
+            "on_failure": "ignore"
           }
         ]
       }
@@ -126,6 +132,19 @@
         ]
       }
     ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx tsx .claude/hooks/mailbox-listener.ts",
+            "timeout": 5000,
+            "on_failure": "ignore"
+          }
+        ]
+      }
+    ],
     "PostCompact": [
       {
         "matcher": "",

package/dist/templates/base/claude/skills/sprint-launch/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: sprint-launch
+description: >
+  Launch parallel Claude sessions in tmux for sprint execution.
+  Use when starting a sprint with independent tasks that benefit from parallel panes.
+  Supports duo, duo-doc, squad, squad-review, platoon, and platoon-full presets
+  covering 2 to 5+ pane configurations.
+argument-hint: <preset> [workflow-id]
+---
+
+# Sprint Launcher — RFC-025 v2
+
+Launch parallel Claude sessions in tmux panes, each isolated in a git worktree, to execute sprint tasks concurrently.
+
+## When to Use
+
+- Starting a sprint with 1-5 independent task tracks
+- You want parallel agent sessions with worktree isolation
+- RFC-021 Sprints, ADR-017 phases, or any feature work with clear task separation
+
+## Prerequisites
+
+Before launching, verify:
+1. **tmux** is installed and on PATH (`tmux -V`)
+2. **claude** CLI is on PATH (`claude --version`)
+3. **git** repo is clean (no uncommitted changes that could conflict with worktrees)
+4. An active workflow exists (or you have a workflowId)
+
+## Presets
+
+| Preset | Panes | Composition | Use When |
+|--------|-------|-------------|----------|
+| `duo` | 1 | 1 implementer | Simple sprint, 1 task track |
+| `duo-doc` | 2 | 1 implementer + 1 doc-sidecar | Documentation-heavy work |
+| `squad` | 3 | 2 implementers + 1 debug-sidecar | 2 parallel tracks with review |
+| `squad-review` | 3 | 1 implementer + 1 debug-sidecar + 1 doc-sidecar | Quality-critical single track |
+| `platoon` | 5 | 3 implementers + 1 reviewer + 1 debug-sidecar | 3 parallel tracks with review |
+| `platoon-full` | 7 | 2 implementers + 2 doc-sidecars + 1 debug-sidecar + 1 test-sidecar + 1 reviewer | Complex sprint with full observability |
+
+## Protocol
+
+**IMPORTANT: Always confirm with the user before launching.**
+
+### Step 1: Gather Parameters
+
+Parse from user input or active workflow context:
+- **preset**: one of the 6 presets above (required)
+- **workflowId**: from active workflow or user input (optional — script generates one if missing)
+
+### Step 2: Confirm via AskUserQuestion
+
+Before executing anything, present the launch plan:
+
+```
+AskUserQuestion({
+  question: "Sprint Launch: {preset} preset\n\nSession: sprint-{wfId:0:8}\nPanes: {pane descriptions}\nWorktrees: ../wt-sprint-{wfId:0:8}-{0,1,...}\n\nProceed?",
+  options: ["Launch", "Change preset", "Cancel"]
+})
+```
+
+### Step 3: Execute
+
+On user approval, run via TypeScript launcher:
+
+```bash
+npx tsx scripts/sprint-launch.ts {preset} {workflowId}
+
+# With task distribution (--task is repeatable, round-robin to implementer panes):
+npx tsx scripts/sprint-launch.ts {preset} {workflowId} --mailbox \
+  --task "TASK-001: Implement auth endpoint" \
+  --task "TASK-002: Write integration tests"
+
+# With tasks fetched from REST API (graceful fallback if API unavailable):
+npx tsx scripts/sprint-launch.ts {preset} {workflowId} --mailbox --fetch-tasks
+```
+
+### Step 4: Auto-attach
+
+The script automatically attaches after launching panes and injecting startup prompts:
+
+- **Inside tmux**: opens a horizontal split pointing at the new session — zero user action required
+- **Outside tmux**: prints the attach command to console, e.g. `tmux attach -t sprint-{prefix}`
+
+Startup prompts are injected into each pane automatically. If a pane fails to receive its prompt, auto-attach still proceeds.
+
+## Task Distribution
+
+When launching with tasks, the launcher distributes them **round-robin to implementer panes only**.
+Sidecar agents (doc-sidecar, debug-sidecar, test-sidecar) react to implementer progress via mailbox
+and do not receive direct task_assignment messages from the launcher.
+
+### --task flag (repeatable)
+
+```bash
+--task "TASK-001: Title"
+```
+
+- Parses `TASK-001` as `taskId` and `Title` as `title`
+- Produces a `task_assignment` mailbox message with `description: ''` and `acceptanceCriteria: []`
+- Tasks are distributed round-robin: task[0] → implementer[0], task[1] → implementer[1], task[2] → implementer[0], etc.
+- The task title is also injected into the pane's CLAUDE.md as a hint (via WorktreeIsolator)
+
+### --fetch-tasks flag
+
+```bash
+--fetch-tasks
+```
+
+- Calls `GET /api/workflows/{workflowId}/tasks` on the configured REST API (`ORCHESTRATOR_API_URL` env var, default `http://localhost:3000`)
+- Appends fetched tasks to any `--task` CLI tasks
+- Graceful fallback: if the API is unreachable or returns an error, prints a warning and continues with CLI tasks only
+
+### Agent Protocol
+
+Agents receive tasks via the sprint-teammate skill. See `.claude/skills/sprint-teammate/sprint-teammate.md`.
+
+## Critical Rules
+
+1. **NEVER use `--bare` for implementer panes** — `--bare` suppresses hooks, skills, and MCP tools. Implementers MUST have access to these. The script uses `claude -p` (without `--bare`).
+2. **Always confirm before launching** — never auto-launch panes.
+3. **Worktrees are cleaned up on exit** — the script traps EXIT/SIGINT/SIGTERM and removes worktrees if interrupted.
+4. **ANTHROPIC_API_KEY warning** — if unset, script warns but continues (Max OAuth mode assumed).
+
+## Monitoring
+
+After launch, check pane health:
+
+```bash
+# Single check
+./scripts/sprint-status.sh sprint-{prefix} --once
+
+# Continuous monitoring (10s interval)
+./scripts/sprint-status.sh sprint-{prefix}
+
+# Custom interval
+POLL_INTERVAL=5 ./scripts/sprint-status.sh sprint-{prefix}
+```
+
+Output shows ALIVE (green) or DEAD (red) per pane.
+
+## Cleanup
+
+Worktrees are auto-cleaned on script exit. If a crash leaves orphans:
+
+```bash
+git worktree prune
+git worktree list  # verify no wt-sprint-* remain
+```
+
+To kill a running sprint session:
+
+```bash
+tmux kill-session -t sprint-{prefix}
+```
+
+## Examples
+
+```bash
+# Simple sprint with 1 implementer (auto-attaches)
+/sprint-launch duo
+
+# Documentation-heavy sprint
+/sprint-launch duo-doc adaaa9a4-ef49-4e26-af14-2b239f62b40c
+
+# 2 parallel tracks
+/sprint-launch squad
+
+# 2 tracks with reviewer sidecar
+/sprint-launch squad-review adaaa9a4-ef49-4e26-af14-2b239f62b40c
+
+# 3 parallel tracks
+/sprint-launch platoon
+
+# 3 tracks with reviewer sidecar
+/sprint-launch platoon-full adaaa9a4-ef49-4e26-af14-2b239f62b40c
+```

package/dist/templates/base/claude/skills/sprint-teammate/sprint-teammate.md

@@ -0,0 +1,79 @@
+# Sprint Teammate Protocol
+
+You are a focused sprint agent. Read this protocol at session start.
+
+## Identity Guard
+
+Check `process.env.SPRINT_ID`. If set, you are in a sprint session.
+Your role is `process.env.PANE_ROLE`. Your inbox is:
+`/tmp/{SPRINT_ID}/mailbox/{PANE_ROLE}/inbox/`
+
+## On Session Start
+
+1. Read your CLAUDE.md for sprint context (session, workflow, task hint).
+2. Check your inbox for any `task_assignment` messages.
+3. If a task is assigned: **execute immediately** — no greeting, no questions.
+4. If inbox is empty: wait. The mailbox-listener hook will inject messages as they arrive.
+
+## Message Types
+
+### Receiving: task_assignment
+```json
+{
+  "type": "task_assignment",
+  "taskId": "TASK-001",
+  "title": "Short title",
+  "description": "Full description",
+  "acceptanceCriteria": ["criterion 1", "criterion 2"]
+}
+```
+On receipt: start implementation immediately. No acknowledgement needed.
+
+### Sending: task_complete
+```json
+{
+  "type": "task_complete",
+  "taskId": "TASK-001",
+  "summary": "What was done and where"
+}
+```
+Write to: `/tmp/{SPRINT_ID}/mailbox/orchestrator-0/inbox/{uuid}.json`
+
+### Sending: status_update
+```json
+{
+  "type": "status_update",
+  "taskId": "TASK-001",
+  "progress": 50,
+  "message": "Tests written, implementing..."
+}
+```
+
+### Sending: error_report
+```json
+{
+  "type": "error_report",
+  "errorCode": "BLOCKER",
+  "message": "Cannot proceed because...",
+  "taskId": "TASK-001"
+}
+```
+
+## Mailbox Paths
+
+| Direction | Path |
+|-----------|------|
+| Your inbox | `/tmp/{SPRINT_ID}/mailbox/{PANE_ROLE}/inbox/` |
+| Orchestrator | `/tmp/{SPRINT_ID}/mailbox/orchestrator-0/inbox/` |
+| Other pane | `/tmp/{SPRINT_ID}/mailbox/{role}-{index}/inbox/` |
+
+Envelope format: `{ "id": "<uuid>", "from": {"role": "...", "index": N}, "to": {"role": "...", "index": N}, "timestamp": "<ISO>", "body": {...} }`
+
+## Self-Guarding Rules
+
+- MUST NOT greet users or ask "What would you like to do?"
+- MUST NOT invoke workflow MCP tools (advancePhase, completeWorkflow)
+- MUST NOT spawn sub-agents
+- MUST execute task_assignment immediately upon receipt
+- MUST send task_complete when done
+- MUST send error_report if blocked (do not silently stall)