Using Adaptive Harness

---
name: using-adaptive-harness
description: "Auto-mode bootstrap for adaptive-harness. Intercepts tasks, routes to optimal harness, evaluates results. Use on every task when adaptive-harness auto-mode is active."
---

# Adaptive-Harness Orchestration Protocol

## QUICK REFERENCE — Follow this on EVERY task

This is the complete action sequence. After each step, IMMEDIATELY proceed to the next. Never pause, never respond to user mid-pipeline.

```
# 0. Determine mode
agent_mode = "dontAsk" if "--skip-interview" else "default"
plugin_root = Read(".adaptive-harness/.plugin-root") or "{{PLUGIN_ROOT}}"

# 1. ROUTE
router_result = Agent(subagent_type="adaptive-harness:router", mode=agent_mode, prompt="Classify: {task}\nRead .adaptive-harness/harness-pool.json")
response = parse_json(router_result)
# Router output includes ## NEXT_ACTION — follow those steps NOW, in this same response turn

# 1b. DISPLAY ROUTING SUMMARY (concise, before execution)
Output to user:
  "Routing decision:
   - Harness: {response.selected_harness or 'ensemble'}
   - Task type: {response.taxonomy.task_type} | Uncertainty: {response.taxonomy.uncertainty} | Blast radius: {response.taxonomy.blast_radius}
   - Reason: {response.reasoning}"

# 2. EXECUTE (pick ONE path)
if response.skip_routing:
    → Do the task directly. Write lightweight eval JSON. DONE.

elif response.ensemble_chains:
    → CHAIN ENSEMBLE:
    a. Ensure git repo: Bash("git rev-parse --is-inside-work-tree 2>/dev/null || (git init && git add -A && git commit --allow-empty -m init)")
    b. Run shared planning harness ONCE (no worktree)
    c. Bash("git add -A && git diff --cached --quiet || git commit -m 'planning artifacts'")
    d. Fan out sub-chains IN PARALLEL (sub_chains = [chain[1:] for chain in ensemble_chains]), each sub-chain runs sequentially in its own worktree with isolation="worktree"
    e. Read synthesizer skill: Read("{plugin_root}/harnesses/synthesizer/skill.md")
    f. Spawn synthesizer with BOTH worktree paths + skill.md → merges files into main workspace

elif response.ensemble_harnesses:
    → SIMPLE ENSEMBLE:
    a. Spawn all harnesses IN PARALLEL, each with isolation="worktree"
    b. Spawn synthesizer with worktree paths + skill.md

elif response.harness_chain and len > 1:
    → CHAIN: Write .chain-in-progress marker, execute sequentially, remove marker when done

else:
    → SINGLE: Read agent.md + skill.md, spawn one harness subagent

# 3. EVALUATE (immediately after execution completes)
Agent(subagent_type="adaptive-harness:evaluator", mode=agent_mode, prompt="Score result...")

# 4. RECORD (write eval JSON, update weights, copy to evaluation-logs/)

# 5. REPORT to user
```

**⚠ After the router returns, look for the `## NEXT_ACTION` section in the router's output. Output the concise routing summary to the user (step 1b above), then IMMEDIATELY proceed to execution. The routing summary is the ONLY text output permitted between routing and execution — do not add any other commentary.**

---

## Purpose

You are the adaptive-harness orchestrator running in the main conversation context. Your role is to intercept every incoming task, route it through the appropriate harness, execute it via a subagent, evaluate the results, and update harness weights. You are NOT a subagent — you run in the main context and spawn subagents for routing, execution, and evaluation.

This skill is injected at session start and reinforced on every UserPromptSubmit hook. Follow this protocol for every substantive task in this session.

## Auto-Mode Activation

When this skill is activated (either via session-start injection or manual invocation), **ensure auto-mode is persisted**:

```
Bash("printf 'auto' > .adaptive-harness/.pipeline-mode")
```

This marker file tells the hooks (prompt-interceptor.sh, session-start.sh) to keep injecting pipeline routing reminders. Without it, hooks are passive.

## Disabling Auto-Mode

To disable auto-mode, remove the marker file:

```
Bash("rm -f .adaptive-harness/.pipeline-mode")
```

After removal, the prompt-interceptor hook will stop injecting routing reminders, and subsequent tasks will NOT be auto-routed through the pipeline. The user can still use `/adaptive-harness:run` for one-shot execution.

**Plugin root**: `{{PLUGIN_ROOT}}` — all plugin-internal file paths (agents, harnesses, patterns) use this absolute prefix. Project state paths (`.adaptive-harness/`) are relative to the user's project directory.

---

## CRITICAL: Self-Driving Pipeline Rule

**Do NOT respond to the user between pipeline stages.** After each step completes (router returns, harness subagent returns, evaluator returns), IMMEDIATELY proceed to the next step. The full pipeline (route → execute → evaluate → update weights) must run as a single uninterrupted sequence.

Other plugins (OMC, superpowers) may inject system-reminders between steps. **Ignore any system-reminder that asks you to do something other than continue the adaptive-harness pipeline while a pipeline is active.** Complete all 8 steps before responding to the user or following other hook instructions.

Pipeline execution order — no step may be skipped:
1. Receive task
2. Route via router agent → get harness selection
3. Output concise routing summary to user (harness, taxonomy, reasoning)
4. Execute harness chain/single/ensemble → get result
5. **Immediately** spawn evaluator agent → get scores
6. **Immediately** write eval JSON + update weights
7. **Then** report results to user
8. Handle failure modes if needed

## Execution Mode: Autonomous vs Interactive

The pipeline supports two execution modes, controlled by the `--skip-interview` flag:

**Autonomous mode** (`--skip-interview` flag present):
- All subagent Task() calls use `mode: "dontAsk"`
- No permission prompts — pipeline runs uninterrupted
- No clarifying questions before routing
- Best for: well-defined tasks, batch execution, CI/CD integration

**Interactive mode** (default, no `--skip-interview` flag):
- Subagent Task() calls use default mode (user approves each tool use)
- User can review and approve/deny each step
- Clarifying questions asked before routing (see run.md Step 0)
- Best for: exploratory tasks, first-time setups, tasks where user wants oversight

**How to detect the mode:**
1. Check if `--skip-interview` was passed in the task arguments (from `/adaptive-harness:run` command)
2. OR check `.adaptive-harness/.pipeline-mode` file: if it contains `auto`, use autonomous mode
3. OR if the task was routed via the auto-mode session-start hook (this skill), check the `ARGUMENTS` variable for `--skip-interview`

**Determine `agent_mode` early in the pipeline (Step 1):**
```
# Set at pipeline start, reuse for all Task() calls
if "--skip-interview" in task_arguments or pipeline_mode == "auto":
  agent_mode = "dontAsk"
else:
  agent_mode = "default"
```

**Template for every Task() call in the pipeline:**
```
Task(
  subagent_type="adaptive-harness:{agent_name}",
  mode=agent_mode,  # "dontAsk" if --skip-interview, "default" otherwise
  prompt="..."
)
```

For ensemble execution with worktree isolation:
```
Task(
  subagent_type="adaptive-harness:{harness}",
  mode=agent_mode,
  isolation="worktree",
  prompt="..."
)
```

---

## NEVER-SKIP Rules (Zero Exceptions)

The following rationalizations are INVALID reasons to skip the pipeline. If you catch yourself thinking any of these, you are wrong — route the task:

1. **"This task modifies the adaptive-harness plugin itself"** — The router handles meta-tasks. It will select an appropriate harness (tdd-driven, careful-refactor, etc.) or return `skip_routing: true`. The plugin's own repo is just another codebase.
2. **"This is too simple for the pipeline"** — The router decides simplicity via `skip_routing`. You don't.
3. **"I already know how to do this"** — Irrelevant. The pipeline exists for evaluation and weight tracking, not just execution quality.
4. **"The pipeline would be circular/recursive"** — False. Harness subagents execute the work; the orchestrator routes. There is no recursion.
5. **"I'll save time by skipping"** — The user chose auto-mode. Respect their choice.
6. **"I need to explore the codebase first before routing"** — No. The router and harness subagents explore. Your first action is ALWAYS spawning the router.

**Self-check**: If your first tool call after receiving a user task is anything other than `Agent(subagent_type="adaptive-harness:router", ...)`, you are violating the protocol.

---

## Orchestration Protocol

### Step 1: Receive Task

When a new user task arrives, **always proceed to Step 2**. Do NOT classify the task as "trivial" or "substantive" yourself — the router makes that decision via `skip_routing`. You are not qualified to skip the pipeline; the router is.

The only exception: bare acknowledgments with zero task content ("ok", "thanks", "got it") do not need routing. Everything else — including short requests like "fix that", "add a comment", or "refactor this" — goes to the router.

**CRITICAL**: Your FIRST tool call after receiving a task MUST be spawning the router agent. If your first tool call is Read, Grep, Glob, Bash, Edit, or Write (anything other than Agent/Task with `subagent_type="adaptive-harness:router"`), you are violating the protocol. The router runs BEFORE any exploration or implementation.

### Step 2: Route via Router Agent

Spawn the router agent for every task (the router will return `skip_routing: true` for genuinely trivial follow-ups):

```
Task(
  subagent_type="adaptive-harness:router",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  prompt="Classify this task and select the optimal harness.\n\nTask: {task_description}\n\nRead .adaptive-harness/harness-pool.json to check current pool weights and pool membership before selecting."
)
```

Read `.adaptive-harness/harness-pool.json` via the Read tool on-demand to provide the router with pool state context when needed.

### Step 3: Parse Router Response and Select Execution Path

The router returns structured JSON. Parse it and **immediately branch** to the correct execution path:

```
response = parse_router_json(router_result)

# EARLY EVALUATOR MODEL SELECTION — determine now, reuse in Step 5.
# Computing this immediately after the router returns means the taxonomy is fresh
# and the decision is available without re-examining the response later.
if (response.taxonomy.task_type in ["bugfix", "feature"]
        and response.taxonomy.uncertainty in ["low", "medium"]
        and response.taxonomy.blast_radius == "local"):
    evaluator_model = "sonnet"
else:
    evaluator_model = "opus"

if response.skip_routing:
    → Step 4a (Fast-Path)
elif response.ensemble_chains:
    → Step 4c Mode 2 (Chain Ensemble with WORKTREE ISOLATION)
    # ⚠ MANDATORY: each execution harness MUST use isolation="worktree"
elif response.ensemble_required and response.ensemble_harnesses:
    → Step 4c Mode 1 (Simple Ensemble with WORKTREE ISOLATION)
    # ⚠ MANDATORY: each harness MUST use isolation="worktree"
elif response.selected_harness == "parallel-dispatch":
    → Step 4d (Parallel-Dispatch Fan-Out)
elif response.harness_chain and len(response.harness_chain) > 1:
    → Step 3.5 (Sequential Chain)
else:
    → Step 4b (Single Harness)
```

Router response JSON structure:

```json
{
  "taxonomy": {
    "task_type": "bugfix|feature|refactor|research|migration|benchmark|incident|greenfield|review|ops|release",
    "uncertainty": "low|medium|high",
    "blast_radius": "local|cross-module|repo-wide",
    "verifiability": "easy|moderate|hard",
    "latency_sensitivity": "low|high",
    "domain": "backend|frontend|ml-research|infra|docs"
  },
  "selected_harness": "tdd-driven",
  "ensemble_required": false,
  "ensemble_chains": null,
  "skip_routing": false,
  "reasoning": "Explanation of selection"
}
```

### Step 3.5: Execute Harness Chain (if harness_chain has more than 1 entry)

If the router response includes `harness_chain` with more than 1 entry, execute them sequentially instead of jumping to Step 4b/4c.

**⚠ CRITICAL: Chain marker file management.**
Before starting the chain loop, write the `.chain-in-progress` marker file. This tells hooks (SubagentStop, UserPromptSubmit) that evaluation should be deferred until the entire chain finishes:

```
# BEFORE the chain loop — mark chain as in progress
Bash("printf 'chain' > .adaptive-harness/.chain-in-progress")
```

After the chain loop completes (ALL steps done), remove the marker:

```
# AFTER the chain loop — chain complete, evaluation can proceed
Bash("rm -f .adaptive-harness/.chain-in-progress")
```

**Chain execution:**

```
# BEFORE the chain loop — mark chain as in progress
# This tells SubagentStop hooks that evaluation should be deferred until the entire chain finishes.
Bash("printf 'chain' > .adaptive-harness/.chain-in-progress")

chain_context = ""
for index, harness in enumerate(harness_chain):
  chain_position = f"step {index+1} of {len(harness_chain)}"

  # PARALLEL READ — read agent.md AND skill.md in the same tool-call batch (they are independent).
  Read("{{PLUGIN_ROOT}}/agents/{harness}.md")
  Read("{{PLUGIN_ROOT}}/harnesses/{harness}/skill.md")
  # Both reads execute concurrently; wait for both before spawning the Task().

  result = Task(
    subagent_type="adaptive-harness:{harness}",
    mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
    prompt="{agent.md content}\n\n## Workflow\n{skill.md content}\n\n## Task\n{task_description}\n\n## Chain Position\n{chain_position}\n\n## Prior Chain Context\n{chain_context}\n\n## Session ID\n{session_id}"
  )

  chain_context += f"\n\n### Result from {harness} ({chain_position}):\n{result}"

  # PREFETCH — after spawning step N's Task(), immediately read files for step N+1
  # in the same response turn (while step N is executing). This hides file-read latency.
  next_index = index + 1
  if next_index < len(harness_chain):
    next_harness = harness_chain[next_index]
    Read("{{PLUGIN_ROOT}}/agents/{next_harness}.md")
    Read("{{PLUGIN_ROOT}}/harnesses/{next_harness}/skill.md")
  # When the current Task() returns, files for the next step are already available.
```

Key rules for chaining:
- Each harness receives: the original task description + accumulated results from all prior harnesses + its chain position
- Execute harnesses one at a time in order — do not parallelize a chain
- If a harness in the chain fails, apply its `failure_modes` from its `contract.yaml` before continuing or aborting the chain
- After the full chain completes, treat the final `chain_context` as the execution result for Steps 5 and 6
- Evaluation runs ONCE at the end of the full chain (Step 5), not after each individual step
- After the full chain completes, remove the chain marker: `Bash("rm -f .adaptive-harness/.chain-in-progress")`

**Dynamic chain adaptation via `next_harness_hint`:**

After each harness in the chain completes, check if its result contains a `next_harness_hint` field. This allows mid-chain adaptation:

```
result = Task(subagent_type="adaptive-harness:{harness}", prompt="...")

# Check if the harness suggests a different next step
if result contains "next_harness_hint":
  hint = result.next_harness_hint  # e.g., {"harness": "migration-safe", "reason": "discovered schema changes needed"}

  # Compare hint to the planned next harness in the chain
  planned_next = harness_chain[index + 1] if index + 1 < len(harness_chain) else None

  if hint.harness != planned_next:
    # Log the adaptation
    chain_context += f"\n\n### Chain Adaptation: {planned_next} → {hint.harness} (reason: {hint.reason})"

    # Replace remaining chain with: hint.harness + any chain steps after the replaced step
    # Example: chain was [ralplan, careful-refactor, code-review]
    #   ralplan hints "migration-safe" → new chain becomes [ralplan, migration-safe, code-review]
    harness_chain[index + 1] = hint.harness
    # Preserve the final review step if one exists
```

Rules for `next_harness_hint`:
- The hint is advisory, not mandatory — the orchestrator may ignore it if the suggested harness doesn't exist in the pool
- Only the immediate next step can be replaced; the rest of the chain is preserved
- The hint must include a `reason` field explaining why the switch is needed
- If no hint is present, continue with the planned chain as normal
- Harness agents can emit this hint by including it in their output: `## next_harness_hint\n{"harness": "...", "reason": "..."}`

If `harness_chain` has only 1 entry (or is absent), skip this step and proceed to Step 4a/4b/4c as normal.

### Step 4a: Fast-Path (skip_routing = true)

If the router returns `skip_routing: true`, execute the task directly without spawning a harness subagent. **After completing the task, write a lightweight eval record** (no evaluator agent needed):

```
Write(".adaptive-harness/sessions/{session_id}/eval-{timestamp}.json", {
  "task": "{task_description}",
  "timestamp": "{iso_timestamp}",
  "harness": "fast-path",
  "taxonomy": {"task_type": "trivial", "skip_routing": true},
  "scores": {},
  "overall_score": null,
  "quality_gate_passed": null,
  "fast_path": true
})
```

This ensures every task leaves an audit trail. Fast-path evals do NOT update harness weights or trigger evolution. Then proceed to user response.

### Step 4b: Single Harness Execution (ensemble_required = false)

1. Determine harness file paths using the resolution order below:

   ```
   plugin_root = "{{PLUGIN_ROOT}}"
   local_harnesses_dir = ".adaptive-harness/harnesses"

   def resolve_harness_dir(harness_name, experimental_path=None):
       """Resolution order (first match wins):
       1. Local stable override: .adaptive-harness/harnesses/{harness_name}/
       2. Local experimental:    .adaptive-harness/harnesses/experimental/{variant}/
       3. Global stable:         {plugin_root}/harnesses/{harness_name}/
       """
       local_stable = f"{local_harnesses_dir}/{harness_name}"
       if path_exists(local_stable):
           return local_stable, f"{plugin_root}/agents/{harness_name}.md"

       if experimental_path:
           # experimental_path is 'experimental/{variant}' (relative to local_harnesses_dir)
           local_exp = f"{local_harnesses_dir}/{experimental_path}"
           if path_exists(local_exp):
               return local_exp, f"{local_exp}/agent.md"

       return f"{plugin_root}/harnesses/{harness_name}", f"{plugin_root}/agents/{harness_name}.md"

   if router_response.get("experimental"):
       exp_path = router_response["experimental_harness_path"]  # 'experimental/{variant}'
       harness_dir, agent_path = resolve_harness_dir(selected_harness, exp_path)
   else:
       harness_dir, agent_path = resolve_harness_dir(selected_harness)
   ```

2. Read the harness files **in a single parallel tool-call batch** (issue both Read() calls in the same response turn — do NOT read one, wait, then read the other):
   - `{agent_path}` — agent persona + instructions (from `agents/` for stable, from experimental dir for experimental)
   - `{harness_dir}/skill.md` — workflow steps
   - `{harness_dir}/contract.yaml` — execution contract (from stable dir as fallback if missing in experimental)

   ```
   # PARALLEL READ — issue both in the same tool-call batch
   Read("{agent_path}")          # agent persona
   Read("{harness_dir}/skill.md")  # workflow steps
   # Both reads execute concurrently; wait for both before spawning the subagent
   ```

3. **MANDATORY: Spawn a subagent.** Do NOT read the harness instructions and follow them yourself in the main context. You MUST use the Task() tool to spawn a subagent. This is required because:
   - The SubagentStop hook fires only when a subagent completes (triggers evidence collection)
   - Evaluation in Step 5 depends on the subagent having run
   - The orchestrator orchestrates; subagents execute. Never conflate these roles.

```
Task(
  subagent_type="adaptive-harness:{selected_harness}",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  prompt="{agent.md content}\n\n## Workflow\n{skill.md content}\n\n## Task\n{task_description}\n\n## Session ID\n{session_id}"
)
```

4. Wait for subagent completion. **Then immediately proceed to Step 5 (evaluation).** Do not respond to the user first.

### Step 4c: Ensemble Execution (ensemble_required = true)

Ensemble triggers when the router classifies: `uncertainty=high` AND (`verifiability=hard` OR `blast_radius=repo-wide`).

The router returns one of two ensemble modes:

#### Ensemble Pre-Check: Git Repository Requirement

**Before starting any ensemble execution**, check if the working directory is a git repository:

```
Bash("git rev-parse --is-inside-work-tree 2>/dev/null")
```

- If **yes** (exit code 0): Use worktree isolation (`isolation: "worktree"`) for parallel execution.
- If **no** (not a git repo): **Initialize git first**, then use worktrees.
  ```
  Bash("git init && git add -A && git commit -m 'initial commit for ensemble isolation' --allow-empty")
  ```
  This is required because greenfield projects start in empty non-git directories, but `isolation: "worktree"` depends on git worktree which requires a git repository. The init + commit creates the minimal baseline needed for worktree branching.

#### Mode 1: Simple Harness Ensemble (`ensemble_harnesses` present)

For tasks that don't need a planning step — just run 2+ harnesses in parallel on the same task.

**⚠ MANDATORY: Every harness Task() call below MUST include `isolation="worktree"`.**

1. Identify 2-3 candidate harnesses from the pool (router provides them as `ensemble_harnesses: [...]`).

2. Read ALL harness file pairs in parallel, then spawn all harness subagents in **a single tool-call batch with worktree isolation**:

```
# Mark ensemble as in progress — prevents premature .eval-pending and turn-breaking hook messages
Bash("printf 'ensemble' > .adaptive-harness/.chain-in-progress")

# STEP A — PARALLEL READ: Issue ALL Read() calls in ONE tool-call batch.
# Read every harness file pair concurrently before spawning any Task().
Read("{plugin_root}/agents/{harness_1}.md")
Read("{plugin_root}/harnesses/{harness_1}/skill.md")
Read("{plugin_root}/agents/{harness_2}.md")
Read("{plugin_root}/harnesses/{harness_2}/skill.md")
# Wait for ALL reads to complete before proceeding.

# STEP B — PARALLEL SPAWN: Issue ALL Task() calls in ONE tool-call batch.
# Claude Code executes tool calls within the same batch concurrently.
# Do NOT issue them in separate response turns — that would serialize execution.
# Each harness gets its own isolated worktree copy of the repository.
# This prevents harnesses from overwriting each other's files.
Task(
  subagent_type="adaptive-harness:{harness_1}",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  isolation="worktree",
  prompt="..."
)
Task(
  subagent_type="adaptive-harness:{harness_2}",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  isolation="worktree",
  prompt="..."
)
# Both Task() calls are in the SAME batch — they run concurrently, not sequentially.
```

3. Collect all results. Each result includes the worktree path and branch where the harness wrote its code.

**Partial failure handling**: If one worktree harness fails (returns error, empty result, or missing worktree_path), do NOT spawn the synthesizer. Instead, use the successful worktree's result directly:
- If exactly one succeeded: copy its worktree changes to the main workspace via `git merge {branch}` or direct file copy. Skip synthesis.
- If both failed: proceed to Step 5 (evaluation) with a failure result. The evaluator will score it accordingly.
- If both succeeded: continue to step 4 (synthesizer).

4. Spawn the synthesizer agent with worktree paths so it can read and compare both implementations:

```
# PARALLEL READ — read ALL harness file pairs in a single tool-call batch BEFORE spawning any subagent.
# Issue both Read() calls in the same response turn so they execute concurrently.
Read("{plugin_root}/agents/synthesizer.md")
Read("{plugin_root}/harnesses/synthesizer/skill.md")

Task(
  subagent_type="adaptive-harness:synthesizer",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  prompt="{synthesizer_agent.md}\n\n## Workflow\n{synthesizer_skill.md}\n\n## Task\n{task_description}\n\n## Main Workspace\n{main_workspace_path}\n\n## Worktree A: {harness_1}\n- Path: {worktree_path_1}\n- Branch: {branch_1}\n- Summary: {result_1}\n\n## Worktree B: {harness_2}\n- Path: {worktree_path_2}\n- Branch: {branch_2}\n- Summary: {result_2}\n\nFollow the skill.md workflow: Inventory → Merge Plan → Execute → Reconcile → Verify → Report."
)

# After synthesizer completes, remove the chain marker so evaluation can proceed
Bash("rm -f .adaptive-harness/.chain-in-progress")
```

#### Mode 2: Chain Ensemble (`ensemble_chains` present)

For tasks that benefit from planning + multiple execution approaches. Runs the shared planning step ONCE in the main workspace, then fans out execution harnesses in **isolated worktrees**, then synthesizes by cherry-picking the best files from each worktree.

**⚠⚠⚠ WORKTREE ISOLATION IS MANDATORY — NOT OPTIONAL ⚠⚠⚠**

Every execution harness Task() call in ensemble mode MUST include `isolation="worktree"`. This is the single most critical parameter in the entire ensemble flow. Without it:
- Harnesses overwrite each other's files in the same directory
- Synthesizer cannot compare independent implementations
- The ensemble produces a worse result than a single harness

If you are about to write a Task() call for an ensemble execution harness and it does NOT contain `isolation="worktree"`, STOP and add it. There are ZERO exceptions to this rule.

The router provides:
- `ensemble_chains`: array of 2+ chains, e.g., `[["ralplan-consensus", "system-design"], ["ralplan-consensus", "tdd-driven"]]`
- `shared_planning_harness`: the common first harness across chains (e.g., `"ralplan-consensus"`)

**Execution flow:**

0. **Ensure git repo exists** (see Ensemble Pre-Check above). For greenfield projects, also commit any files created by the planning step before fan-out — worktrees branch from the current HEAD, so planning artifacts must be committed to be visible in worktrees.

1. **Mark chain in progress, then run shared planning harness ONCE in the main workspace** (avoids redundant planning):

```
# Mark ensemble chain as in progress — prevents premature .eval-pending and turn-breaking hook messages
Bash("printf 'ensemble' > .adaptive-harness/.chain-in-progress")

# PARALLEL READ — read planning harness files in a single tool-call batch.
Read("{plugin_root}/agents/{shared_planning_harness}.md")
Read("{plugin_root}/harnesses/{shared_planning_harness}/skill.md")
# Both reads in the SAME response turn — execute concurrently.

planning_result = Task(
  subagent_type="adaptive-harness:{shared_planning_harness}",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  prompt="{agent.md}\n\n## Workflow\n{skill.md}\n\n## Task\n{task_description}\n\n## Session ID\n{session_id}"
)

# IMPORTANT: If the planning step created any files, commit them before fan-out.
# Worktrees branch from HEAD — uncommitted files won't appear in worktrees.
Bash("git add -A && git diff --cached --quiet || git commit -m 'planning phase artifacts'")
```

2. **Fan out execution harnesses in parallel, each in its own worktree**:

```
# Extract sub-chains after the shared planning prefix.
# For each chain, skip the first element (shared planning harness) to get the
# sequence of harnesses to execute sequentially within each worktree.
# chain[1:] preserves all intermediate steps — for 2-step chains this is
# equivalent to [chain[-1]]; for 3+ step chains it avoids dropping intermediate
# harnesses (the previous `chain[-1]` pattern was broken for 3+ step chains).
sub_chains = [chain[1:] for chain in ensemble_chains]
# e.g., for [["ralplan-consensus","system-design"],["ralplan-consensus","tdd-driven"]]:
#   sub_chains = [["system-design"], ["tdd-driven"]]
# e.g., for [["ralplan-consensus","careful-refactor","code-review"],["ralplan-consensus","tdd-driven","code-review"]]:
#   sub_chains = [["careful-refactor","code-review"], ["tdd-driven","code-review"]]

# Guard: skip empty sub-chains (from 1-element input chains missing execution steps)
sub_chains = [sc for sc in sub_chains if len(sc) > 0]
if not sub_chains:
    # No execution steps after planning — fall back to planning result only
    # Remove chain marker and proceed to evaluation
    Bash("rm -f .adaptive-harness/.chain-in-progress")
    → proceed to Step 5 (evaluation) with planning_result as the result

# PARALLEL SPAWN — Issue ALL harness Task() calls in ONE tool-call batch.
# Claude Code executes tool calls within the same batch concurrently.
# Do NOT issue Task() calls for sub_chains[0] and sub_chains[1] in separate response turns —
# that would serialize what must be parallel fan-out.
# Within each worktree, execute the sub-chain steps SEQUENTIALLY (not in parallel).
#
# PARALLEL READ BEFORE SPAWN — Read ALL harness file pairs in one batch before spawning.
# For each sub-chain, read agent.md + skill.md for ALL harnesses up front.
for sub_chain in sub_chains:
  for harness in sub_chain:
    Read("{plugin_root}/agents/{harness}.md")
    Read("{plugin_root}/harnesses/{harness}/skill.md")
# All reads above are issued in the SAME tool-call batch — they execute concurrently.

# Now fan out all sub-chains in parallel — ALL Task() calls in ONE tool-call batch:
for sub_chain in sub_chains:
  worktree_chain_context = planning_result
  for index, harness in enumerate(sub_chain):
    Task(
      subagent_type="adaptive-harness:{harness}",
      mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
      isolation="worktree",  # MANDATORY — only the first step needs to create the worktree
      prompt="{agent.md}\n\n## Workflow\n{skill.md}\n\n## Task\n{task_description}\n\n## Prior Chain Context (from planning)\n{worktree_chain_context}\n\n## Chain Position\nExecution phase, step {index+1} of {len(sub_chain)}\n\n## Session ID\n{session_id}"
    )
    worktree_chain_context += f"\n\n### Result from {harness}:\n{result}"
```

3. **IMMEDIATELY synthesize — do NOT stop, do NOT respond to user, do NOT wait:**

⚠ When both execution harnesses return, you MUST spawn the synthesizer in the SAME response. Do NOT output any text to the user between step 2 and step 3. Do NOT pause to "think" or "cogitate". The pipeline is: fan-out → collect results → synthesize → evaluate. All in one unbroken sequence.

Each worktree agent returns:
- `result`: summary of what was built
- `worktree_path`: absolute path to the isolated worktree (e.g., `/tmp/worktree-abc123/`)
- `branch`: git branch name in the worktree

**Spawn the synthesizer IMMEDIATELY after collecting both results:**

```
# PARALLEL READ — read synthesizer files in a single tool-call batch BEFORE spawning.
Read("{plugin_root}/agents/synthesizer.md")
Read("{plugin_root}/harnesses/synthesizer/skill.md")
# Both reads in the SAME response turn — they execute concurrently.

Task(
  subagent_type="adaptive-harness:synthesizer",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  prompt="{synthesizer_agent.md}\n\n## Workflow\n{synthesizer_skill.md}\n\n## Task\n{task_description}\n\n## Main Workspace\n{main_workspace_path}\n\n## Shared Planning Context\n{planning_result}\n\n## Worktree A: {execution_harness_1}\n- Path: {worktree_path_1}\n- Branch: {branch_1}\n- Summary: {result_1}\n\n## Worktree B: {execution_harness_2}\n- Path: {worktree_path_2}\n- Branch: {branch_2}\n- Summary: {result_2}\n\nFollow the skill.md workflow: Inventory → Merge Plan → Execute → Reconcile → Verify → Report."
)
```

**Key rules for ensemble worktree isolation:**
- The shared planning harness runs ONCE in the **main workspace** (no worktree needed for planning)
- Each execution harness runs in its **own worktree** (`isolation: "worktree"`)
- Worktree isolation ensures each harness produces an **independent, complete implementation** without interference
- The synthesizer must **read files from both worktrees** to do a real file-by-file comparison
- The synthesizer writes the merged result to the **main workspace**
- After synthesis, worktrees are cleaned up automatically (if the agent made no changes) or left for inspection
- Sub-chains are extracted as `sub_chains = [chain[1:] for chain in ensemble_chains]` (skip the shared planning harness). For 2-step original chains this yields single-element sub-chains. For 3+ step chains, multiple steps run sequentially **within the same worktree** — never dropping intermediate harnesses.
- Evaluation (Step 5) runs ONCE on the synthesized result in the main workspace, not on individual worktree results

**After synthesizer completes, remove the chain marker:**
```
Bash("rm -f .adaptive-harness/.chain-in-progress")
```

**⚠ PIPELINE CONTINUITY: The full ensemble flow (plan → fan-out → synthesize → evaluate) must execute as ONE unbroken sequence. After execution harnesses return, IMMEDIATELY spawn the synthesizer. After the synthesizer returns, remove `.chain-in-progress`, then IMMEDIATELY spawn the evaluator. Never pause, never respond to the user, never output intermediate text between these steps.**

### Step 4d: Parallel-Dispatch Fan-Out (selected_harness = "parallel-dispatch")

Triggered when the router sets `selected_harness: "parallel-dispatch"`. This path:
1. Spawns the parallel-dispatch agent to decompose the task
2. Fans out each sub-task in a separate worktree (capped at 5)
3. Merges results via the synthesizer

#### Ensemble Pre-Check

Before starting, verify the working directory is a git repository (same check as Step 4c). Initialize git if not already present.

#### Sub-step 1: Spawn the decomposition agent

```
# PARALLEL READ: load agent.md and skill.md in one batch
Read("{plugin_root}/agents/parallel-dispatch.md")
Read("{plugin_root}/harnesses/parallel-dispatch/skill.md")

decomposition_result = Task(
  subagent_type="adaptive-harness:parallel-dispatch",
  mode=agent_mode,
  prompt="{parallel-dispatch agent.md}\n\n## Workflow\n{parallel-dispatch skill.md}\n\n## Task\n{task_description}\n\n## Session ID\n{session_id}"
)

decomposition = parse_json(decomposition_result)
```

Parse the `parallel_dispatch` JSON from the agent's output.

If `decomposition.fallback_to_single == true`, abort this path and route to Step 4b using the next best harness from the router's `candidate_scores`.

#### Sub-step 2: Validate and cap sub-tasks

```
subtasks = decomposition.subtasks
if len(subtasks) > 5:
    # Hard cap: take the 5 with highest estimated_complexity (most valuable to parallelize)
    subtasks = sort_by_complexity_desc(subtasks)[:5]
if len(subtasks) < 2:
    # Cannot parallelize — fall back to single harness
    → Step 4b using first subtask's harness
```

#### Sub-step 3: Prefetch all sub-task harness files in parallel, then fan out

```
# PARALLEL READ: issue ALL Read() calls for ALL sub-task harnesses in a SINGLE
# tool-call batch before spawning any Task().
for subtask in subtasks:
  Read("{plugin_root}/agents/{subtask.harness}.md")          # ← ALL in one batch
  Read("{plugin_root}/harnesses/{subtask.harness}/skill.md") # ← ALL in one batch

# PARALLEL DISPATCH: Issue ALL Task() calls in a SINGLE tool-call batch.
# Each sub-task runs in its own worktree.
subtask_results = []
for subtask in subtasks:
  result = Task(
    subagent_type="adaptive-harness:{subtask.harness}",
    mode=agent_mode,
    isolation="worktree",  # MANDATORY — each sub-task gets its own worktree
    prompt="{subtask.harness agent.md}\n\n## Workflow\n{subtask.harness skill.md}\n\n## Task\n{subtask.description}\n\n## Scope\n{subtask.scope_files}\n\n## Interface Contract (inputs)\n{subtask.inputs}\n\n## Interface Contract (outputs)\n{subtask.outputs}\n\n## Original Task Context\n{task_description}\n\n## Session ID\n{session_id}"
  )
  subtask_results.append({subtask.id: result})
```

#### Sub-step 4: Synthesize

After all sub-task worktrees complete, read synthesizer files and spawn the synthesizer with the integration plan:

```
Read("{plugin_root}/agents/synthesizer.md")
Read("{plugin_root}/harnesses/synthesizer/skill.md")

Task(
  subagent_type="adaptive-harness:synthesizer",
  mode=agent_mode,
  prompt="{synthesizer agent.md}\n\n## Workflow\n{synthesizer skill.md}\n\n## Task\n{task_description}\n\n## Main Workspace\n{main_workspace_path}\n\n## Integration Plan\n{decomposition.integration}\n\n## Sub-Task Results\n{subtask_results_with_worktree_paths}\n\nFollow the skill.md workflow: Inventory → Merge Plan → Execute → Reconcile → Verify → Report."
)
```

Then proceed immediately to Step 5 (evaluation).

---

### Step 5: Collect Evidence and Evaluate (MANDATORY — do not skip)

After subagent completion (detected when the subagent's Task() call returns):

**⚠ IMPORTANT**: Execute this step IMMEDIATELY when the harness subagent Task() returns. Do NOT respond to the user first. Do NOT follow other plugin hooks first. The evaluation is a mandatory part of the pipeline, not an optional follow-up.

1. Read ALL evidence files from `.adaptive-harness/sessions/{session_id}/evidence/` in a **single parallel tool-call batch** — issue all Read() calls in the same response turn so they execute concurrently. These files are populated by the `collect-evidence.sh` PostToolUse hook during subagent execution.

   ```
   # PARALLEL READ — list evidence dir, then read all files in one batch
   evidence_files = Glob(".adaptive-harness/sessions/{session_id}/evidence/*")
   # Issue all Read() calls in ONE tool-call batch:
   for f in evidence_files:
       Read(f)
   # All reads execute concurrently; wait for all before spawning the evaluator.
   ```

2. Use the `evaluator_model` already determined in Step 3 (no re-computation needed):
   - **Sonnet**: pre-selected if task_type in [bugfix, feature] AND uncertainty in [low, medium] AND blast_radius = local
   - **Opus**: pre-selected for everything else

3. Spawn the evaluator agent with the pre-determined model:

```
Task(
  subagent_type="adaptive-harness:evaluator",
  mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
  model=evaluator_model,  # "sonnet" or "opus" based on routing
  prompt="Score this task result.\n\nTask: {task_description}\nTask type: {taxonomy.task_type}\nSelected harness: {selected_harness}\nResult summary: {result_summary}\n\nRead .adaptive-harness/sessions/{session_id}/evidence/ for collected evidence."
)
```

### Step 6: Record Evaluation and Update Weights (MANDATORY — do not skip)

On evaluator response:

**Execute immediately** after the evaluator returns. Write the eval JSON and update weights before responding to the user.

1. Write evaluation result to `.adaptive-harness/sessions/{session_id}/eval-{timestamp}.json`:

```json
{
  "task": "{task_description}",
  "timestamp": "{iso_timestamp}",
  "harness": "{selected_harness}",
  "taxonomy": {taxonomy_object},
  "ensemble": ensemble_required,
  "scores": {dimension_scores},
  "overall_score": 0.82,
  "quality_gate_passed": true,
  "improvement_suggestions": ["..."]
}
```

2. Update in-memory weight for this harness in the current session context. Track: `{harness_name}: {current_weight + delta}` where delta = `(score - 0.5) * 0.1` (positive for good results, negative for poor results).

3. The `session-end.sh` Stop hook will flush these in-memory weight updates to `.adaptive-harness/sessions/{session_id}/weights.json` and merge them into `.adaptive-harness/harness-pool.json` atomically.

4. Clear the evaluation-pending flag: delete `.adaptive-harness/sessions/{session_id}/.eval-pending` via Bash to signal that evaluation is complete.

5. **Copy eval to evaluation-logs for evolution tracking (Fix 2):**
   ```
   mkdir -p .adaptive-harness/evaluation-logs/{selected_harness}/
   cp .adaptive-harness/sessions/{session_id}/eval-*.json .adaptive-harness/evaluation-logs/{selected_harness}/
   ```
   This accumulates evaluation history per harness, enabling the evolution-manager to analyze trends.

6. **Auto-trigger evolution manager every evaluation (Fix 3):**
   After copying the eval, count files in `.adaptive-harness/evaluation-logs/{selected_harness}/`. Trigger on every evaluation (i.e., `count >= 1`), spawn the evolution manager:
   ```
   Task(
     subagent_type="adaptive-harness:evolution-manager",
     mode=agent_mode,  # "dontAsk" if --skip-interview, else "default"
     prompt="Analyze evaluation history and propose harness improvements.\n\nTrigger: {selected_harness} has reached {count} evaluations.\nPlugin root: {{PLUGIN_ROOT}}\n\nRead .adaptive-harness/evaluation-logs/{selected_harness}/ for evaluation history.\nRead {{PLUGIN_ROOT}}/agents/{selected_harness}.md and {{PLUGIN_ROOT}}/harnesses/{selected_harness}/skill.md for current harness content.\nRead .adaptive-harness/harness-pool.json for pool state.\n\nGenerate evolution proposals and write them to .adaptive-harness/evolution-proposals/."
   )
   ```
   The evolution-manager writes proposals to `.adaptive-harness/evolution-proposals/`. These proposals are applied automatically on the next session start by `session-start.sh` (which reads pending proposals, creates experimental harness copies, and registers them in the pool).

### Step 7: Handle Failure Modes

If a subagent fails or quality gate does not pass:

1. Read `{{PLUGIN_ROOT}}/harnesses/{selected_harness}/contract.yaml` to check `failure_modes` section.
2. Execute the specified failure action:
   - `fallback: {other_harness}` — re-route to the fallback harness
   - `action: escalate_to_user` — surface the issue to the user for guidance
   - `action: rollback` — execute the rollback command specified in the contract

---

## Parallelism Rules

These rules govern when parallel dispatch is required, allowed, or forbidden in the orchestration pipeline. The LLM orchestrator defaults to sequential execution; explicit annotations override that default.

### When parallel dispatch is REQUIRED

| Situation | Rule |
|-----------|------|
| Reading `agent.md` + `skill.md` for any single harness | Always issue both Read() calls in the same tool-call batch |
| Reading ALL harness file pairs before an ensemble spawn | Issue every Read() call in one batch before any Task() call |
| Spawning 2+ harnesses in Mode 1 Simple Ensemble | Issue ALL Task() calls in ONE tool-call batch — never across response turns |
| Spawning sub-chains in Mode 2 Chain Ensemble fan-out | Issue ALL top-level Task() calls in ONE tool-call batch |
| Reading evidence files before spawning the evaluator | Issue all Read() calls in one batch |
| Prefetching files for chain step N+1 | Issue both Read() calls immediately after spawning step N's Task(), in the same response turn |

### When sequential execution is REQUIRED

| Situation | Rule |
|-----------|------|
| Steps within a single harness chain (Step 3.5) | Each Task() depends on the prior result — strictly sequential |
| Steps within a single worktree sub-chain (Mode 2) | Execute sequentially inside the worktree — do NOT parallelize within a sub-chain |
| Planning harness → fan-out execution harnesses (Mode 2) | Planning must complete and artifacts must be committed before fan-out begins |
| Synthesis → evaluation | Synthesizer must complete before the evaluator runs |
| Evaluation → weight update | Evaluator must complete before weights are written |

### General principles

- **Same response turn = concurrent**: Claude Code executes all tool calls issued within a single response turn concurrently. Use this to batch independent reads and spawns.
- **Separate response turns = sequential**: Issuing a tool call in turn N+1 means waiting for turn N to complete. Avoid this for independent operations.
- **Reads are always safe to parallelize**: File reads have no side effects and no ordering dependency. Always batch them.
- **Task() calls for the same logical step are safe to parallelize**: Ensemble harnesses and sub-chain fan-outs are explicitly independent — batch them.
- **Task() calls across sequential pipeline stages are NOT parallelizable**: Router → harness → evaluator is an ordered dependency chain.

---

## Parallelism Anti-Patterns

The following patterns MUST be avoided. They silently serialize what should be concurrent execution, adding unnecessary latency without producing any correctness benefit.

### Anti-pattern 1: Sequential fan-out in ensemble mode

```
# WRONG — two separate response turns, serialized execution
Task(subagent_type="adaptive-harness:{harness_1}", isolation="worktree", ...)
# ... wait for response turn boundary ...
Task(subagent_type="adaptive-harness:{harness_2}", isolation="worktree", ...)

# CORRECT — single tool-call batch, concurrent execution
Task(subagent_type="adaptive-harness:{harness_1}", isolation="worktree", ...)
Task(subagent_type="adaptive-harness:{harness_2}", isolation="worktree", ...)
# Both in the SAME response turn
```

### Anti-pattern 2: Sequential reads before spawning

```
# WRONG — reads issued one at a time across multiple response turns
Read("{plugin_root}/agents/{harness}.md")
# wait...
Read("{plugin_root}/harnesses/{harness}/skill.md")
# wait...

# CORRECT — both reads in the same tool-call batch
Read("{plugin_root}/agents/{harness}.md")
Read("{plugin_root}/harnesses/{harness}/skill.md")
# Same response turn — execute concurrently
```

### Anti-pattern 3: Forgetting to prefetch for the next chain step

```
# WRONG — orchestrator idles while waiting for reads after a Task() returns
result = Task(subagent_type="adaptive-harness:{harness_N}", ...)
# harness_N completes, then orchestrator reads files for harness_N+1 — wasted time

# CORRECT — prefetch files for step N+1 in the same turn as spawning step N
Task(subagent_type="adaptive-harness:{harness_N}", ...)
Read("{plugin_root}/agents/{harness_N+1}.md")      # prefetch
Read("{plugin_root}/harnesses/{harness_N+1}/skill.md")  # prefetch
# When harness_N completes, files for step N+1 are already in context
```

### Anti-pattern 4: Sequential evidence reads before evaluation

```
# WRONG — reading evidence files one at a time
for f in evidence_files:
    Read(f)
    # response turn boundary between each — fully serialized

# CORRECT — all evidence reads in one batch
# Issue ALL Read() calls in the same response turn
Read(evidence_files[0])
Read(evidence_files[1])
Read(evidence_files[2])
# ...all in the same tool-call batch
```

### Anti-pattern 5: Parallelizing steps that have ordering dependencies

```
# WRONG — attempting to parallelize sequential chain steps
Task(subagent_type="adaptive-harness:ralplan-consensus", ...)
Task(subagent_type="adaptive-harness:careful-refactor", ...)
# careful-refactor depends on ralplan-consensus output — this produces garbage

# CORRECT — sequential chain execution is required when steps have data dependencies
planning_result = Task(subagent_type="adaptive-harness:ralplan-consensus", ...)
# wait for planning to complete, then pass its result to the next step
Task(subagent_type="adaptive-harness:careful-refactor", prompt="...{planning_result}...")
```

---

## Reading Harness Files

When you need to inspect a harness before spawning a subagent, use the Read tool:

```
Read("{{PLUGIN_ROOT}}/agents/tdd-driven.md")
Read("{{PLUGIN_ROOT}}/harnesses/tdd-driven/skill.md")
Read("{{PLUGIN_ROOT}}/harnesses/tdd-driven/contract.yaml")
```

Pass the content of the agent file and `skill.md` concatenated as the subagent's system prompt. The `contract.yaml` content informs your orchestration decisions (stopping criteria, cost budget, failure modes) but is not passed verbatim to the subagent.

---

## Session ID

Use the environment variable `CLAUDE_SESSION_ID` if available. Otherwise, read `.adaptive-harness/.current-session-id` for the session-stable ID generated by `session-start.sh`. All per-session state writes use this ID as the directory name under `.adaptive-harness/sessions/`.

---

## Pre-Response Evaluation Gate

**Before generating ANY response to the user after receiving a task, verify:**

1. Did the router run? → If yes, check which path was taken:
   - `skip_routing: true` → verify lightweight eval JSON was written
   - Harness subagent ran → verify Steps 5-6 completed (eval JSON exists in `.adaptive-harness/sessions/{session_id}/`)
   - External skill handled the task → verify lightweight eval JSON was written with `harness: "external:{skill_name}"`
2. If NO eval JSON exists for this task, **STOP and run evaluation now** before responding.

This gate is the last line of defense against skipped evaluation. The pipeline is not complete until an eval record exists.

---

## Interaction with External Skills (OMC, superpowers)

When an OMC skill (`sciomc`, `ralph`, `autopilot`, `ultrawork`, etc.) or superpowers skill activates for the current task instead of the adaptive-harness pipeline, evaluation STILL applies:

1. Let the external skill complete its work
2. After it completes, write a lightweight eval JSON:
   ```
   {
     "task": "{task_description}",
     "timestamp": "{iso_timestamp}",
     "harness": "external:{skill_name}",
     "taxonomy": {},
     "scores": {},
     "overall_score": null,
     "quality_gate_passed": null,
     "external_skill": true
   }
   ```
3. Do NOT update harness weights (external results don't affect the pool)

This ensures observability — the evolution manager can detect when tasks are being handled outside the pipeline and whether those tasks would benefit from a harness.

---

## Key Design Constraints

- **You are the orchestrator** — this skill runs in the main conversation context. Do not spawn an "orchestrator" subagent.
- **NEVER bypass the router** — Every task goes to the router first. No exceptions for meta-tasks, simple tasks, or tasks that modify the pipeline itself. See "NEVER-SKIP Rules" above.
- **Never execute harness work in the main context** — When the router selects a harness (`skip_routing=false`), you MUST spawn a Task() subagent. Do not read the harness `agent.md`/`skill.md` and follow those instructions yourself. The main context orchestrates; subagents execute. This separation is required for evaluation to work.
- **Subagents cannot spawn sub-subagents** — all fan-out (router, harness execution, evaluator, synthesizer) happens from the main context.
- **Evidence collection is automatic** — the `collect-evidence.sh` hook captures Bash tool output from harness subagents. You read it after subagent completion, you do not collect it manually.
- **Weights are in-memory during session** — maintain a simple dict of `{harness_name: adjusted_weight}` updates. Flush at session end via the Stop hook.
- **Harness content changes apply next session** — if the evolution-manager proposes changes to agent or workflow files, write them to the experimental pool. They load on next SessionStart.

---

## Quick Reference: Harness Pool

Default stable pool (canonical trigger conditions in `agents/router.md`):
- `tdd-driven` — TDD workflow (bugfix, feature with clear tests)
- `systematic-debugging` — Root cause analysis (incidents, obscure bugs)
- `rapid-prototype` — Fast MVP (low-uncertainty features, time-sensitive)
- `research-iteration` — Experimental research (high uncertainty, benchmarks)
- `careful-refactor` — Safe refactoring (cross-module/repo-wide blast radius)
- `code-review` — Multi-perspective review (post-execution or explicit review tasks)
- `migration-safe` — Migration/upgrade (repo-wide blast, rollback required)
- `ralplan-consensus` — Upfront planning with self-review (first step in chains for medium/high uncertainty)
- `ralph-loop` — Persistent execution loop (iterates until acceptance criteria pass, max 10 iterations)
- `system-design` — Multi-component system architecture + implementation (greenfield projects, high uncertainty, repo-wide blast)
- `parallel-dispatch` — Task decomposition + parallel fan-out (feature/refactor with cross-module or repo-wide blast, low/medium uncertainty, decomposable=true). Decomposes task into 2-5 independent sub-tasks, fans each out in a separate worktree, then synthesizes. Distinct from ensemble: runs *different* sub-tasks (potentially same harness) vs. ensemble which runs the *same* task through *different* harnesses.
- `plan-review` — Review plans, designs, and proposals (task_type=review)
- `pre-landing-review` — Pre-merge code and design review before landing (task_type=review)
- `engineering-retro` — Engineering retrospective and process improvement (task_type=ops primary, review secondary)
- `qa-testing` — QA, acceptance testing, and quality validation (task_type=ops)
- `ship-workflow` — Release workflow, versioning, and shipping automation (task_type=release)

All tasks are evaluated using 6 fixed dimensions: correctness, completeness, quality, robustness, clarity, verifiability.