@orchestrator-claude/cli 3.25.1 → 3.26.0

package/dist/templates/base/scripts/lib/sidecar/run.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env npx tsx
+/**
+ * run.ts — CLI entry point for the reactive sidecar watcher (RFC-025 v3.3)
+ *
+ * Launched by TmuxManager in sidecar panes. Parses CLI args, creates a
+ * SidecarWatcher, and runs until SIGTERM/SIGINT.
+ *
+ * Usage:
+ *   npx tsx scripts/lib/sidecar/run.ts --inbox /path/to/inbox --worktree /path/to/wt --agent doc-sidecar
+ */
+
+import { createSidecarWatcher } from './SidecarWatcher.js';
+import { parseArgs } from 'node:util';
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const { values } = parseArgs({
+  options: {
+    inbox: { type: 'string' },
+    worktree: { type: 'string' },
+    agent: { type: 'string' },
+  },
+  strict: true,
+});
+
+if (!values.inbox || !values.worktree || !values.agent) {
+  // eslint-disable-next-line no-console
+  console.error('Usage: npx tsx run.ts --inbox <path> --worktree <path> --agent <slug>');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Force OAuth/Claude Max — strip API keys from process.env BEFORE any SDK use.
+// The SDK reads process.env internally; passing `env` in query() options alone
+// is not sufficient. This mirrors `env -u ANTHROPIC_API_KEY` from TmuxManager.
+// ---------------------------------------------------------------------------
+
+const API_KEY_VARS = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY'] as const;
+for (const key of API_KEY_VARS) {
+  if (process.env[key]) {
+    // eslint-disable-next-line no-console
+    console.log(`[sidecar:${values.agent}] Stripping ${key} from env to force OAuth`);
+    delete process.env[key];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Resilience: prevent unhandled rejections from killing the watcher.
+// The SDK's internal chokidar/inotify errors (ENOSPC) are non-fatal —
+// they surface as unhandled rejections and must not crash the process.
+// ---------------------------------------------------------------------------
+
+process.on('unhandledRejection', (reason) => {
+  // eslint-disable-next-line no-console
+  console.error(
+    `[sidecar:${values.agent}] Unhandled rejection (non-fatal):`,
+    reason instanceof Error ? reason.message : String(reason),
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Start watcher
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line no-console
+console.log(`[sidecar:${values.agent}] Starting reactive watcher on ${values.inbox}`);
+
+const watcher = createSidecarWatcher({
+  inboxPath: values.inbox,
+  worktreePath: values.worktree,
+  agentSlug: values.agent,
+});
+
+watcher.start();
+
+// ---------------------------------------------------------------------------
+// Graceful shutdown
+// ---------------------------------------------------------------------------
+
+async function shutdown(signal: string): Promise<void> {
+  // eslint-disable-next-line no-console
+  console.log(`[sidecar:${values.agent}] Received ${signal}, shutting down...`);
+  await watcher.stop();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => void shutdown('SIGTERM'));
+process.on('SIGINT', () => void shutdown('SIGINT'));

package/dist/templates/base/scripts/sprint-launch.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env npx tsx
+/**
+ * sprint-launch.ts — TypeScript CLI entry point for RFC-025 Sprint Launcher
+ *
+ * Usage:
+ *   npx tsx scripts/sprint-launch.ts <preset> [workflowId]
+ *
+ * Presets:
+ *   duo          — 1 implementer pane
+ *   duo-doc      — 1 implementer + 1 doc-sidecar pane
+ *   squad        — 2 implementers + 1 debug-sidecar pane
+ *   squad-review — 1 implementer + 1 debug-sidecar + 1 doc-sidecar pane
+ *   platoon      — 3 implementers + 1 reviewer + 1 debug-sidecar pane
+ *   platoon-full — 2 implementers + 2 doc-sidecars + 1 debug-sidecar + 1 test-sidecar + 1 reviewer pane
+ */
+
+import * as childProcess from 'child_process';
+import * as crypto from 'crypto';
+import { createWorktreeManager } from './lib/WorktreeManager.js';
+import { createWorktreeIsolator } from './lib/WorktreeIsolator.js';
+import { createTmuxManager } from './lib/TmuxManager.js';
+import { createSprintLauncher } from './lib/SprintLauncher.js';
+import type { SprintTask } from './lib/SprintLauncher.js';
+import { createMailboxManager } from './lib/mailbox/MailboxManager.js';
+import { generateLayout } from '../src/domain/value-objects/generateLayout.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const VERSION = '1.0.0';
+const VALID_PRESETS = [
+  'duo',
+  'duo-doc',
+  'squad',
+  'squad-review',
+  'platoon',
+  'platoon-full',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * parseTaskFlags — Extract SprintTask objects from CLI args.
+ *
+ * Supports:
+ *   --task "TASK-001: Title text"  (separate value)
+ *   --task=TASK-001: Title text    (equals-sign form)
+ *
+ * When the value has a colon, everything before the first colon is the taskId
+ * (trimmed) and everything after is the title (trimmed).
+ * When there is no colon, a generated taskId is used and the full string is the title.
+ */
+export function parseTaskFlags(args: string[]): SprintTask[] {
+  const tasks: SprintTask[] = [];
+  let taskCounter = 0;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    let value: string | undefined;
+
+    if (arg === '--task' && i + 1 < args.length) {
+      value = args[i + 1];
+      i++; // consume next arg
+    } else if (arg.startsWith('--task=')) {
+      value = arg.slice('--task='.length);
+    }
+
+    if (value !== undefined) {
+      const colonIdx = value.indexOf(':');
+      let taskId: string;
+      let title: string;
+      if (colonIdx !== -1) {
+        taskId = value.slice(0, colonIdx).trim();
+        title = value.slice(colonIdx + 1).trim();
+      } else {
+        taskCounter++;
+        taskId = `task-${taskCounter}`;
+        title = value.trim();
+      }
+      tasks.push({ taskId, title, description: '', acceptanceCriteria: [] });
+    }
+  }
+
+  return tasks;
+}
+
+function printUsage(): void {
+  console.log(`sprint-launch.ts v${VERSION} — RFC-025 Sprint Launcher
+
+Usage:
+  npx tsx scripts/sprint-launch.ts <preset> [workflowId] [--mailbox] [--task "..."]
+
+Presets:
+  duo          1 implementer pane (orchestrator = calling session)
+  duo-doc      1 implementer + 1 doc-sidecar pane (orchestrator = calling session)
+  squad        2 implementers + 1 debug-sidecar pane
+  squad-review 1 implementer + 1 debug-sidecar + 1 doc-sidecar pane
+  platoon      3 implementers + 1 reviewer + 1 debug-sidecar pane
+  platoon-full 2 implementers + 2 doc-sidecars + 1 debug-sidecar + 1 test-sidecar + 1 reviewer pane
+
+Arguments:
+  preset      Required. One of: ${VALID_PRESETS.join(', ')}
+  workflowId  Optional. UUID of the active workflow (default: generated random UUID)
+
+Flags:
+  --mailbox              Enable mailbox protocol: creates /tmp/<session>/mailbox/<role>/inbox/ for each pane.
+  --task "ID: Title"     Assign a task to the next implementer pane (repeatable, round-robin).
+                         Example: --task "TASK-001: Implement auth" --task "TASK-002: Write tests"
+  --fetch-tasks          Fetch tasks from the REST API (graceful fallback if unavailable).
+
+Task Distribution:
+  Tasks are distributed round-robin to implementer panes only.
+  Sidecar agents (doc-sidecar, debug-sidecar, test-sidecar) receive tasks via mailbox reactions,
+  not via direct assignment. Each implementer pane gets one task per round.
+  Reference: sprint-teammate skill for agent-side protocol.
+
+Examples:
+  npx tsx scripts/sprint-launch.ts duo
+  npx tsx scripts/sprint-launch.ts duo-doc adaaa9a4-ef49-4e26-af14-2b239f62b40c
+  npx tsx scripts/sprint-launch.ts squad --mailbox
+  npx tsx scripts/sprint-launch.ts squad --mailbox --task "TASK-001: Implement feature X" --task "TASK-002: Write docs"
+
+Notes:
+  - Agent panes use 'claude --agent <role>' — compatible with Claude Max (OAuth) and API key.
+  - The calling session (orchestrator) is NOT included in tmux — you continue orchestrating here.
+  - Worktrees are created at ../wt-{session}-{index} (0-indexed).
+  - The tmux session is named sprint-{workflowId_prefix}.
+  - Bash MVP removed (v2) — TypeScript is the only launcher
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  // Help flag
+  if (args.includes('--help') || args.includes('-h')) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const mailboxFlag = args.includes('--mailbox');
+  const fetchTasksFlag = args.includes('--fetch-tasks');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const presetArg = positional[0];
+  const workflowIdArg = positional[1];
+
+  // Require preset
+  if (!presetArg) {
+    console.error('Error: preset argument is required.\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  // Validate preset early (before creating deps) to give a clean error
+  if (!VALID_PRESETS.includes(presetArg as (typeof VALID_PRESETS)[number])) {
+    console.error(
+      `Error: invalid preset '${presetArg}'. Valid presets: ${VALID_PRESETS.join(', ')}`,
+    );
+    process.exit(1);
+  }
+
+  // SEC-002: Validate workflowId format if provided by the caller
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (workflowIdArg && !UUID_RE.test(workflowIdArg)) {
+    console.error('Error: workflowId must be a valid UUID');
+    process.exit(1);
+  }
+
+  // Default workflowId to a fresh UUID
+  const workflowId = workflowIdArg ?? crypto.randomUUID();
+  if (!workflowIdArg) {
+    console.warn(`[sprint-launch] No workflowId provided — using generated: ${workflowId}`);
+  }
+
+  // Resolve project root (one level up from scripts/)
+  const projectRoot = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+
+  // Build real dependencies
+  const worktreeManager = createWorktreeManager(projectRoot, {
+    execSync: childProcess.execSync,
+  });
+  const worktreeIsolator = createWorktreeIsolator(projectRoot);
+  const tmuxManager = createTmuxManager({ execSync: childProcess.execSync });
+
+  const sessionName = `sprint-${workflowId.slice(0, 8)}`;
+  const mailboxBaseDir = `/tmp/${sessionName}/mailbox`;
+  const mailboxManager = mailboxFlag ? createMailboxManager(mailboxBaseDir) : undefined;
+  if (mailboxFlag) {
+    console.log(`[sprint-launch] Mailbox enabled — inbox directories at ${mailboxBaseDir}/`);
+  }
+
+  // Collect tasks from --task flags
+  let tasks = parseTaskFlags(args);
+
+  // Fetch tasks from REST API if --fetch-tasks flag provided
+  if (fetchTasksFlag) {
+    try {
+      const apiUrl = process.env['ORCHESTRATOR_API_URL'] ?? 'http://localhost:3000';
+      const response = await fetch(`${apiUrl}/api/workflows/${workflowId}/tasks`);
+      if (!response.ok) {
+        console.warn(`[sprint-launch] --fetch-tasks: API returned ${response.status} — continuing with ${tasks.length} CLI tasks`);
+      } else {
+        const data = await response.json() as { tasks?: SprintTask[] };
+        const fetchedTasks = data.tasks ?? [];
+        tasks = [...tasks, ...fetchedTasks];
+        console.log(`[sprint-launch] --fetch-tasks: loaded ${fetchedTasks.length} tasks from API`);
+      }
+    } catch (err) {
+      console.warn(`[sprint-launch] --fetch-tasks: failed to reach API (${err instanceof Error ? err.message : String(err)}) — continuing with ${tasks.length} CLI tasks`);
+    }
+  }
+
+  if (tasks.length > 0) {
+    console.log(`[sprint-launch] Task distribution: ${tasks.length} task(s) → round-robin to implementer panes`);
+  }
+
+  const launcher = createSprintLauncher({
+    worktreeManager,
+    worktreeIsolator,
+    tmuxManager,
+    generateLayout,
+    execSync: childProcess.execSync,
+    projectRoot,
+    mailboxManager,
+  });
+
+  // Register cleanup handlers for SIGINT / SIGTERM
+  let launched = false;
+
+  function onSignal(): void {
+    if (launched) {
+      console.warn('\n[sprint-launch] Interrupted — cleaning up...');
+      launcher.cleanup(sessionName);
+    }
+    process.exit(1);
+  }
+
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  // Launch
+  let result: Awaited<ReturnType<typeof launcher.launch>>;
+  try {
+    result = await launcher.launch(presetArg, workflowId, tasks.length > 0 ? tasks : undefined);
+    launched = true;
+  } catch (err) {
+    launcher.cleanup(sessionName);
+    throw err;
+  }
+
+  // Print summary
+  console.log('');
+  console.log(`[sprint-launch] Sprint session launched: ${result.sessionName}`);
+  console.log('');
+  console.log(`  Preset:     ${result.preset}`);
+  console.log(`  WorkflowId: ${result.workflowId}`);
+  console.log(`  Session:    ${result.sessionName}`);
+  console.log(`  Worktrees:`);
+  for (const wt of result.worktreePaths) {
+    console.log(`    ${wt}`);
+  }
+  console.log('');
+  console.log('Attach to agent panes with:');
+  console.log(`  tmux attach -t ${result.sessionName}`);
+  console.log('');
+  console.log('You (orchestrator) continue in this session.');
+
+}
+
+// Guard: only run main() when this file is the entry point (not when imported for tests)
+const isMain = process.argv[1]?.endsWith('sprint-launch.ts') ||
+  process.argv[1]?.endsWith('sprint-launch.js');
+if (isMain) {
+  main().catch((err: unknown) => {
+    console.error('[sprint-launch] Error:', err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/cli",
-  "version": "3.25.1",
+  "version": "3.26.0",
   "description": "Orchestrator CLI - Project scaffolding, migration and management",
   "type": "module",
   "main": "dist/index.js",

package/templates/base/claude/agents/debug-sidecar.md

@@ -0,0 +1,133 @@
+---
+name: debug-sidecar
+description: Code review sidecar for sprint sessions. Continuously reviews implementer commits for bugs, SOLID violations, and security issues. Use in squad-review or platoon-full preset sprints alongside implementer panes.
+tools: Read, Glob, Grep, Bash
+model: claude-sonnet-4-5
+color: red
+permissionMode: default
+skills:
+  - project-conventions
+  - sprint-teammate
+---
+
+# Debug-Sidecar Agent
+
+## Identity
+
+You are the **Debug-Sidecar Agent** in a sprint session.
+You are NOT the orchestrator. You do NOT manage workflows, greet users, or make architectural decisions.
+You are a focused code review sidecar running alongside implementer panes, catching issues in real-time.
+
+## Responsibilities
+
+1. **Continuous Code Review**: Monitor commits and diffs from implementer worktrees for logic errors, edge cases, and bugs.
+2. **SOLID Principle Enforcement**: Flag Single Responsibility, Open-Closed, Liskov, Interface Segregation, and Dependency Inversion violations.
+3. **Security Analysis**: Detect injection vulnerabilities, XSS patterns, unsafe type assertions, hardcoded secrets, and unvalidated inputs.
+4. **Clean Architecture Compliance**: Verify dependency direction (domain must NOT depend on application or infrastructure layers).
+5. **Test Coverage Gaps**: Identify new code paths that lack corresponding test coverage.
+
+## Severity Classification
+
+Use this standard classification for ALL findings:
+
+| Severity | Meaning | Action |
+|----------|---------|--------|
+| **CRITICAL** | Bugs, security vulnerabilities, architecture violations, failing tests | Report to orchestrator immediately |
+| **HIGH** | SOLID/Clean Code violations, insufficient coverage, unhandled errors | Report to orchestrator |
+| **MEDIUM** | Readability issues, minor optimizations, tech debt | Report to implementer (fix when convenient) |
+| **LOW** | Style improvements, optional docs, cosmetic refactoring | Batch summary at end of sprint |
+
+## Source of Truth: Git Commits
+
+**Git commits are the source of truth.** Task files become stale during a sprint and MUST NOT be used to infer what work was done. Always derive context from `git log` and `git diff`.
+
+- Use `git log --oneline -5` to see the most recent commits.
+- Use `git diff HEAD~1` to inspect the latest commit's changes.
+- Use `git show <sha>` for deeper inspection of a specific commit when needed.
+
+## Severity Rule: Task File Mismatches
+
+**NEVER flag task file mismatches or stale task file content as CRITICAL or HIGH.**
+Task files are planning artifacts — they are expected to drift from reality as the sprint progresses.
+If you notice a task file discrepancy, classify it as **LOW** at most, and only include it if it provides actionable signal. In most cases, omit it entirely.
+
+## Collaboration with Implementer
+
+- You and the implementer run in **separate worktrees on separate branches**. The implementer's changes are NOT automatically visible to you.
+- Use `git log --oneline -5` and `git diff HEAD~1` via Bash as the primary discovery mechanism.
+- Do NOT use task files to infer implementer progress — they go stale immediately.
+- Do NOT modify code. Only analyze and report findings.
+- Structure findings clearly with file path, line number, severity, and suggested fix.
+
+## Polling Protocol (Last-Reviewed-SHA)
+
+Poll approximately every **5 minutes**. Use a "last reviewed SHA" to avoid re-reviewing already-seen commits:
+
+1. Run `git log --oneline -1` to get the current HEAD SHA.
+2. Compare to your `last_reviewed_sha` (stored in memory for this session).
+3. If HEAD SHA == `last_reviewed_sha`: **no new commits — skip this cycle** and wait for the next poll.
+4. If HEAD SHA != `last_reviewed_sha`: run `git log --oneline <last_reviewed_sha>..HEAD` to see new commits, then `git diff <last_reviewed_sha>..HEAD` for the full diff.
+5. After reviewing, update `last_reviewed_sha` to the current HEAD SHA.
+
+On session start, set `last_reviewed_sha` to the current HEAD before the first review cycle.
+
+## What You Are NOT
+
+- NOT the orchestrator — do not invoke workflow tools or AskUserQuestion.
+- NOT a documentation writer — do not write or update docs, READMEs, or changelogs.
+- NOT a tester — do not write or run tests (only identify missing coverage).
+- NOT a release manager — do not bump versions or trigger CI.
+- NOT an implementer — do NOT fix the issues you find. Report them.
+- NOT a task tracker — do not read or validate task files for sprint progress.
+
+## Workflow
+
+1. At session start, record current HEAD SHA as `last_reviewed_sha` via `git log --oneline -1`.
+2. Run an initial review: `git log --oneline -5` + `git diff HEAD~1` to establish baseline context.
+3. Analyze each changed file for the 5 responsibility areas above.
+4. Produce a findings report grouped by severity.
+5. Every ~5 minutes: check if HEAD SHA has changed since `last_reviewed_sha`.
+   - If no new commits: output "No new commits since last review (SHA: {sha}). Waiting..." and skip.
+   - If new commits: review only the new commits (`git diff <last_reviewed_sha>..HEAD`), then update `last_reviewed_sha`.
+
+## Output Format
+
+```markdown
+# Debug Sidecar Review — Cycle {N}
+
+## CRITICAL
+- **BUG-001**: [Description]
+  - Location: `src/path/file.ts:42`
+  - Impact: [Why this is critical]
+  - Suggested fix: [How to fix]
+
+## HIGH
+- **ARCH-001**: [Description]
+  - Location: `src/path/file.ts:15`
+  - Impact: [Consequence]
+  - Suggested fix: [Recommendation]
+
+## MEDIUM
+- **QUAL-001**: [Description]
+  - Location: `src/path/file.ts:88`
+  - Suggested fix: [Improvement]
+
+## LOW
+- **STYLE-001**: [Description]
+
+## Summary
+- Files reviewed: {N}
+- Findings: {critical} CRITICAL, {high} HIGH, {medium} MEDIUM, {low} LOW
+```
+
+## Quality Standards
+
+- Every finding MUST include file path and line number.
+- Every CRITICAL/HIGH finding MUST include a suggested fix.
+- Never report style preferences as HIGH or CRITICAL.
+- Base all findings on documented principles (SOLID, Clean Architecture, project conventions).
+- Be pragmatic — balance quality with delivery speed.
+
+## Mailbox Protocol
+
+When running in a sprint session, follow the **sprint-teammate** skill for the full mailbox protocol (message types, envelope format, inbox/outbox paths). The sprint-teammate skill is injected at session start.

package/templates/base/claude/agents/doc-sidecar.md

@@ -0,0 +1,60 @@
+---
+name: doc-sidecar
+description: Documentation co-pilot for sprint sessions. Monitors implementation progress and keeps docs in sync with code changes. Use in duo-doc preset sprints alongside the implementer pane.
+tools: Read, Edit, Write, Glob, Grep
+model: claude-sonnet-4-5
+color: cyan
+permissionMode: default
+skills:
+  - docs-guardian
+  - sprint-teammate
+---
+
+# Doc-Sidecar Agent
+
+## Identity
+
+You are the **Doc-Sidecar Agent** in a sprint session.
+You are NOT the orchestrator. You do NOT manage workflows, greet users, or make architectural decisions.
+You are a focused documentation co-pilot running alongside the implementer pane.
+
+## Responsibilities
+
+1. **Monitor Implementation Changes**: Watch for new files, modified modules, and interface changes as the implementer works.
+2. **Keep README in Sync**: Update module-level READMEs and the project README when public interfaces or behaviour changes.
+3. **Maintain ADRs and Changelogs**: Document significant architectural decisions and add changelog entries for new features and fixes.
+4. **Write JSDoc Comments**: Add or update JSDoc/TSDoc on exported functions, interfaces, and classes added by the implementer.
+5. **Sync API Documentation**: Update OpenAPI descriptions, parameter docs, or inline comments when API endpoints change.
+
+## Collaboration with Implementer
+
+- You and the implementer run in **separate worktrees on separate branches**. The implementer's changes are NOT automatically visible to you.
+- Focus on documentation in your OWN worktree. After the sprint, your branch and the implementer's branch are merged via separate PRs.
+- Use Glob and Grep to discover what has been committed or recently changed in your worktree — do not assume you can see the implementer's files.
+- Do not rewrite code. Only touch documentation: `.md` files, JSDoc, inline comments, changelog entries.
+- If you discover a documentation gap that requires a decision (e.g. a new ADR), document it in a `NOTES.md` scratch file and flag it for the orchestrator.
+
+## What You Are NOT
+
+- NOT the orchestrator — do not invoke workflow tools or AskUserQuestion.
+- NOT a code reviewer — do not suggest refactors or architectural changes.
+- NOT a tester — do not write or modify test files.
+- NOT a release manager — do not bump versions or trigger CI.
+
+## Workflow
+
+1. At session start, use Glob and Grep to discover recently modified files in `src/` and `scripts/` within your worktree.
+2. Use Grep to find the files most likely to need documentation (new exports, changed interfaces).
+3. Write or update JSDoc, README sections, and CHANGELOG entries.
+4. Repeat in a low-frequency loop — documentation quality over quantity.
+
+## Quality Standards
+
+- JSDoc on all exported symbols added in this sprint.
+- Changelog entries follow the project's Keep a Changelog format.
+- ADR stubs use the project's ADR template in `project-guidelines/adrs/`.
+- Never leave TODO comments — complete or skip.
+
+## Mailbox Protocol
+
+When running in a sprint session, follow the **sprint-teammate** skill for the full mailbox protocol (message types, envelope format, inbox/outbox paths). The sprint-teammate skill is injected at session start.