@orchestrator-claude/cli 3.25.2 → 3.27.0

package/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/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/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)

package/templates/base/scripts/lib/SprintLauncher.ts

@@ -0,0 +1,325 @@
+/**
+ * SprintLauncher.ts — Orchestrates the full sprint session launch (RFC-025)
+ *
+ * Responsibilities:
+ *   1. Validate prerequisites (tmux on PATH, claude on PATH, no duplicate session)
+ *   2. Prune stale worktrees
+ *   3. Create worktrees via WorktreeManager (one per pane)
+ *   4. Isolate each worktree via WorktreeIsolator
+ *   5. Launch tmux session via TmuxManager
+ *   6. Return LaunchResult
+ *
+ * DI via factory function — same pattern as gate-guardian.ts (ADR-017 Phase 4).
+ * execSync is injected for testability; in production use child_process.execSync.
+ * Input values (preset, workflowId) are validated before use in shell commands.
+ */
+
+import type { WorktreeManager } from './WorktreeManager.js';
+import type { WorktreeIsolator } from './WorktreeIsolator.js';
+import type { TmuxManager, PaneLaunchConfig } from './TmuxManager.js';
+import { SprintPreset } from '../../src/domain/value-objects/SprintLayout.js';
+import type { PaneConfig } from '../../src/domain/value-objects/SprintLayout.js';
+import type { generateLayout as GenerateLayoutFn } from '../../src/domain/value-objects/generateLayout.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Milliseconds to wait after launchLayout before sending activation prompts.
+ * Claude Code needs ~5-8 seconds to boot and display the ❯ prompt.
+ */
+export const BOOT_DELAY_MS = 7000;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+import type { MailboxAddress, MessageEnvelope } from './mailbox/types.js';
+
+/** Minimal MailboxManager interface required by SprintLauncher. */
+export interface MailboxManager {
+  /** Create mailbox inbox directories for each role in the sprint. */
+  init(addresses: readonly MailboxAddress[]): void;
+  /**
+   * Send a message envelope to the address encoded in envelope.to.
+   * Matches MailboxManager.sendMessage(envelope) from MailboxManager.ts.
+   */
+  sendMessage(envelope: MessageEnvelope): void;
+}
+
+export interface SprintTask {
+  taskId: string;
+  title: string;
+  description: string;
+  acceptanceCriteria: string[];
+}
+
+export interface LaunchResult {
+  sessionName: string;
+  workflowId: string;
+  preset: string;
+  worktreePaths: readonly string[];
+}
+
+export interface SprintLauncherDeps {
+  worktreeManager: WorktreeManager;
+  worktreeIsolator: WorktreeIsolator;
+  tmuxManager: TmuxManager;
+  generateLayout: typeof GenerateLayoutFn;
+  execSync: (cmd: string, opts?: object) => string | Buffer;
+  projectRoot: string;
+  /** Optional mailbox manager — initialises inbox directories before launch. */
+  mailboxManager?: MailboxManager;
+  /**
+   * Optional delay function — defaults to real setTimeout-based delay.
+   * Inject a no-op `() => Promise.resolve()` in tests to avoid 7s waits.
+   */
+  delay?: (ms: number) => Promise<void>;
+}
+
+export interface SprintLauncher {
+  launch(presetName: string, workflowId: string, tasks?: SprintTask[]): Promise<LaunchResult>;
+  cleanup(sessionName: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when the agent role is a reactive sidecar (RFC-025 v3.3).
+ * Sidecars launch as Node.js watcher processes instead of interactive claude sessions.
+ * Implementers, reviewers, and other roles remain interactive.
+ */
+function isSidecarRole(role: string): boolean {
+  return role.includes('sidecar');
+}
+
+/**
+ * Builds the shell command for a reactive sidecar pane.
+ * Launches the SidecarWatcher script which watches the mailbox inbox
+ * and spawns Agent SDK query() calls on demand.
+ *
+ * The inbox path matches MailboxManager's layout: `/tmp/{sessionName}/mailbox/{role}-{index}/inbox`
+ *
+ * NOTE: The script runs from `projectRoot` (not the worktree) so that node_modules
+ * are available for chokidar and SDK imports. The worktree is passed as --worktree
+ * and used as cwd for the SDK query() call.
+ */
+function buildSidecarCommand(agentSlug: string, worktreePath: string, sessionName: string, mailboxRole: string, paneIndex: number, projectRoot: string): string {
+  const inboxPath = `/tmp/${sessionName}/mailbox/${mailboxRole}-${paneIndex}/inbox`;
+  return `cd "${projectRoot}" && npx tsx scripts/lib/sidecar/run.ts --inbox "${inboxPath}" --worktree "${worktreePath}" --agent ${agentSlug}`;
+}
+
+export function createSprintLauncher(deps: SprintLauncherDeps): SprintLauncher {
+  const { worktreeManager, worktreeIsolator, tmuxManager, generateLayout, execSync, mailboxManager } = deps;
+  const delay = deps.delay ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  function validatePrerequisites(sessionName: string): void {
+    // Validate tmux is on PATH (static command — no user input)
+    try {
+      execSync('which tmux', { stdio: 'pipe' });
+    } catch {
+      throw new Error(
+        'tmux is not on PATH. Install tmux to use sprint-launch.',
+      );
+    }
+
+    // Validate claude is on PATH (static command — no user input)
+    try {
+      execSync('which claude', { stdio: 'pipe' });
+    } catch {
+      throw new Error(
+        'claude is not on PATH. Install Claude Code CLI to use sprint-launch.',
+      );
+    }
+
+    // Guard against duplicate session via TmuxManager (no shell exec here)
+    if (tmuxManager.hasSession(sessionName)) {
+      throw new Error(
+        `tmux session '${sessionName}' already exists. Attach with: tmux attach -t ${sessionName}`,
+      );
+    }
+  }
+
+  async function launch(presetName: string, workflowId: string, tasks?: SprintTask[]): Promise<LaunchResult> {
+    // 1. Validate preset (validates input before any use in commands)
+    const presetResult = SprintPreset.create(presetName);
+    if (presetResult.isErr()) {
+      throw new Error(`Invalid preset: ${presetResult.error}`);
+    }
+    const preset = presetResult.value;
+
+    // 2. Derive session name
+    const sessionName = `sprint-${workflowId.slice(0, 8)}`;
+
+    // 3. Validate prerequisites
+    validatePrerequisites(sessionName);
+
+    // 4. Generate layout
+    const layoutResult = generateLayout(preset, workflowId);
+    if (layoutResult.isErr()) {
+      throw new Error(`Failed to generate layout: ${layoutResult.error}`);
+    }
+    const layout = layoutResult.value;
+
+    // 5. Initialise mailbox inbox directories (before worktree prune)
+    if (mailboxManager) {
+      const addresses: MailboxAddress[] = layout.panes.map((p: PaneConfig, i: number) => ({
+        role: p.context.mailboxRole as MailboxAddress['role'],
+        index: i,
+      }));
+      mailboxManager.init(addresses);
+    }
+
+    // 6. Prune stale worktrees
+    worktreeManager.prune();
+
+    // 7. Create worktrees (one per pane, indexed)
+    const worktreePaths: string[] = [];
+    for (let i = 0; i < layout.panes.length; i++) {
+      const worktreePath = worktreeManager.addWorktree(i, sessionName);
+      worktreePaths.push(worktreePath);
+    }
+
+    // 8. Build round-robin task assignment map (implementer panes only).
+    //    PaneConfig is frozen — use a separate Map to track assignments.
+    const paneTaskMap = new Map<number, SprintTask>();
+    if (tasks && tasks.length > 0) {
+      const implementerIndices = layout.panes
+        .map((pane: PaneConfig, i: number) => ({ pane, i }))
+        .filter(({ pane }) => pane.agent.includes('implementer'))
+        .map(({ i }) => i);
+
+      for (let t = 0; t < tasks.length; t++) {
+        const paneIndex = implementerIndices[t % implementerIndices.length];
+        if (paneIndex !== undefined) {
+          paneTaskMap.set(paneIndex, tasks[t]);
+        }
+      }
+    }
+
+    // 9. Isolate each worktree — inject sprint context into CLAUDE.md
+    //    so agents know their workflow, mailbox, and task at startup.
+    //    Zero tmux input needed (TD-133 resolved via CLAUDE.md injection).
+    for (let i = 0; i < layout.panes.length; i++) {
+      const pane = layout.panes[i];
+      const assignedTask = paneTaskMap.get(i);
+      worktreeIsolator.isolateWorktree(pane.agent, worktreePaths[i], {
+        sessionName,
+        workflowId,
+        mailboxRole: `${pane.context.mailboxRole}-${i}`,
+        task: assignedTask?.title ?? pane.context.task,
+      });
+    }
+
+    // 10. Send task assignment messages to agents via mailbox (before launch)
+    if (mailboxManager) {
+      for (let i = 0; i < layout.panes.length; i++) {
+        const pane = layout.panes[i];
+        const assignedTask = paneTaskMap.get(i);
+
+        // Use assigned SprintTask if available, otherwise fall back to pane.context.task
+        if (assignedTask) {
+          const address: MailboxAddress = {
+            role: pane.context.mailboxRole as MailboxAddress['role'],
+            index: i,
+          };
+          const envelope: MessageEnvelope = {
+            id: crypto.randomUUID(),
+            from: { role: 'orchestrator', index: 0 },
+            to: address,
+            timestamp: new Date().toISOString(),
+            body: {
+              type: 'task_assignment',
+              taskId: assignedTask.taskId,
+              title: assignedTask.title,
+              description: assignedTask.description,
+              acceptanceCriteria: assignedTask.acceptanceCriteria,
+            },
+          };
+          mailboxManager.sendMessage(envelope);
+        } else if (pane.context.task) {
+          const address: MailboxAddress = {
+            role: pane.context.mailboxRole as MailboxAddress['role'],
+            index: i,
+          };
+          const envelope: MessageEnvelope = {
+            id: crypto.randomUUID(),
+            from: { role: 'orchestrator', index: 0 },
+            to: address,
+            timestamp: new Date().toISOString(),
+            body: {
+              type: 'task_assignment',
+              taskId: `task-${i}`,
+              title: pane.context.task,
+              description: '',
+              acceptanceCriteria: [],
+            },
+          };
+          mailboxManager.sendMessage(envelope);
+        }
+      }
+    }
+
+    // 11. Build PaneLaunchConfig[] for TmuxManager (no initialPrompt needed)
+    //     Sidecar panes get a custom `command` that launches the reactive watcher
+    //     instead of an interactive `claude --agent` session (RFC-025 v3.3).
+    const paneLaunchConfigs: PaneLaunchConfig[] = layout.panes.map((pane: PaneConfig, i: number) => {
+      const config: PaneLaunchConfig = {
+        role: pane.agent,
+        workdir: worktreePaths[i],
+        sprintId: sessionName,
+        paneRole: `${pane.context.mailboxRole}-${i}`,
+      };
+      if (isSidecarRole(pane.agent)) {
+        config.command = buildSidecarCommand(
+          pane.agent,
+          worktreePaths[i],
+          sessionName,
+          pane.context.mailboxRole as string,
+          i,
+          deps.projectRoot,
+        );
+      }
+      return config;
+    });
+
+    // 12. Launch tmux session (interactive mode — TUI visible, context from CLAUDE.md)
+    tmuxManager.launchLayout(sessionName, paneLaunchConfigs);
+
+    // 12a. Wait for Claude to boot then activate implementer panes.
+    //      Sidecars stay idle — they respond reactively in a future version.
+    const implementerIndicesForActivation = paneLaunchConfigs
+      .map((pane, i) => ({ pane, i }))
+      .filter(({ pane }) => pane.role.includes('implementer'))
+      .map(({ i }) => i);
+
+    if (implementerIndicesForActivation.length > 0) {
+      // eslint-disable-next-line no-console
+      console.log('[sprint-launch] Activating implementer panes...');
+      await delay(BOOT_DELAY_MS);
+      for (const paneIndex of implementerIndicesForActivation) {
+        tmuxManager.sendPromptLiteral(sessionName, paneIndex, 'siga');
+      }
+    }
+
+    // 13. Auto-attach for seamless UX
+    tmuxManager.autoAttach(sessionName);
+
+    return {
+      sessionName,
+      workflowId,
+      preset: preset.value,
+      worktreePaths: Object.freeze(worktreePaths),
+    };
+  }
+
+  function cleanup(sessionName: string): void {
+    worktreeManager.removeAll(sessionName);
+    tmuxManager.killSession(sessionName);
+  }
+
+  return { launch, cleanup };
+}