@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/generic/delegation/references/pr-fixes-mode.md

@@ -0,0 +1,155 @@
+# PR Feedback Mode (--pr-fixes)
+
+When invoked with `--pr-fixes [PR_URL]`, delegation addresses human review feedback from a pull request instead of implementing from a plan.
+
+## Priority Levels
+
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1 | `coderabbit:critical` | Critical issues + SPEC COMPLIANCE failures |
+| 2 | `human` | Human reviewer comments (authority over automation) |
+| 3 | `coderabbit:major` | Major issues + CODE QUALITY HIGH items |
+| 4 | `coderabbit:minor` | Minor issues |
+
+## Process
+
+### Step 1: Fetch All PR Feedback
+
+```bash
+# Get full PR details including reviews and comments
+gh pr view <number> --json title,body,state,files,reviewDecision,reviews,comments
+
+# Get issue-level comments (pre-merge check summaries)
+gh issue view <number> --json comments
+```
+
+> Or use GitHub MCP `pull_request_read` and `issue_read` if available.
+
+### Step 2: Parse CodeRabbit Feedback
+
+**2a: Identify CodeRabbit comments** by author = `coderabbitai[bot]`
+
+**2b: Parse line comments by severity label:**
+
+| Label | Priority |
+|-------|----------|
+| `Critical` | 1 |
+| `Major` | 2 |
+| `Minor` | 3 |
+
+Extract from each comment:
+- Severity label (emoji + text)
+- File path and line number
+- Issue description
+- Suggested fix (from Proposed fix section if present)
+
+**2c: Parse pre-merge check summaries:**
+- `Status: FAIL` in Spec Review -> Priority 1
+- `Status: NEEDS_FIXES | BLOCKED` in Quality Review -> Priority 2
+- Extract items from `Missing:`, `Untested:`, `Scope Creep:` lists
+
+**2d: Parse reviews with `CHANGES_REQUESTED`:**
+- Note "Actionable comments posted: N" count
+- Cross-reference with line comments already parsed
+
+### Step 3: Parse Human Comments (Priority 2)
+
+For non-CodeRabbit comments, assign `priority: 2` (human authority over automation).
+
+Skip comments that are:
+- Purely praise/acknowledgment ("LGTM", "Nice work")
+- Questions without action items
+- Already marked resolved
+- From other bots (CI notifications, etc.)
+
+### Step 4: Create Fix Tasks
+
+For each actionable item, create a structured fix task:
+
+| Field | Description |
+|-------|-------------|
+| `id` | `fix-001`, `fix-002`, etc. |
+| `priority` | `1` (critical), `2` (human), `3` (major), `4` (minor) |
+| `source` | `"coderabbit:critical"`, `"human"`, `"coderabbit:major"`, `"coderabbit:minor"` |
+| `severity` | `"Critical"`, `"Major"`, `"Minor"`, or null |
+| `file` | File path |
+| `line` | Line number (if line comment) |
+| `issue` | Problem description |
+| `action` | Required change / suggested fix |
+
+### Step 5: Sort and Display Fix Tasks
+
+Sort by priority (1->4), then by file path for grouping.
+
+### Step 6: Track Fix Tasks
+
+Use TodoWrite to track all fix tasks with priority labels.
+
+### Step 7: Dispatch Fixes (MANDATORY - Priority Order)
+
+**Dispatch sequence:**
+1. Dispatch all P1 (critical) fixes in parallel
+2. Wait for completion
+3. Dispatch all P2 (human) fixes in parallel
+4. Wait for completion
+5. Dispatch all P3 (major) fixes in parallel
+6. Wait for completion
+7. Dispatch all P4 (minor) fixes in parallel
+8. Wait for completion
+
+**Task prompt template:**
+```typescript
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  description: "Fix [P{priority} {severity}]: {issue summary}",
+  prompt: `
+# Task: Fix PR Feedback - {issue summary}
+
+## Priority
+{priority} - {source}
+
+## Context
+PR: {PR_URL}
+Source: {source}
+Original feedback: "{original comment text}"
+
+## Working Directory
+{absolute path to repo}
+
+## Fix Required
+File: {file path}
+Line: {line number if applicable}
+Issue: {issue description}
+Action: {required change}
+
+## TDD Requirements
+1. Write a test that would catch this issue (if applicable)
+2. Verify test fails
+3. Implement the fix
+4. Verify test passes
+
+## Success Criteria
+- [ ] Issue addressed per feedback
+- [ ] Tests pass
+- [ ] No regressions introduced
+`
+})
+```
+
+**CHECKPOINT:** Do NOT proceed to next priority level until all fixes in the current level have completed.
+
+### Step 8: Push and Report
+
+After all fixes complete, commit and push:
+```bash
+git add <fixed-files>
+git commit -m "fix: address PR review feedback"
+git push
+```
+
+Report to user: total fixes by priority, files modified. Then auto-chain to `/exarchos:synthesize` for merge confirmation.
+
+### Handling Missing CodeRabbit Comments
+
+If no CodeRabbit comments found, proceed with human comments only.

package/skills/generic/delegation/references/rationalization-refutation.md

@@ -0,0 +1,15 @@
+# Rationalization Refutation Guide
+
+Common rationalizations that lead to delegation failures, with counter-arguments and correct alternatives.
+
+## Rationalizations Table
+
+| Rationalization | Counter-argument | What to do instead |
+|----------------|-----------------|-------------------|
+| "This task is simple enough to skip tests." | Simple tasks have the highest regression risk because they lack safety nets. Every skipped test is a future debugging session. TDD is mandatory per project rules, not optional per perceived complexity. | Write the test first. If it truly is simple, the test will be trivial to write — proving the point. |
+| "The subagent will figure it out without a detailed prompt." | Subagents have zero context beyond what you provide. They cannot read the plan, see prior conversation, or infer intent. Vague prompts produce vague implementations that fail review. | Paste the full task description, file paths, TDD requirements, and acceptance criteria into the prompt. Use the implementer-prompt template without shortcuts. |
+| "One worktree is enough for parallel tasks." | Two agents writing to the same worktree will race on `git checkout`, corrupt branch state, and produce merge conflicts. This is a known, documented failure mode. | Create one worktree per task via `prepare_delegation`. Never share worktrees between parallel agents. |
+| "I can fix review findings directly instead of re-dispatching." | The orchestrator must not write implementation code (Orchestrator Constraints rule). Fixing directly bypasses TDD, skips worktree isolation, and conflates orchestration with implementation. | Dispatch a fixer agent using `references/fixer-prompt.md` with adversarial verification posture. Let the subagent fix in the proper worktree with proper tests. |
+| "The subagent's self-assessment is sufficient for verifying completion." | Subagents are biased toward reporting success. They may miss failing tests, skip type checks, or misdiagnose root causes. Self-assessment is a known unreliable signal in multi-agent systems. | Independently verify: run tests in the worktree, check `git status` for uncommitted files, read test output yourself. Use the adversarial verification posture from `references/fixer-prompt.md`. |
+| "I'll just dispatch sequentially to avoid coordination complexity." | Sequential dispatch wastes wall-clock time proportional to task count. Independent tasks should run in parallel — that is the entire purpose of delegation. | Identify dependency edges in the plan. Dispatch all tasks without inbound dependencies in a single parallel batch. Sequence only what the dependency graph requires. |
+| "I can reuse context from the previous subagent's session." | Subagents do not share memory, state, or context windows. Attempting to reference "what the previous agent did" produces hallucinated continuations. | Follow the Fresh Context Per Task principle. Each prompt is self-contained. If Task B depends on Task A's output, wait for A to complete, read its artifacts, and include them in B's prompt. |

package/skills/generic/delegation/references/state-management.md

@@ -0,0 +1,84 @@
+# Delegation State Management
+
+State update patterns for workflow state during delegation. Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` for all mutations.
+
+## Read Tasks from State
+
+Instead of re-parsing plan, read task list with `action: "get"`, `query: "tasks"`. For status checks during monitoring, use `fields: ["tasks"]` to reduce response size.
+
+## Subagent Mode
+
+**On Task Dispatch:**
+```
+action: "set", featureId: "<id>", updates: {
+  "tasks[id=<taskId>]": { "status": "in_progress", "startedAt": "<ISO timestamp>" },
+  "worktrees.<wt-id>": { "branch": "<branch>", "taskId": "<taskId>", "status": "active" }
+}
+```
+
+**On Task Complete:**
+```
+action: "set", featureId: "<id>", updates: {
+  "tasks[id=<taskId>]": { "status": "complete", "completedAt": "<ISO timestamp>" }
+}
+```
+
+**On All Tasks Complete:**
+```
+action: "set", featureId: "<id>", phase: "review"
+```
+
+## Agent Team Mode (Single-Writer)
+
+Only the orchestrator mutates `workflow.tasks[]` via `exarchos_workflow set`. Hooks emit events but never mutate state directly.
+
+- **Step 2:** Store `nativeTaskId` from each `TaskCreate` return value
+- **Step 4:** Read `team.task.completed` events during monitoring, update task status
+- **Staleness:** 30-60s projection lag is acceptable — native task dependency unblocking is automatic
+
+For the three-layer consistency model, drift recovery, and eventual consistency details, see `agent-teams-saga.md`.
+
+## Benchmark Label
+
+After extracting tasks from the plan, check if ANY task has `testingStrategy.benchmarks: true`. If so, record in state:
+
+```
+action: "set", featureId: "<id>", updates: {
+  "verification.hasBenchmarks": true
+}
+```
+
+The `/exarchos:synthesize` skill reads `verification.hasBenchmarks` and applies the `has-benchmarks` label via `gh pr edit <number> --add-label has-benchmarks`.
+
+## Agent ID Tracking
+
+Workflow task state includes additional fields for resume-aware fixer flow:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agentId` | string | Claude Code agent ID for resume. Canonical source: `SubagentStop` hook payload. |
+| `agentResumed` | boolean | Whether this agent was resumed (vs. fresh dispatch). |
+| `lastExitReason` | string | Completion status (e.g., `"success"`, `"failure"`, `"timeout"`). Canonical source: `SubagentStop` hook payload. |
+
+The `SubagentStop` hook (`hooks/hooks.json`) is the **canonical source** for `agentId` and `lastExitReason`. When the hook fires for `exarchos-implementer` or `exarchos-fixer` agents, the orchestrator persists the hook payload fields into `tasks[id=taskId]`. This enables the resume-first strategy in the fixer flow: when a task fails, the orchestrator can resume the original agent with failure context rather than dispatching a fresh fixer.
+
+**State update on SubagentStop hook:**
+```text
+action: "set", featureId: "<id>", updates: {
+  "tasks[id=<taskId>]": {
+    "agentId": "<from SubagentStop hook payload: agent_id>",
+    "agentResumed": false,
+    "lastExitReason": "<from SubagentStop hook payload: exit_reason>"
+  }
+}
+```
+
+**State update on resume:**
+```text
+action: "set", featureId: "<id>", updates: {
+  "tasks[id=<taskId>]": {
+    "agentResumed": true,
+    "status": "in_progress"
+  }
+}
+```

package/skills/generic/delegation/references/testing-patterns.md

@@ -0,0 +1,146 @@
+# Testing Patterns
+
+Code patterns for TDD implementation. Referenced from `rules/tdd.md`.
+
+## Test File Co-location
+
+Test files live alongside their source files, not in a separate `tests/` directory.
+
+| Language | Source | Test |
+|----------|--------|------|
+| TypeScript | `src/foo.ts` | `src/foo.test.ts` |
+| C# | `Services/OrderService.cs` | `Services/OrderService.Tests.cs` |
+| Bash | `scripts/check-pr-comments.sh` | `scripts/check-pr-comments.test.sh` |
+
+## Naming Convention
+
+Tests use `Method_Scenario_Outcome` format:
+- TypeScript: `it('GetOrder_InvalidId_ReturnsNotFound', ...)`
+- C#: `public async Task GetOrder_InvalidId_ReturnsNotFound()`
+- Bash: function name `test_no_args_exit_2`
+
+## TypeScript (Vitest)
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+```
+
+### Test Pattern
+
+```typescript
+describe('ComponentName', () => {
+  describe('methodName', () => {
+    it('should do expected behavior when condition', async () => {
+      // Arrange
+      const input = createTestData();
+
+      // Act
+      const result = await component.method(input);
+
+      // Assert
+      expect(result).toBe(expected);
+    });
+  });
+});
+```
+
+### Mocking
+
+```typescript
+vi.mock('./dependency', () => ({ someFn: vi.fn() }));
+fetchMock.mockResponseOnce(JSON.stringify({ data: 'value' }));
+expect(mockFn).toHaveBeenCalledWith(expectedArgs);
+```
+
+## C# (TUnit)
+
+All tests MUST use `[Test]` attribute, be `async Task`, and await all assertions.
+
+### Test Pattern
+
+```csharp
+[Test]
+public async Task MethodName_Scenario_ExpectedOutcome()
+{
+    // Arrange
+    var mockRepo = Substitute.For<IRepository>();
+    mockRepo.FindAsync(Arg.Any<Guid>()).Returns(expectedOrder);
+    var sut = new OrderService(mockRepo);
+
+    // Act
+    var result = await sut.GetOrderAsync(orderId);
+
+    // Assert (MUST await)
+    await Assert.That(result.IsSuccess).IsTrue();
+    await Assert.That(result.Value.Id).IsEqualTo(orderId);
+}
+```
+
+### Assertions
+
+```csharp
+await Assert.That(actual).IsEqualTo(expected);
+await Assert.That(condition).IsTrue();
+await Assert.That(value).IsNotNull();
+await Assert.That(collection).Contains(item);
+await Assert.That(collection).HasCount(3);
+await Assert.That(() => sut.Method()).Throws<ArgumentException>();
+```
+
+### Parameterized Tests
+
+```csharp
+[Test]
+[Arguments(2, 3, 5)]
+[Arguments(0, 0, 0)]
+public async Task Add_VariousInputs_ReturnsExpectedSum(int a, int b, int expected)
+{
+    var result = _calculator.Add(a, b);
+    await Assert.That(result).IsEqualTo(expected);
+}
+```
+
+### Setup/Cleanup
+
+```csharp
+[Before(Test)]
+public async Task Setup() { _service = new Service(); }
+
+[After(Test)]
+public async Task Cleanup() { /* dispose */ }
+```
+
+### Mocking (NSubstitute)
+
+```csharp
+var mock = Substitute.For<IOrderService>();
+mock.GetOrderAsync(Arg.Any<Guid>()).Returns(Result<Order>.Success(order));
+await mock.Received(1).GetOrderAsync(expectedId);
+await mock.DidNotReceive().DeleteAsync(Arg.Any<Guid>());
+```
+
+## Property-Based Testing (fast-check)
+
+### When to Use
+
+- Data transformations (encode/decode, serialize/deserialize) -> Roundtrip
+- State machines (transitions, guards) -> Invariant
+- Collections/ordering (sort, filter, pagination) -> Idempotence
+- Mathematical operations (scoring, budgets) -> Bounds/constraints
+- Concurrency (optimistic locking) -> Linearizability
+
+### Import
+
+```typescript
+import { it, fc } from '@fast-check/vitest';
+```
+
+### Basic Usage
+
+```typescript
+it.prop([fc.array(fc.integer())], (arr) => {
+  expect(sort(sort(arr))).toEqual(sort(arr));
+});
+```
+
+See `pbt-patterns.md` for roundtrip, invariant, idempotence, and commutativity pattern templates.

package/skills/generic/delegation/references/troubleshooting.md

@@ -0,0 +1,109 @@
+# Delegation Troubleshooting
+
+## MCP Tool Call Failed
+If an Exarchos MCP tool returns an error:
+1. Check the error message — it usually contains specific guidance
+2. Verify the workflow state exists: call `exarchos_workflow` with `action: "get"` and the featureId
+3. If "version mismatch": another process updated state — retry the operation
+4. If state is corrupted: call `exarchos_workflow` with `action: "cancel"` and `dryRun: true`
+
+## State Desync
+If workflow state doesn't match git reality:
+1. The SessionStart hook runs reconciliation automatically on resume
+2. If manual check needed: compare state file with `git log` and branch state
+3. Update state via `exarchos_workflow` with `action: "set"` to match git truth
+
+## Worktree Creation Failed
+If `git worktree add` fails:
+1. Check if the branch already exists: `git branch --list <branch-name>`
+2. Check if a worktree already exists at the path: `git worktree list`
+3. If stale worktree: `git worktree prune` then retry
+4. If branch conflict: use a unique branch name
+
+## Subagent Not Responding
+If a spawned subagent doesn't respond:
+1. Check task output: use `TaskOutput` with the agent's task ID and `block: false`
+2. If the subagent is stuck: stop it with `TaskStop` and re-dispatch
+3. For Agent Teams: use Claude Code's native teammate messaging (Shift+Up/Down to select, then type)
+
+## Task Claim Conflict
+If `exarchos_orchestrate` with `action: "task_claim"` returns ALREADY_CLAIMED:
+1. Another agent already claimed this task — skip it
+2. Check task status via `exarchos_view` with `action: "tasks"` and `filter: { "taskId": "<id>" }`
+3. Do not re-dispatch — the other agent is handling it
+
+## Common Workflow Errors
+
+### Error: `all-tasks-complete not satisfied: N task(s) incomplete`
+
+**Cause:** Claude Code TaskList was updated via `TaskUpdate`, but exarchos workflow state was not synced. The `all-tasks-complete` guard checks the exarchos workflow `tasks[]` array, NOT Claude Code's native TaskList.
+
+**Solution:** Before transitioning to review, call `exarchos_workflow set` with updated task statuses:
+```json
+{
+  "action": "set",
+  "featureId": "<id>",
+  "updates": {
+    "tasks": [
+      { "id": "1", "status": "complete" },
+      { "id": "2", "status": "complete" }
+    ]
+  }
+}
+```
+
+### Error: `Expected object, received array` when setting reviews
+
+**Cause:** The `reviews` field requires a keyed object, not an array.
+
+**Solution:** Use named keys for each review:
+```json
+{
+  "reviews": {
+    "spec-review": { "status": "pass", "issues": [] },
+    "quality-review": { "status": "pass", "issues": [] }
+  }
+}
+```
+
+### Error: `No transition from 'explore' to 'plan'`
+
+**Cause:** Refactor workflows use different phase names than feature workflows. Feature uses `plan`, refactor uses `overhaul-plan` (overhaul track) or `polish-implement` (polish track).
+
+**Solution:** Check the `validTargets` array in the error response. For refactor overhaul: use `overhaul-plan`. For refactor polish: use `polish-implement`. Use `exarchos_workflow get` with `query: "phase"` to confirm current phase (fast-path for scalar queries).
+
+### Error: `invalid_enum_value` on event type (e.g., `wave.completed`)
+
+**Cause:** The event type string doesn't match the enum. Common mistakes: `wave.completed` (not a valid type), `task.progress` (use `task.progressed`).
+
+**Solution:** Use exact type strings from the Event Emission Contract table in SKILL.md. Valid team delegation types: `team.spawned`, `team.task.planned`, `team.teammate.dispatched`, `team.disbanded`, `team.task.completed`, `team.task.failed`.
+
+### Error: `Guard 'triage-complete' failed: triage-complete not satisfied`
+
+**Cause:** The guard checks for `state.triage.symptom`, not `state.triage.complete` or `state.triageComplete`.
+
+**Solution:** Set the `triage.symptom` field:
+```json
+{
+  "action": "set",
+  "featureId": "<id>",
+  "updates": {
+    "triage": { "symptom": "<description of the bug or issue>" }
+  }
+}
+```
+
+### Error: `Guard 'root-cause-found' failed`
+
+**Cause:** Guard checks `state.investigation.rootCause`, not `state.rootCause`.
+
+**Solution:** Set `investigation.rootCause`:
+```json
+{
+  "action": "set",
+  "featureId": "<id>",
+  "updates": {
+    "investigation": { "rootCause": "<root cause description>" }
+  }
+}
+```

package/skills/generic/delegation/references/worked-example.md

@@ -0,0 +1,104 @@
+# Delegation Worked Example
+
+Complete trace of a two-task delegation: happy path for task-001, failure recovery for task-002.
+
+## Context
+
+Feature: `add-email-validation` with two plan tasks:
+- **task-001:** Email format validator (`src/validators/email.ts`)
+- **task-002:** Domain MX check (`src/validators/domain.ts`)
+
+## 1. Prepare
+
+Call the composite action:
+
+```typescript
+exarchos_orchestrate({
+  action: "prepare_delegation",
+  featureId: "add-email-validation",
+  tasks: [
+    { id: "task-001", title: "Email format validator", modules: ["src/validators"] },
+    { id: "task-002", title: "Domain MX check", modules: ["src/validators"] }
+  ]
+})
+```
+
+Response:
+```json
+{
+  "ready": true,
+  "worktrees": [
+    { "taskId": "task-001", "path": "/project/.worktrees/task-001" },
+    { "taskId": "task-002", "path": "/project/.worktrees/task-002" }
+  ],
+  "qualityHints": []
+}
+```
+
+## 2. Dispatch
+
+Build two self-contained prompts from `implementer-prompt.md` and dispatch in a single message:
+
+```typescript
+Task({
+  subagent_type: "general-purpose", model: "opus", run_in_background: true,
+  description: "Implement task-001: Email format validator",
+  prompt: `# Task: Email Format Validator\n\n## Working Directory\n/project/.worktrees/task-001\n\n[Full implementer prompt with TDD, file paths, acceptance criteria...]`
+})
+
+Task({
+  subagent_type: "general-purpose", model: "opus", run_in_background: true,
+  description: "Implement task-002: Domain MX check",
+  prompt: `# Task: Domain MX Check\n\n## Working Directory\n/project/.worktrees/task-002\n\n[Full implementer prompt with TDD, file paths, acceptance criteria...]`
+})
+```
+
+## 3. Monitor — Happy Path (task-001)
+
+```typescript
+TaskOutput({ task_id: "task-001-id", block: true })
+// Result: tests pass, implementation complete
+```
+
+Update workflow state:
+```typescript
+exarchos_workflow({ action: "set", featureId: "add-email-validation",
+  updates: { "tasks[0].status": "complete" } })
+```
+
+Emit gate event:
+```typescript
+exarchos_event({ action: "append", stream: "add-email-validation",
+  event: { type: "gate.executed", data: { gateName: "post-delegation-check", layer: "CI", passed: true } } })
+```
+
+## 4. Monitor — Failure Recovery (task-002)
+
+```typescript
+TaskOutput({ task_id: "task-002-id", block: true })
+// Result: test fails — DNS mock not wired, MX lookup hits network
+```
+
+**Do NOT trust the implementer's summary.** Read the test output independently:
+- Root cause: Missing `vi.mock('dns')` — real DNS called during test.
+
+Re-dispatch with fixer prompt in the same worktree:
+
+```typescript
+Task({
+  subagent_type: "general-purpose", model: "opus",
+  description: "Fix task-002: DNS mock missing",
+  prompt: `# Fix Task: DNS Mock Missing\n\n## Adversarial Verification Posture\nIndependently verify the failure...\n\n## Working Directory\n/project/.worktrees/task-002\n\n## Issue to Fix\n**File:** src/validators/domain.test.ts\n**Problem:** Missing vi.mock('dns') — test makes real network calls\n**Fix:** Add vi.mock('dns') with MX record stub\n\n## Verification\nRun: npm run test:run\nAll tests must pass without network access.`
+})
+```
+
+After fix succeeds, update state and emit gate event as in the happy path.
+
+## 5. Transition
+
+Both tasks complete. Auto-continue:
+```typescript
+exarchos_workflow({ action: "set", featureId: "add-email-validation",
+  updates: { phase: "review" } })
+Skill({ skill: "exarchos:review", args: "docs/plans/add-email-validation.md" })
+```