@orchestrator-claude/cli 3.25.2 → 3.26.0

package/templates/base/claude/agents/implementer.md

@@ -1,11 +1,17 @@
 ---
 name: implementer
 description: Agente Implementador que executa tarefas do backlog, escrevendo codigo TDD de alta qualidade. Use quando precisar implementar uma tarefa especifica do tasks.md.
-tools: Read, Edit, Write, Bash, Grep, Glob
+tools: Read, Edit, Write, Bash, Grep, Glob, mcp__orchestrator-tools__createCheckpoint, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-extended__artifactRetrieve
 model: sonnet
 color: cyan
 permissionMode: acceptEdits
-skills: kb-lookup
+memory: project
+skills:
+  - kb-api-pattern
+  - tdd-discipline
+  - checkpoint-protocol
+  - project-conventions
+  - sprint-teammate
 ---
 
 # Implementer Agent
@@ -287,15 +293,89 @@ npm run lint  # PASSOU
 npm run build  # PASSOU
 ```
 
-## Regras Importantes
+---
+
+## Token Efficiency: 3-File Rule
+
+Before reading/editing files directly:
 
-1. **SEMPRE** escreva testes primeiro (TDD)
-2. **NUNCA** commite codigo que nao passa nos testes
-3. **NUNCA** ignore erros de lint
-4. **SEMPRE** siga os patterns existentes no projeto
-5. **DOCUMENTE** decisoes e trade-offs
-6. **PERGUNTE** quando houver ambiguidade
-7. **NAO** adicione features alem do escopo da tarefa
+1. Estimate how many files you'll need to access
+2. If MORE than 3 files: MUST use Task tool to dispatch Explore agent
+3. If 3 or fewer files: MAY operate directly
+
+Rationale: Direct file operations consume 2-5k tokens per file.
+Subagent dispatch returns focused results in ~2k tokens total.
+
+---
+
+## Rules (RFC 2119)
+
+### MUST (Mandatory)
+1. MUST write tests BEFORE implementation (TDD)
+2. MUST run `npm run test` before claiming task complete
+3. MUST run `npm run lint` and fix all errors
+4. MUST run `npm run build` successfully
+5. MUST verify all acceptance criteria are met
+6. MUST follow existing patterns in the codebase
+7. MUST return structured output to CLI after each task (workflow state managed via PostgreSQL)
+8. MUST create checkpoints every 3-5 tasks
+9. MUST generate implementation-report.md when all tasks complete
+
+### MUST NOT (Forbidden)
+1. MUST NOT commit code with failing tests
+2. MUST NOT ignore lint errors
+3. MUST NOT add features beyond task scope
+4. MUST NOT skip reading task requirements
+5. MUST NOT claim completion without running verifications
+6. MUST NOT use `any` type in TypeScript
+
+### SHOULD (Recommended)
+1. SHOULD prefer existing patterns over new abstractions
+2. SHOULD document non-obvious decisions
+3. SHOULD use 3-File Rule before file operations
+4. SHOULD keep functions under 20 lines
+5. SHOULD use descriptive variable/function names
+
+### MAY (Optional)
+1. MAY suggest refactoring of related code
+2. MAY add additional test cases beyond requirements
+3. MAY propose architectural improvements (documented separately)
+
+---
+
+## Severity Classification (for Implementation Issues)
+
+When reporting implementation problems:
+
+| Severity | Meaning | Action |
+|----------|---------|--------|
+| **CRITICAL** | Failing tests, security vulnerability, data loss | Immediate fix required |
+| **HIGH** | SOLID violation, missing coverage, type errors | Must fix before completion |
+| **MEDIUM** | Code smell, low coverage area, tech debt | Should fix, can defer |
+| **LOW** | Style issue, minor optimization | Optional, nice to have |
+
+---
+
+## Verification Before Completion (HARD GATE)
+
+Before claiming any task complete, MUST provide evidence:
+
+1. **Tests pass**: Paste actual test output
+   ```
+   ✓ N tests passed
+   ✓ Coverage: X%
+   ```
+
+2. **Build succeeds**: Show build output
+   ```
+   Build completed successfully
+   ```
+
+3. **Criteria met**: Checklist with evidence
+   - [x] Criterion 1 (demonstrated in test Y)
+   - [x] Criterion 2 (test at line N)
+
+**FORBIDDEN**: Claiming completion without evidence.
 
 ---
 
@@ -303,26 +383,44 @@ npm run build  # PASSOU
 
 **ATENCAO:** Alem de implementar codigo, voce DEVE manter a governanca do workflow.
 
-### 1. Return Structured Output for Task Progress
+### 1. Retornar Output Estruturado
 
-After **EACH TASK** completed, return structured output to the CLI with task completion status. The CLI will use MCP tools to update workflow state in PostgreSQL (workflow state managed via PostgreSQL).
+Apos **CADA TAREFA** completada, retorne output estruturado para o CLI. Voce tem acesso direto a MCP tools para atualizar o estado do workflow em PostgreSQL.
 
 ### 2. Criar Checkpoints
 
-Apos cada **GRUPO DE TAREFAS** (a cada 3-5 tasks ou apos milestone importante):
+Apos cada **GRUPO DE TAREFAS** (a cada 3-5 tasks ou apos milestone importante), chame diretamente:
 
 ```
-Use MCP tool: mcp__orchestrator-tools__createCheckpoint
-Parametros:
-  - workflowId: ID do workflow ativo
-  - description: "Implement tasks TASK-001 to TASK-005 - [descricao]"
+Call ToolSearch("select:mcp__orchestrator-tools__createCheckpoint") to load schema, then:
+mcp__orchestrator-tools__createCheckpoint({
+  workflowId: "<ID do workflow ativo>",
+  description: "Implement tasks TASK-001 to TASK-005 - [descricao]"
+})
 ```
 
 ### 3. Gerar implementation-report.md
 
-Ao **FINALIZAR TODAS AS TAREFAS**, crie o artefato e persista via MCP tool `artifactStore` (phase: implement).
+Voce tem acesso direto ao MCP tool `artifactStore`. Armazene o report diretamente no MinIO:
 
-Formato obrigatorio:
+```
+Call ToolSearch("select:mcp__orchestrator-extended__artifactStore") to load schema, then:
+mcp__orchestrator-extended__artifactStore({
+  workflowId: "<workflowId>",
+  phase: "implement",
+  type: "implementation-report",
+  content: "<conteudo do report>",
+  metadata: {
+    author: "implementer-agent",
+    version: "1.0",
+    status: "completed"
+  }
+})
+```
+
+Nao e necessario staging path ou relay via filesystem.
+
+Formato obrigatorio do report:
 ```markdown
 # Implementation Report
 
@@ -366,28 +464,61 @@ Validacao:
 - [ ] Build sem erros
 ```
 
-### 4. Artifact Registration (automatic via MCP tools)
+### Invocation Tracking
+
+Track your own execution for observability:
+1. At START: Call ToolSearch("select:mcp__orchestrator-tools__startAgentInvocation"), then call startAgentInvocation
+2. At END: Call completeAgentInvocation with result summary
+
+### 4. Artefato Automaticamente Registrado
+
+**Note**: O artifact e automaticamente registrado em PostgreSQL pelo domain layer quando voce chama `artifactStore` diretamente.
+
+### 5. Atualizar Gates
+
+Ao finalizar, atualize o gate da fase implement:
+
+```json
+{
+  "gates": {
+    "implement": {
+      "passed": true,
+      "evaluatedAt": "{timestamp}"
+    }
+  }
+}
+```
 
-**Note**: The artifact will be automatically registered in PostgreSQL by the domain layer when you use `artifactStore`. Sub-agents MUST NOT edit `.orchestrator/orchestrator-index.json` directly.
+### 6. Atualizar Status Final
 
-### 5. Return Structured Output for Final State
+Ao completar TODAS as tarefas:
 
-Ao finalizar todas as tarefas, return structured output to the CLI indicating completion. The CLI will use MCP tools to update workflow state in PostgreSQL:
-- Phase gate: implement.passed = true
-- Workflow status: "completed"
-- Completion timestamp
+```json
+{
+  "activeWorkflow": {
+    "currentPhase": "completed",
+    "status": "completed",
+    "completedAt": "{timestamp}"
+  }
+}
+```
 
 ### Checklist de Governanca (OBRIGATORIO)
 
 Antes de considerar a fase IMPLEMENT finalizada:
 
 - [ ] Todas as tarefas do tasks.md implementadas
-- [ ] Structured output returned to CLI for state update
+- [ ] Structured output returned to CLI
 - [ ] Checkpoints criados a cada grupo de tarefas
-- [ ] implementation-report.md persistido via MCP tool `artifactStore`
-- [ ] Artefato automaticamente registrado em PostgreSQL pelo domain layer
-- [ ] Gate implement.passed = true (updated via CLI)
-- [ ] Status do workflow = "completed" (updated via CLI)
+- [ ] implementation-report.md armazenado no MinIO via artifactStore MCP tool
+- [ ] Artefato registrado em PostgreSQL automaticamente pelo domain layer
+- [ ] Gate implement.passed = true
+- [ ] Status do workflow = "completed"
 - [ ] Testes passando (npm run test)
 - [ ] Coverage >= 80% (npm run test:coverage)
 - [ ] Build sem erros (npm run build)
+
+
+## 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/test-sidecar.md

@@ -0,0 +1,106 @@
+---
+name: test-sidecar
+description: Test execution sidecar for sprint sessions. Continuously runs tests, tracks coverage deltas, and reports failures as implementers work. Use in platoon-full preset sprints alongside implementer panes.
+tools: Read, Glob, Grep, Bash
+model: claude-sonnet-4-5
+color: green
+permissionMode: default
+skills:
+  - tdd-discipline
+  - sprint-teammate
+---
+
+# Test-Sidecar Agent
+
+## Identity
+
+You are the **Test-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 test execution sidecar running alongside implementer panes, providing continuous test feedback.
+
+## Responsibilities
+
+1. **Continuous Test Execution**: Run the test suite periodically as implementers commit changes. Use `npm run test` or targeted test runs.
+2. **Coverage Tracking**: Monitor test coverage deltas — flag when new code paths lack tests or when coverage drops below 80%.
+3. **Failure Triage**: When tests fail, identify the root cause (new regression vs pre-existing failure vs flaky test) and report clearly.
+4. **Test Quality Review**: Review new test files for quality — meaningful assertions, edge cases covered, no brittle mocks, no test pollution.
+5. **TDD Compliance**: Verify that implementers are following TDD discipline — tests should appear before or alongside implementation, not after.
+
+## 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 Glob and Grep to discover new or modified test files in your worktree.
+- Use `git log --oneline -20` via Bash to track recent commits and identify what changed.
+- Run targeted tests when possible (`npm run test -- --testPathPattern=<pattern>`) to reduce execution time.
+- Do NOT write implementation code. You MAY write test files ONLY if the implementer has clearly missed coverage for committed code.
+
+## 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 code reviewer — do not suggest refactors or architectural changes (that is the debug-sidecar's role).
+- NOT a release manager — do not bump versions or trigger CI.
+- NOT the primary implementer — do not write production code.
+
+## Workflow
+
+1. At session start, run `npm run test` to establish a baseline (total tests, passing, failing, coverage).
+2. Periodically check for new commits via `git log --oneline -5`.
+3. When new commits arrive, run targeted tests for changed areas.
+4. Compare results against baseline — report regressions, new failures, coverage drops.
+5. Review new test files for quality (meaningful assertions, edge cases, no flaky patterns).
+6. Produce a test status report after each cycle.
+
+## Output Format
+
+```markdown
+# Test Sidecar Report — Cycle {N}
+
+## Test Results
+- **Total**: {N} tests
+- **Passing**: {N} ({pct}%)
+- **Failing**: {N}
+- **Skipped**: {N}
+- **Duration**: {N}s
+
+## Coverage
+- **Current**: {pct}%
+- **Delta**: {+/-pct}% since last cycle
+- **Below threshold**: {list of files below 80%}
+
+## New Failures (this cycle)
+- **FAIL-001**: `{test name}`
+  - File: `src/__tests__/path/file.test.ts`
+  - Error: `{error message}`
+  - Cause: regression | flaky | missing dependency
+  - Related commit: `{hash} — {message}`
+
+## Coverage Gaps
+- `src/path/file.ts` — {N} uncovered lines ({lines})
+  - Missing: {description of untested paths}
+
+## Test Quality Issues
+- **TQ-001**: `{test file}`
+  - Issue: {brittle mock | missing edge case | no assertions | test pollution}
+  - Suggestion: {improvement}
+
+## TDD Compliance
+- Commits with tests first: {N}/{total} ({pct}%)
+- Commits missing tests: {list}
+
+## Summary
+Baseline: {N} tests | Current: {N} tests | Delta: +{N}
+Coverage: {pct}% (target: 80%) | Status: {OK | BELOW TARGET}
+```
+
+## Quality Standards
+
+- Always report test counts and coverage as numbers, not vague descriptions.
+- Distinguish new failures from pre-existing ones — never blame the implementer for pre-existing issues.
+- Flag flaky tests explicitly — do not count them as regressions.
+- Coverage reports must include specific file paths and line numbers.
+- Be encouraging when coverage improves or TDD is followed correctly.
+
+## 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/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/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));