@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/codex/delegation/references/agent-teams-saga.md

@@ -0,0 +1,254 @@
+# Agent Teams Delegation Saga
+
+> **Machine-readable version:** `exarchos_orchestrate({ action: "runbook", id: "agent-teams-saga" })`
+> The runbook below is the authoritative sequence. The prose description provides human-readable context.
+
+Event-first delegation saga for Agent Teams mode. Every coordination action is preceded by an Exarchos event emission. The event stream is the authoritative record; native API calls are side effects.
+
+**Architectural principle:** Events record intent. Native API calls execute effects.
+
+## Delegation Saga (6 Steps)
+
+The dispatch follows a saga pattern with compensable, pivot, and retryable transactions.
+
+### Step 1: Create Team (COMPENSABLE)
+
+```yaml
+# Emit event (source of truth)
+exarchos_event append:
+  stream: {featureId}
+  event:
+    type: "team.spawned"
+    data:
+      teamSize: {N}
+      teammateNames: ["teammate-1", "teammate-2"]
+      taskCount: {M}
+      dispatchMode: "agent-team"
+
+# Execute side effect
+TeamCreate:
+  team_name: {featureId}
+  description: "SDLC delegation for {featureId}"
+```
+
+Idempotency: before retrying, check if `~/.claude/teams/{featureId}/` already exists.
+
+### Gate: Team Verification
+
+Before proceeding to Step 2:
+1. Verify team config exists: `~/.claude/teams/{featureId}/config.json`
+2. Verify config has valid `members` array
+3. If check fails: emit `team.creation.failed` event, abort delegation
+
+### Step 2: Create Native Tasks (COMPENSABLE)
+
+Emit ALL task planning events in a single batched call (1 MCP call instead of N):
+
+```yaml
+# Emit ALL task events in one batch (source of truth)
+exarchos_event batch_append:
+  stream: {featureId}
+  events:
+    - type: "team.task.planned"
+      taskId: "task-001"
+      title: {task.title}
+      modules: {task.files}
+      blockedBy: {task.blockedBy}
+    - type: "team.task.planned"
+      taskId: "task-002"
+      ...
+```
+
+`batch_append` atomicity: acquires the stream lock once, validates all events, writes with sequential sequence numbers in a single append. All-or-nothing -- if any event fails validation, none are written.
+
+Then create native tasks and wire dependencies:
+
+```yaml
+# Execute side effects (one TaskCreate per task)
+TaskCreate:
+  subject: {task.title}
+  description: {task.fullDescription}
+  activeForm: "Implementing {task.title}"
+  # Returns nativeTaskId
+
+# Wire dependencies (after ALL tasks created -- requires sequential creation)
+TaskUpdate:
+  taskId: {nativeTaskId}
+  addBlockedBy: [{blockerNativeTaskIds}]
+```
+
+Idempotency: before retrying, check `TaskList` for existing tasks with matching subjects to avoid duplicates.
+
+After all tasks are created, store the correlation (orchestrator is the **sole writer** of `workflow.tasks[]`):
+
+```yaml
+exarchos_workflow set:
+  featureId: {featureId}
+  updates:
+    tasks: [{...task, nativeTaskId: "returned-id"}]
+```
+
+### Step 3: Spawn Teammates (PIVOT -- point of no return)
+
+> This is the **pivot transaction**. Once teammates start working, their side effects (file writes, commits, worktree modifications) cannot be cleanly reversed. Steps 1-2 are compensable; Step 3+ are not fully reversible.
+
+For each teammate:
+
+```yaml
+# Emit event (source of truth)
+exarchos_event append:
+  stream: {featureId}
+  event:
+    type: "team.teammate.dispatched"
+    teammateName: {name}
+    worktreePath: {path}
+    assignedTaskIds: [{taskIds}]
+    model: "opus"
+
+# Execute side effect
+# Note: teammates inherit the lead's permission mode (per Claude Code docs).
+# Do NOT set `mode` at spawn -- it is not respected.
+Task:
+  subagent_type: "general-purpose"
+  team_name: {featureId}
+  name: {teammateName}
+  model: "opus"
+  prompt: {spawnPrompt}  # See implementer-prompt.md template
+```
+
+> **Spawn prompt assembly:** `{spawnPrompt}` MUST include all universal sections from `implementer-prompt.md` (TDD Requirements, Files, Success Criteria, **Commit Strategy**, Completion) PLUS the Agent Teams-only sections (Coordination, Workflow Intelligence, Team Context, Historical Context). See the comparison table in `implementer-prompt.md` for the full section list. The Commit Strategy section with `git commit`/`git push` instructions is required — without it, teammates may skip pushing their work.
+
+### Step 4: Monitor (RETRYABLE)
+
+The orchestrator enters delegate mode (Shift+Tab). Hooks operate autonomously:
+- **SubagentStart** -- injects live coordination data only (task status changes, newly unblocked tasks). Historical intelligence and team context are already in the spawn prompt.
+- **TeammateIdle** -- runs quality gates, emits `team.task.completed` or `team.task.failed` events. Does NOT mutate `workflow.tasks[]` (single-writer principle). The orchestrator reads these events and updates state.
+
+**Tiered monitoring strategy** (minimizes token cost):
+
+| Tier | Tool | When | Cost |
+|------|------|------|------|
+| Routine | `exarchos_view workflow_status` | Every 30-60s | ~85 tokens |
+| On task completion | `exarchos_workflow get` (fields: tasks) | When TeammateIdle fires | ~200 tokens |
+| On-demand | `exarchos_view delegation_timeline` | Task stall or all complete | ~120 tokens |
+
+Do NOT triple-read on every cycle. `delegation_timeline` replays the full event stream -- reserve for final summary or anomaly detection.
+
+When the orchestrator detects `team.task.completed` events, it updates `workflow.tasks[]`:
+```yaml
+exarchos_workflow set:
+  featureId: {featureId}
+  updates:
+    tasks: [{...task, status: "complete", completedAt: timestamp}]
+```
+
+### Step 5: Disband (RETRYABLE)
+
+When all tasks complete:
+
+```yaml
+# Emit event
+exarchos_event append:
+  stream: {featureId}
+  event:
+    type: "team.disbanded"
+    totalDurationMs: {calculated}
+    tasksCompleted: {count}
+    tasksFailed: {count}
+
+# Shutdown remaining teammates
+SendMessage:
+  type: "shutdown_request"
+  recipient: {each remaining teammate}
+
+# Cleanup native team (after all teammates confirm shutdown)
+TeamDelete
+```
+
+### Step 6: Transition (RETRYABLE)
+
+```yaml
+exarchos_workflow set:
+  featureId: {featureId}
+  phase: "review"
+  # auto-emits workflow.transition event
+```
+
+## Saga Compensation
+
+When the saga fails at any step, compensate in reverse order:
+
+| Failed At | Compensating Actions | Idempotency Check |
+|-----------|---------------------|-------------------|
+| Step 1 (team create) | `TeamDelete` | Check `~/.claude/teams/{featureId}/` exists before delete |
+| Step 2 (task create) | Delete created tasks via `TaskUpdate(status: "deleted")` x created, then `TeamDelete` | Check `TaskList` for existing tasks before delete |
+| Step 3 (spawn -- PIVOT) | `SendMessage(type: "shutdown_request")` x spawned teammates, delete tasks, `TeamDelete` | Check team config `members` array for active teammates |
+| Step 4+ (monitoring) | `exarchos_workflow cancel` (handles full compensation) | Already idempotent via workflow state check |
+
+Compensation steps themselves must be idempotent: deleting an already-deleted team is a no-op; shutting down an already-terminated teammate is a no-op.
+
+If a compensating action itself fails after 3 retries, mark the workflow with `_compensationFailed: true` and emit `team.compensation.failed`. The SessionStart hook detects this on next session for manual resolution.
+
+## Claude Code Agent Teams Constraints
+
+| Constraint | Impact |
+|------------|--------|
+| **No session resumption** for teammates | Teammates are ephemeral. On restart, SessionStart detects orphaned teams but cannot restore them. Spawn new teammates if delegation is incomplete. |
+| **One team per session** | Naturally enforces single-orchestrator invariant. No additional locking needed. |
+| **No nested teams** | Teammates cannot spawn sub-teams. Team composition is flat. |
+| **Permissions inherit from lead** | Do NOT set `mode` at spawn -- not respected. All teammates inherit the lead's permission mode. |
+| **Teammates load MCP automatically** | Exarchos MCP tools are available without explicit instruction. The spawn prompt guides WHICH tools to use, not HOW to access them. |
+
+**CRITICAL:** Ensure your session is using the opus model for coding tasks. All teammates inherit the session model -- use Task tool dispatch if you need per-task model selection.
+
+## Event Payload Conventions
+
+Keep event payloads lean. Move diagnostics to state files.
+
+- `team.task.completed`: prefer `fileCount: number` over `filesChanged: string[]`
+- `team.task.failed`: prefer `gateNames: string[]` (max 10) over `gateResults: Record<string, unknown>`
+- `failureReason`: max 200 characters
+- Move full diagnostics to state file `reviews[taskId]`, not event payloads
+
+## State Bridge (TeammateIdle)
+
+When using Agent Teams mode, the `TeammateIdle` hook fires when a teammate completes its work and becomes idle. It bridges real-time Agent Teams coordination with the Exarchos event stream:
+
+- **On quality pass:** Emits `team.task.completed` event to the event stream. Does NOT mutate `workflow.tasks[]` -- the orchestrator is the sole writer (single-writer principle).
+- **On quality fail:** Returns exit code 2 (sends feedback to teammate, keeps it working). Emits `team.task.failed` event with gate results.
+- **Circuit breaker:** On repeated quality failures, emits `team.task.failed` with circuit open signal.
+- **Graceful degradation:** If no matching workflow/worktree found, gate still passes.
+
+**Single-writer principle:** The orchestrator reads `team.task.completed` events during its monitoring loop and updates `workflow.tasks[]` via `exarchos_workflow set`. This eliminates CAS race conditions between hook and orchestrator writes. The 30-60s latency between event emission and projection update is acceptable -- native task dependency unblocking is automatic (handled by Claude Code) and unaffected by this delay.
+
+This implements a **layered coordination** model:
+- Agent Teams handles real-time dispatch and self-coordination
+- Exarchos event stream records all lifecycle events (source of truth)
+- Orchestrator materializes events into `workflow.tasks[]` (working projection)
+
+## Agent Teams Event Emission
+
+When using Agent Teams mode, the delegation saga emits events at each lifecycle boundary:
+
+**Orchestrator-emitted events (saga steps):**
+- `team.spawned` -- Step 1: team creation (`event.data`: teamSize, teammateNames, taskCount, dispatchMode)
+- `team.task.planned` -- Step 2: task planning via `batch_append` (includes taskId, title, modules, blockedBy)
+- `team.teammate.dispatched` -- Step 3: teammate spawn (includes teammateName, worktreePath, assignedTaskIds, model)
+- `team.disbanded` -- Step 5: team disbandment (includes totalDurationMs, tasksCompleted, tasksFailed)
+
+**Hook-emitted events (automatic via TeammateIdle):**
+- `team.task.completed` -- After quality gates pass (includes taskId, teammateName, durationMs, filesChanged, testsPassed). Hook emits only; does NOT mutate workflow state.
+- `team.task.failed` -- After quality gates fail (includes taskId, teammateName, failureReason, gateResults). Hook emits only.
+
+
+**Superseded events:**
+- `team.task.assigned` -- Superseded by the combination of `team.task.planned` (Step 2) + `team.teammate.dispatched` (Step 3). Existing event streams may still contain `team.task.assigned` events; CQRS views handle both old and new types during the transition period.
+
+**Tool usage by delegation mode:**
+
+| Delegation Mode | Task Completion Signal | State Update |
+|----------------|----------------------|--------------|
+| **Subagent mode** | `exarchos_orchestrate task_complete` (auto-emits `task.completed`) | Orchestrator calls `exarchos_workflow set` |
+| **Agent team mode** | TeammateIdle hook emits `team.task.completed` | Orchestrator reads event, calls `exarchos_workflow set` |
+
+> **Important:** Do NOT use `exarchos_orchestrate task_complete` or `task_fail` during agent team delegation. The TeammateIdle hook handles completion signaling. Using both would produce duplicate events in the stream.

package/skills/codex/delegation/references/fix-mode.md

@@ -0,0 +1,118 @@
+---
+name: fix-mode
+---
+
+# Fix Mode (--fixes)
+
+When invoked with `--fixes`, delegation handles review failures instead of initial implementation.
+
+## Trigger
+
+```bash
+/exarchos:delegate --fixes docs/plans/YYYY-MM-DD-feature.md
+```
+
+Or auto-invoked after review failures.
+
+## Fix Mode Process
+
+1. **Read failure details** from state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"`:
+   - Query `reviews` for review failures
+
+2. **Extract fix tasks** from failure reports:
+
+   ```typescript
+   exarchos_orchestrate({
+     action: "extract_fix_tasks",
+     stateFile: "<path>",
+     reviewReport: "<path>",
+     repoRoot: "<path>"
+   })
+   ```
+
+   **On `passed: true`:** Tasks extracted successfully (JSON array in output).
+   **On `passed: false`:** Parse error — review report or state file malformed.
+
+3. **Create fix tasks** for each issue:
+   - Use `fixer-prompt.md` template
+   - Include full issue context
+   - Specify target worktree
+
+4. **Dispatch fixers** — prefer resume when `agentId` is available, otherwise fresh dispatch:
+
+   **Resume (Claude Code):**
+   ```typescript
+   Task({
+     resume: "[agentId from workflow state]",
+     prompt: "Your implementation failed. [failure context]. Apply adversarial verification."
+   })
+   ```
+
+   **Fresh dispatch (cross-platform):**
+   ```typescript
+   Task({
+     subagent_type: "exarchos-fixer",
+     run_in_background: true,
+     description: "Fix: [issue summary]",
+     prompt: "[fixer-prompt template with issue details]"
+   })
+   ```
+
+5. **Re-review after fixes**:
+   After all fix tasks complete, auto-invoke review phase:
+   ```typescript
+   Skill({ skill: "exarchos:review", args: "<state-file>" })
+   ```
+
+## Resume-First Strategy
+
+When fixing failed tasks, prefer resuming the original agent over dispatching a fresh fixer. Resume preserves the implementer's full context (file reads, reasoning, partial progress), making fixes faster and more accurate.
+
+### agentId Tracking
+
+The `agentId` is captured from the `Task()` completion output and stored in workflow task state. The `SubagentStop` hook (`hooks/hooks.json`) automatically captures `agentId` when `exarchos-implementer` or `exarchos-fixer` agents complete.
+
+Check workflow state for `agentId`:
+```text
+exarchos_workflow get with fields: ["tasks"]
+→ tasks[id=<taskId>].agentId
+```
+
+### Decision Flow
+
+1. **agentId available + Claude Code?** → Resume with failure context
+2. **agentId unavailable or non-Claude-Code client?** → Fresh dispatch with `exarchos-fixer` agent type
+3. **Resume fails?** → Fall back to fresh dispatch
+
+### Gate Chain After Fix
+
+After any fix (resume or fresh dispatch), run the `task-fix` runbook:
+```typescript
+exarchos_orchestrate({ action: "runbook", id: "task-fix" })
+```
+
+This executes the gate chain: re-run tests → TDD compliance check → static analysis → mark task complete if all pass. If runbook unavailable, use `describe` to retrieve gate schemas: `exarchos_orchestrate({ action: "describe", actions: ["check_tdd_compliance", "check_static_analysis", "task_complete"] })`
+
+## Fix Task Structure
+
+Each fix task extracted should include:
+
+| Field | Description |
+|-------|-------------|
+| issue | Problem description from review |
+| file | File path needing fix |
+| line | Line number (if known) |
+| worktree | Which worktree to fix in |
+| branch | Which branch owns this fix |
+| priority | HIGH / MEDIUM / LOW |
+
+## Transition After Fixes
+
+Fix mode goes back to the integration phase after fixes are applied,
+then re-enters review to re-integrate and re-verify:
+
+```text
+/exarchos:delegate --fixes -> [fixes applied] -> re-integrate -> /exarchos:review
+```
+
+This ensures fixed code is re-verified.

package/skills/codex/delegation/references/fixer-prompt.md

@@ -0,0 +1,174 @@
+# Fixer Prompt Template
+
+Use this template when dispatching fix tasks via the Task tool after review failures.
+
+## Adversarial Verification Posture
+
+You are a FIX agent. Do NOT trust the implementer's self-assessment of what went wrong.
+
+- **Independently verify the failure** before applying corrections — re-read the failing test output yourself, do not rely on error summaries provided by the original implementer
+- **Re-read the failing test output yourself** — compare the actual vs expected values; the implementer may have misdiagnosed the root cause
+- **Verify the fix actually resolves the root cause,** not just the symptom — a test that passes for the wrong reason is worse than a failing test
+- **Run ALL tests after fixing,** not just the failing one — regressions from targeted fixes are common and must be caught immediately
+- **Check for silent failures** — verify that error paths are tested, not just happy paths; the original failure may mask additional issues
+
+This posture exists because subagent self-assessment is an unreliable signal. Implementers are biased toward reporting success and may rationalize partial fixes as complete. Your job is to verify independently.
+
+## Template
+
+```markdown
+# Fix Task: [Issue Summary]
+
+## CRITICAL: Worktree Verification (MANDATORY)
+
+Before making ANY changes:
+1. Run: `pwd`
+2. Verify path contains `.worktrees/`
+3. If NOT in worktree: STOP and report error
+
+## Working Directory
+[Absolute path to worktree]
+
+## Issue to Fix
+
+**Source:** [Spec Review | Quality Review | PR Feedback]
+**File:** `[path/to/file.ts]`
+**Line:** [line number if applicable]
+**Priority:** [HIGH | MEDIUM | LOW]
+
+### Problem
+[Clear description of the issue from review]
+
+### Expected Behavior
+[What the code should do instead]
+
+### Suggested Fix
+[Specific guidance on how to fix, from review report]
+
+## Verification
+
+After implementing the fix:
+
+1. **Run tests:**
+   ```bash
+   npm run test:run
+   ```
+   Ensure all tests pass.
+
+2. **If this fix requires a new test:**
+   - Write test FIRST (TDD)
+   - Verify it fails for the expected reason
+   - Implement fix
+   - Verify test passes
+
+3. **Run quality checks:**
+   ```bash
+   npm run typecheck
+   npm run lint
+   ```
+
+## TDD for New Tests
+
+If adding a test to prevent regression:
+
+```typescript
+describe('[ComponentName]', () => {
+  it('should [expected behavior] when [condition]', () => {
+    // Arrange
+    [Setup that reproduces the bug]
+
+    // Act
+    [Execute the code path]
+
+    // Assert
+    expect(result).[matcher](expected);
+  });
+});
+```
+
+## Success Criteria
+
+- [ ] Worktree verified before changes
+- [ ] Issue addressed per review feedback
+- [ ] New test written if applicable
+- [ ] All existing tests pass
+- [ ] Type check passes
+- [ ] Lint passes
+- [ ] No regressions introduced
+
+## Completion
+
+When done, report:
+1. Files modified
+2. Test results
+3. Summary of fix applied
+```
+
+## Usage Example
+
+```typescript
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  description: "Fix: SQL injection vulnerability",
+  prompt: `
+# Fix Task: SQL Injection in User Query
+
+## CRITICAL: Worktree Verification (MANDATORY)
+
+Before making ANY changes:
+1. Run: \`pwd\`
+2. Verify path contains \`.worktrees/\`
+3. If NOT in worktree: STOP and report error
+
+## Working Directory
+/home/user/project/.worktrees/task-003
+
+## Issue to Fix
+
+**Source:** Quality Review
+**File:** \`src/api/users.ts\`
+**Line:** 42
+**Priority:** HIGH
+
+### Problem
+Raw string interpolation in SQL query allows injection attacks.
+
+### Expected Behavior
+Use parameterized queries to prevent SQL injection.
+
+### Suggested Fix
+Replace:
+\`\`\`typescript
+db.query(\`SELECT * FROM users WHERE id = \${userId}\`)
+\`\`\`
+With:
+\`\`\`typescript
+db.query('SELECT * FROM users WHERE id = $1', [userId])
+\`\`\`
+
+## Verification
+
+After implementing the fix:
+
+1. Run tests: \`npm run test:run\`
+2. Add test for SQL injection prevention
+3. Run quality checks
+
+## Success Criteria
+
+- [ ] Worktree verified
+- [ ] Parameterized query implemented
+- [ ] Injection test added
+- [ ] All tests pass
+`
+})
+```
+
+## Key Principles
+
+1. **Always verify worktree** - First action is pwd check
+2. **Clear issue description** - Include file, line, problem
+3. **Specific fix guidance** - Show before/after when possible
+4. **Verification steps** - Always run tests after fix
+5. **TDD for regressions** - Add test to prevent recurrence