@lvlup-sw/exarchos 2.0.1

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

@@ -0,0 +1,154 @@
+# 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, use Graphite to commit and push:
+```bash
+gt modify -m "fix: address PR review feedback"
+gt submit --no-interactive
+```
+
+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/delegation/references/state-management.md

@@ -0,0 +1,51 @@
+# Delegation State Management
+
+State update patterns for workflow state during delegation. Use `mcp__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 `/synthesize` skill reads `verification.hasBenchmarks` and applies the `has-benchmarks` label via `gh pr edit <number> --add-label has-benchmarks`.

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

@@ -0,0 +1,129 @@
+# Testing Patterns
+
+Code patterns for TDD implementation. Referenced from `rules/tdd.md`.
+
+## 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/delegation/references/troubleshooting.md

@@ -0,0 +1,33 @@
+# 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

package/skills/delegation/references/workflow-steps.md

@@ -0,0 +1,127 @@
+---
+name: workflow-steps
+---
+
+# Delegation Workflow Steps
+
+## Step 1: Prepare Environment
+
+For parallel tasks, create worktrees:
+```bash
+git worktree add .worktrees/task-001 feature/task-001
+cd .worktrees/task-001 && npm install
+```
+
+## Step 2: Extract Task Details
+
+From implementation plan, extract for each task:
+- Full task description
+- Files to create/modify
+- Test file paths
+- Expected test names
+- Dependencies
+
+## Step 3: Create TodoWrite Entries
+
+Track all delegated tasks:
+```typescript
+TodoWrite({
+  todos: [
+    { content: "Task 001: User model", status: "in_progress", activeForm: "Implementing user model" },
+    { content: "Task 002: Auth endpoints", status: "pending", activeForm: "Implementing auth endpoints" }
+  ]
+})
+```
+
+## Step 4: Dispatch Implementers
+
+**Parallel dispatch:**
+```typescript
+// Launch multiple in single message for parallel execution
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  run_in_background: true,
+  description: "Implement task 001",
+  prompt: "[Full implementer prompt]"
+})
+
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  run_in_background: true,
+  description: "Implement task 002",
+  prompt: "[Full implementer prompt]"
+})
+```
+
+### Agent Teams Dispatch (enhanced)
+
+When using `--mode agent-team`:
+1. **Pre-delegation intelligence:** Query `exarchos_view team_performance` for historical metrics
+2. **Team creation:** Create team with named teammates, each assigned to a worktree
+3. **Task list setup:** Create native Claude Code tasks with dependency annotations
+4. **Natural language delegation:** Describe tasks to teammates with full implementer prompt content
+5. **Event emission:** Append `team.spawned` event with teamSize, teammateNames, taskCount
+
+Teammates self-coordinate via shared task list. No `Task()` calls needed.
+
+## Step 5: Monitor Progress
+
+For background tasks:
+```typescript
+TaskOutput({ task_id: "task-001-id", block: true })
+```
+
+### Agent Teams Monitoring (enhanced)
+
+When using `--mode agent-team`:
+- Teammates visible in tmux split panes
+- `TeammateIdle` hook auto-runs quality gates (typecheck, tests, clean worktree)
+- On quality pass: emits `team.task.completed` event with performance data
+- On quality fail: exit code 2 sends feedback, emits `team.task.failed` event
+- Hook scans task graph for newly unblocked tasks for teammates to claim
+- Orchestrator monitors via `exarchos_view delegation_timeline` for bottleneck detection
+
+## Step 6: Collect Results
+
+When tasks complete, run the post-delegation check:
+
+```bash
+bash scripts/post-delegation-check.sh \
+  --state-file <path-to-state.json> \
+  --repo-root <project-root> \
+  [--skip-tests]
+```
+
+**Validates:**
+- State file exists and is valid JSON
+- Tasks array has entries
+- All tasks report "complete" status
+- Per-worktree test runs pass (unless `--skip-tests`)
+- State file consistency (all tasks have id and status fields)
+
+**On exit 0:** All delegation results collected and verified. Update TodoWrite status, then check if schema sync is needed (Step 7) and proceed to review phase.
+
+**On exit 1:** Failures detected. Review the per-task status report. Address incomplete tasks or failing tests before proceeding.
+
+### Agent Teams Collection (enhanced)
+
+When using `--mode agent-team`:
+- `TeammateIdle` hook bridges real-time Agent Teams with persistent Exarchos state
+- On quality gate pass: task marked "complete" + `team.task.completed` event emitted
+- On quality gate fail: exit code 2 sends feedback + `team.task.failed` event emitted
+- Rich event data: taskId, teammateName, durationMs, filesChanged, testsPassed
+- After all teammates finish: append `team.disbanded` event with summary metrics
+- Run `post-delegation-check.sh` as usual for final validation
+
+## Step 7: Schema Sync (Auto-Detection)
+
+After all tasks complete, check if API files were modified:
+
+```bash
+bash scripts/needs-schema-sync.sh --repo-root <path> [--base-branch main]
+```
+
+**On exit 0:** No sync needed — proceed to review.
+**On exit 1:** Sync needed — API files modified (`*Endpoints.cs`, `Models/*.cs`, `Requests/*.cs`, `Responses/*.cs`, `Dtos/*.cs`). Run `npm run sync:schemas` and commit via Graphite before proceeding. See `@skills/sync-schemas/SKILL.md`.

package/skills/delegation/references/worktree-enforcement.md

@@ -0,0 +1,64 @@
+---
+name: worktree-enforcement
+---
+
+# Worktree Enforcement (MANDATORY)
+
+All implementation tasks MUST run in isolated worktrees, not the main project root.
+
+## Why Worktrees Are Required
+
+- **Isolation:** Prevents merge conflicts between parallel tasks
+- **Safety:** Protects main project state
+- **Parallelism:** Enables multiple subagents to work simultaneously
+- **Recovery:** Easy rollback via branch deletion
+
+## Pre-Dispatch Checklist
+
+Before dispatching ANY implementer, run the worktree setup script:
+
+```bash
+bash scripts/setup-worktree.sh \
+  --repo-root <project-root> \
+  --task-id <task-id> \
+  --task-name <task-name> \
+  [--base-branch main] \
+  [--skip-tests]
+```
+
+**Validates:**
+- `.worktrees/` is gitignored (adds to `.gitignore` if missing)
+- Feature branch created (`feature/<task-id>-<task-name>` from base branch)
+- Git worktree added at `.worktrees/<task-id>-<task-name>`
+- `npm install` ran in worktree
+- Baseline tests pass in worktree
+
+**On exit 0:** Worktree is ready. Proceed with implementer dispatch.
+
+**On exit 1:** Setup failed. Review the markdown checklist output for which step failed. Fix the issue before dispatching.
+
+**On exit 2:** Usage error. Check required arguments: `--repo-root`, `--task-id`, `--task-name`.
+
+## Worktree State Tracking
+
+Track worktrees in the workflow state file using `mcp__exarchos__exarchos_workflow` with `action: "set"`:
+- Set `worktrees.<worktree-id>` to an object containing `branch`, `status`, and either `taskId` (single task) or `tasks` (array of task IDs for multi-task worktrees)
+
+## Implementer Prompt Requirements
+
+Include in ALL implementer prompts:
+
+1. **Absolute worktree path** as Working Directory
+2. **Worktree verification block** (from implementer-prompt.md template)
+3. **Abort instructions** if not in worktree
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Make subagents read plan files | Provide full task text in prompt |
+| Use default model for coding | Specify `model: "opus"` |
+| Send sequential Task calls | Batch parallel tasks in one message |
+| Skip worktree for parallel work | Create isolated worktrees |
+| Forget to track in TodoWrite | Update status for every task |
+| Skip TDD requirements | Include TDD instructions in prompt |