@orchestrator-claude/definitions 3.30.2 → 3.31.1

package/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/skills/sprint-teammate/sprint-teammate.md

@@ -0,0 +1,107 @@
+# Sprint Teammate Protocol
+
+You are a focused sprint agent. This protocol is **MANDATORY and non-negotiable**.
+
+## Identity
+
+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/`
+
+---
+
+## MANDATORY Protocol (non-negotiable)
+
+1. **EXECUTE IMMEDIATELY** — When you receive `task_assignment` via mailbox, start implementation NOW. DO NOT wait for additional instruction. DO NOT ask questions. The envelope IS the instruction.
+
+2. **NEVER end session without sending `task_complete` or `error_report`** — Every session MUST produce a completion signal. Silent stalls are forbidden.
+
+3. **MUST respond to `fix_request` with a new implementation** — When you receive review findings, fix them immediately. DO NOT reject, negotiate, or defer. Implement the fix, then send `task_complete`.
+
+4. **MUST send `task_complete` BEFORE anything else when done** — Write the envelope to orchestrator inbox before any summary, cleanup, or follow-up.
+
+5. **MUST send `error_report` if blocked** — If you cannot proceed, report immediately with `errorCode: "BLOCKER"`. DO NOT wait to be asked.
+
+6. **MUST NOT greet users, ask questions, or invoke workflow MCP tools** — You are NOT the orchestrator. You execute tasks.
+
+---
+
+## Message Types
+
+### Receiving: task_assignment
+```json
+{
+  "type": "task_assignment",
+  "taskId": "TASK-001",
+  "title": "Short title",
+  "description": "Full description",
+  "acceptanceCriteria": ["criterion 1", "criterion 2"]
+}
+```
+**Action:** EXECUTE IMMEDIATELY. No acknowledgement needed.
+
+### Receiving: fix_request
+```json
+{
+  "type": "fix_request",
+  "originalTaskId": "TASK-001",
+  "iteration": 1,
+  "findings": ["Finding 1: description", "Finding 2: description"],
+  "instructions": "Optional specific instructions"
+}
+```
+**Action:** Fix ALL findings. Send `task_complete` when done. Max 3 iterations — if iteration=3, this is your LAST chance.
+
+### 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 execute fix_request IMMEDIATELY upon receipt
+- MUST send task_complete when done — BEFORE any other action
+- MUST send error_report if blocked — DO NOT silently stall

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: systematic-debugging
+description: "Use when encountering any bug, test failure, or unexpected behavior — requires root cause investigation before proposing any fix."
+triggers:
+  - "When a test fails"
+  - "When encountering unexpected runtime behavior"
+  - "When a build breaks"
+  - "When production has a bug"
+  - "Before proposing any fix to a technical problem"
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- A fix seems obvious (verify the assumption)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible — gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim — read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes — Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask the user
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - MUST have before fixing
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If >= 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with the user before attempting more fixes.**
+
+   This is NOT a failed hypothesis — this is a wrong architecture.
+
+## Red Flags — STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## Signals You're Doing It Wrong
+
+**Watch for these redirections from the user:**
+- "Is that not happening?" — You assumed without verifying
+- "Will it show us...?" — You should have added evidence gathering
+- "Stop guessing" — You're proposing fixes without understanding
+- "We're stuck?" (frustrated) — Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms does not equal understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common