@lvlup-sw/exarchos 2.0.1

package/skills/delegation/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: delegation
+description: "Dispatch implementation tasks to agent teammates in git worktrees. Use when the user says 'delegate', 'dispatch tasks', 'assign work', 'delegate tasks', or runs /delegate. Spawns teammates, creates worktrees, monitors progress, and collects results. Supports --fixes flag for review finding remediation. Do NOT use for single-file changes or polish-track refactors."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: delegate
+---
+
+# Delegation Skill
+
+## Overview
+
+Dispatch implementation tasks to Claude Code subagents with proper context and TDD requirements.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/delegate` command
+- Implementation plan is ready
+- User wants to parallelize work
+- Tasks are ready for execution
+
+## Delegation Modes
+
+| Mode | Mechanism | Best for |
+|------|-----------|----------|
+| `subagent` (default) | `Task` with `run_in_background` | 1-3 independent tasks, CI, headless |
+| `agent-team` | `Task` with `team_name` | 3+ interdependent tasks, interactive sessions |
+
+**Auto-detection:** tmux + `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` → `agent-team`. Otherwise → `subagent`. Override with `/delegate --mode subagent|agent-team`.
+
+**CRITICAL:** Always specify `model: "opus"` for coding tasks.
+
+```typescript
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  description: "Implement user model",
+  prompt: `[Full implementer prompt from template]`
+})
+```
+
+For agent-team event payloads and YAML examples, see `references/agent-teams-saga.md`. For adaptive team composition, see `references/adaptive-orchestration.md`.
+
+## Controller Responsibilities
+
+The orchestrator (you) MUST:
+
+1. **Extract tasks upfront** — Read plan, extract all task details
+2. **Provide full context** — Never make subagents read files for task info
+3. **Include TDD requirements** — Use implementer prompt template
+4. **Track progress** — TodoWrite (subagent) or native TaskList (agent-team)
+5. **Set up worktrees** — For parallel execution
+6. **Single-writer discipline** (agent-team) — Only the orchestrator mutates `workflow.tasks[]`
+
+## Implementer Prompt Template
+
+Use `@skills/delegation/references/implementer-prompt.md` as template for Task tool prompts.
+
+**Conditional PBT:** When a task has `testingStrategy.propertyTests: true`, include the PBT section from `references/pbt-patterns.md`. When `false`, omit entirely.
+
+## Delegation Workflow — Subagent Mode
+
+1. Prepare worktrees — `scripts/setup-worktree.sh`
+2. Extract task details from plan
+3. Check for benchmark tasks → set `verification.hasBenchmarks` in state
+4. Create TodoWrite entries for tracking
+5. Dispatch parallel subagents via Task tool
+6. Monitor progress via TaskOutput
+7. Collect and verify — `scripts/post-delegation-check.sh`
+8. Schema sync if API files modified
+
+For detailed step instructions, see `references/workflow-steps.md`.
+
+## Delegation Workflow — Agent Team Mode (6-Step Saga)
+
+Follow the event-first saga: **emit event → execute side effect** at every step.
+
+| Step | Action | Type |
+|------|--------|------|
+| Pre-flight | Read tasks, prepare worktrees | — |
+| 1 | Create team | Compensable |
+| 2 | Create native tasks (batched) | Compensable |
+| 3 | Spawn teammates (**pivot**) | Point of no return |
+| 4 | Monitor (tiered) | Retryable |
+| 5 | Disband | Retryable |
+| 6 | Transition to review | Retryable |
+
+For step-by-step instructions, idempotency checks, compensation protocol, and event payloads, see `references/agent-teams-saga.md`.
+
+## Parallel Execution Strategy
+
+Dispatch parallel tasks in a single message with multiple Task calls. See `references/parallel-strategy.md` for group identification, dispatching patterns, and model selection.
+
+## Worktree Enforcement (MANDATORY)
+
+All tasks MUST run in isolated worktrees. Use `scripts/setup-worktree.sh` for setup.
+
+Before dispatching: run `scripts/verify-worktree.sh --cwd <path>`. If exit 1: stop dispatch, report invalid worktree. See `references/worktree-enforcement.md`.
+
+## State Management
+
+Track task progress in workflow state for context persistence. Read tasks with `action: "get"`, `query: "tasks"`. For benchmark labeling, state patterns, and agent-team consistency model, see `references/state-management.md`.
+
+## Fix Mode (--fixes)
+
+Handles review failures instead of initial implementation. Uses `references/fixer-prompt.md` template, dispatches fix tasks per issue, then re-invokes review.
+
+**Arguments:** `--fixes <state-file-path>` — state JSON containing review results in `.reviews.<taskId>.specReview` or `.reviews.<taskId>.qualityReview`.
+
+For detailed process, see `references/fix-mode.md`. For PR feedback workflows (`--pr-fixes`), see `references/pr-fixes-mode.md`.
+
+## Completion Criteria
+
+- [ ] All tasks extracted from plan (or read from state)
+- [ ] Worktrees created and validated via verify-worktree.sh
+- [ ] Implementers dispatched with full context
+- [ ] All tasks report completion, all tests pass
+- [ ] Schema sync run if API files modified
+- [ ] State file reflects all task completions
+
+## Transition
+
+After all tasks complete, **auto-continue immediately** (no user confirmation):
+
+1. Verify all `tasks[].status === 'complete'` in workflow state
+2. Update state: `action: "set"`, `phase: "review"`
+3. Invoke: `Skill({ skill: "exarchos:review", args: "<plan-path>" })`
+
+This is NOT a human checkpoint — workflow continues autonomously.
+
+## Known Limitations
+
+- **Agent Teams:** No session resumption, task status lag, one team per session, no nested teams, requires tmux/iTerm2. Cold start falls back to plan's parallel group strategy.
+- **Subagents:** No visual monitoring, individual context windows, limited observability.
+
+## Troubleshooting
+
+See `references/troubleshooting.md` for MCP tool failures, state desync, worktree creation, teammate spawn timeouts, and task claim conflicts.
+
+## Exarchos Integration
+
+**Subagent mode:** Emit `task.assigned` on dispatch, use `exarchos_orchestrate task_complete` on completion. Phase transitions auto-emit `workflow.transition`.
+
+**Agent-team mode:** Follow the 6-step saga. Do NOT mix with subagent-mode patterns — the TeammateIdle hook handles completion. See `references/agent-teams-saga.md`.
+
+**Claim guard** (subagent only): Use `exarchos_orchestrate task_claim` for optimistic concurrency. On `ALREADY_CLAIMED`, skip and check status before re-dispatching.

package/skills/delegation/references/adaptive-orchestration.md

@@ -0,0 +1,31 @@
+# Adaptive Orchestration
+
+When using Agent Teams mode, the orchestrator can leverage historical data for smarter team composition.
+
+## Pre-Delegation Intelligence
+
+Before creating the team, query the TeamPerformanceView for historical teammate metrics:
+- `exarchos_view` with `action: 'team_performance'` -- teammate efficiency, module expertise, quality gate pass rates
+- Use `synthesizeIntelligence()` from SubagentStart hook for historical fix-cycle patterns per module
+
+## Team Composition
+
+Informed by historical metrics:
+- **Team sizing:** Use `teamSizing.avgTasksPerTeammate` to determine optimal teammate count
+- **Task assignment:** Match modules to teammates with relevant `moduleExpertise`
+- **Cold start:** When no historical data exists, fall back to plan's parallel groups for sizing
+
+## Guard-Aware Task Graph
+
+Before creating the native Claude Code task list:
+1. Build a dependency graph from plan task `blockedBy` fields
+2. Identify the critical path through the dependency chain
+3. Front-load independent tasks for maximum parallelism
+4. On TeammateIdle, scan the task graph for newly unblocked tasks (tasks whose `blockedBy` dependencies are all completed) so teammates can claim them
+
+## Intelligence Views
+
+Two CQRS views provide team analytics:
+
+- `exarchos_view` with `action: 'team_performance'` -- Query before delegation for team sizing and module assignment. Returns teammate metrics (tasks completed, avg duration, module expertise, quality gate pass rates) and team sizing recommendations.
+- `exarchos_view` with `action: 'delegation_timeline'` -- Query after delegation for retrospective analysis. Returns task timeline with bottleneck detection (longest task, blocking dependencies).

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

@@ -0,0 +1,248 @@
+# Agent Teams Delegation Saga
+
+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"
+    teamName: {featureId}
+    teamSize: {N}
+    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
+```
+
+### 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 (includes teamName, teamSize, 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.
+- `team.context.injected` -- From SubagentStart hook (includes phase, toolsAvailable)
+
+**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/delegation/references/fix-mode.md

@@ -0,0 +1,74 @@
+---
+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__exarchos__exarchos_workflow` with `action: "get"`:
+   - Query `reviews` for review failures
+
+2. **Extract fix tasks** from failure reports:
+
+   ```bash
+   bash scripts/extract-fix-tasks.sh --state-file <path> [--review-report <path>] [--repo-root <path>]
+   ```
+
+   **On exit 0:** Tasks extracted successfully (JSON array on stdout).
+   **On exit 1:** 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** (same as implementers, different prompt):
+   ```typescript
+   Task({
+     subagent_type: "general-purpose",
+     model: "opus",
+     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>" })
+   ```
+
+## 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/delegation/references/fixer-prompt.md

@@ -0,0 +1,162 @@
+# Fixer Prompt Template
+
+Use this template when dispatching fix tasks via the Task tool after review failures.
+
+## 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