---
name: do-in-parallel
description: Run independent tasks concurrently across multiple files or targets using parallel sub-agents, with per-task model selection and LLM-as-a-judge verification. Use when tasks do not depend on each other and can run side by side.
---

# do-in-parallel

<task>
Launch multiple sub-agents in parallel to execute tasks across different files or targets. Analyze the task to select the right-sized model tier per target, perform requirement grouping analysis (repeatable, shared, or independent), generate quality-focused prompts with Zero-shot Chain-of-Thought reasoning and mandatory self-critique, then dispatch meta-judges based on grouping (one per group or per independent task, all in parallel), followed by implementors for each task in parallel, with LLM-as-a-judge verification using grouping-appropriate evaluation specs after each completes.
</task>

<context>
This command implements the **Supervisor/Orchestrator pattern** with parallel dispatch, **requirement grouping**, and **meta-judge → LLM-as-a-judge verification**. The primary benefit is **parallel execution** - multiple independent tasks run concurrently rather than sequentially, dramatically reducing total execution time for batch operations. Requirement grouping analysis reduces total agents by sharing meta-judges and judges across related tasks: repeatable groups (same task across targets) share one meta-judge spec, shared groups (interdependent tasks) use one combined judge.


Key benefits:
- **Parallel execution** - Multiple tasks run simultaneously
- **Requirement grouping** - Reduces meta-judges and judges by identifying repeatable and shared task patterns
- **Right-sized model** - Chosen per target by the [Model Selection Policy](#model-selection-policy): `sonnet`/`haiku` by default, `opus` only when earned
- **Fresh context** - Each sub-agent works with clean context window
- **Task-specific evaluation** - Each meta-judge produces tailored rubrics and checklists for its specific task or group
- **External verification** - Judge applies target-specific meta-judge specification mechanically — catches blind spots self-critique misses
- **Feedback loop** - Retry with specific issues identified by judge
- **Quality gate** - Work doesn't ship until it meets threshold

**Common use cases:**
- Apply the same refactoring across multiple files
- Run code analysis on several modules simultaneously
- Generate documentation for multiple components
- Execute independent transformations in parallel
</context>

## Arguments

| Argument | Format | Default | Description |
|----------|--------|---------|-------------|
| `task` | Free-form text | **Required** | Task description to execute across targets |
| `--files` | `"file1,file2,..."` | None | Comma-separated list of file paths to target |
| `--targets` | `"target1,target2,..."` | None | Comma-separated list of named targets |
| `--model` | `haiku\|sonnet\|opus` | *auto-selected per task* | Explicit user override for **all** sub-agents across **every** task: implementation, meta-judge, and judge. When omitted, you MUST select a tier per task per the [Model Selection Policy](#model-selection-policy) — there is no fixed fallback tier, and the Phase 3 tier-assessment steps do not run. When provided, the user's choice wins over the policy for every sub-agent — see the [Escalation Rule](#escalation-rule) for how escalation interacts with an explicit override. |
| `--output` | Path | None | Output directory path for results |
| `--strict` | `--strict` | `false` | Disable the [Iteration Discretion Rule](#55-iteration-discretion-rule) - a target passes ONLY when `score >= 4.0`, otherwise retry until max retries is reached. |

Example: `/do-in-parallel Refactor error handling --files "src/a.ts,src/b.ts" --strict`

**CRITICAL:** You are the orchestrator only - you MUST NOT perform the task yourself. IF you read, write or run bash tools you failed task imidiatly. It is single most critical criteria for you. If you used anyting except sub-agents you will be killed immediatly!!!! Your role is to:

1. Analyze the task, perform requirement grouping analysis, and select the model tier per task per the [Model Selection Policy](#model-selection-policy)
2. Dispatch meta-judges in parallel based on grouping 
3. After each meta-judge completes, dispatch the implementation sub-agent(s) for that group's targets with structured prompts
4. After implementors complete, dispatch judges based on grouping 
5. Parse verdict and iterate if needed (max 3 retries per target; for shared groups, retry only failing tasks)
6. Collect results and report final summary

## RED FLAGS - Never Do These

**NEVER:**

- Read implementation files to understand code details (let sub-agents do this)
- Write code or make changes to source files directly
- Skip judge verification to "save time"
- Read judge reports in full (only parse structured headers)
- Proceed after max retries without user decision
- Wait for one agent to complete before starting another
- Re-run meta-judge on retries
- Wait to launch implementors until ALL meta-judges have completed
- Launch separate meta-judges for tasks that belong to the same repeatable or shared group
- Re-launch ALL implementation agents in a shared group when only some failed

**ALWAYS:**

- Use Task tool to dispatch sub-agents for ALL implementation work
- Perform requirement grouping analysis BEFORE dispatching any meta-judges
- Dispatch meta-judges based on grouping -- all in parallel in a SINGLE response
- Do not wait for ALL meta-judges to complete before dispatching implementors, launch them immediately after each meta-judge completes
- Launch each implementor for a task immediately after its meta-judge completes. If all meta-judges are completed, launch all implementation agents in SINGLE response
- Pass each target's specific meta-judge evaluation specification to its judge agent 
- For shared groups, dispatch ONE judge that reviews ALL related changes together
- Include `CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}` in prompts to meta-judge and judge agents
- Use Task tool to dispatch independent judges for verification
- Wait for each implementation to complete before dispatching its judge
- Parse only VERDICT/SCORE/ISSUES from judge output
- Iterate with feedback if verification fails (max 3 retries per target)
- Apply the [Iteration Discretion Rule](#55-iteration-discretion-rule) to every target verdict, unless `--strict` was provided
- For shared group retries, only re-launch the specific failing implementation agent(s), not the entire group
- Reuse same meta-judge specification for all retries (never re-run meta-judge)

## Model Selection Policy

Picking the model is the **single highest-leverage decision** you make — more than any prompt wording, it decides whether a target comes back correct and how long the batch takes. You MUST NOT treat it as a formality: name the tier and give a one-line justification before dispatching **each** target. Reaching for the strongest model because you did not want to think is a failure, not caution.

**Tier default:** `sonnet` and `haiku` are the default. `opus` is reserved and opt-in — it MUST be *earned* by a trigger in the table below, never picked because you are unsure.

**Per task, not per run:** a tier is chosen **independently for every task**, from that task's own scope, complexity and risk — the batch is no longer forced into one "same configuration for all parallel agents." Independent tasks are each tiered on their own merits. A repeatable group's shared meta-judge produces one reusable spec, but that does NOT force one tier: each task in the group keeps its own implementation and judge tier from the Selection Rules below, so a critical-domain target inside an otherwise-mechanical group can still land on `opus` while its siblings stay cheaper. A shared group's single judge reviews every task in the group together, so it runs at the HIGHEST current implementation tier among them (see [Role Pairing](#role-pairing)). A tier reached by one task (including one reached by escalation) MUST NOT be carried into sibling tasks or the next batch.

### Selection Rules

| Task shape | Tier | Examples |
|---|---|---|
| Single documentation/text file correction — no code, no cross-file reasoning | `haiku` | Fix a typo, update a link, correct a stale command in a README |
| Small, few-line (~10 lines or fewer), mechanical code change confined to one file | `haiku` | Bump a constant, add a guard clause, rename a local, edit a config value |
| Code writing — new functions, components or tests, single-module changes, established patterns | `sonnet` | Add an endpoint, write a service method plus tests, refactor one module |
| **Multi-file refactoring** (~3+ files, or any file count when a shared contract changes) OR **critical** (auth, payments/billing, data integrity, irreversible migration, public API break) OR **complex logic** (concurrency, non-trivial algorithms, architectural decisions) | `opus` | Cross-cutting refactor, auth or payment logic, schema migration, novel algorithm design |

**Precedence (MANDATORY):** evaluate EVERY row, not just the first that matches. When more than one row matches, the **HIGHEST matching tier wins** — criticality and complexity always override size. A four-line null check inside a security-critical auth handler matches both the `haiku` row and the `opus` row, and is therefore `opus`. The **critical** list is exhaustive, not illustrative: shipping to production, touching real users, or adding to a public API are NOT triggers, so a new endpoint with validation in one service file stays `sonnet`. **Mechanical-breadth carve-out:** breadth alone is not complexity. For a purely mechanical change — one identical, rule-driven edit repeated across targets, with no logic and no contract change — only the **multi-file trigger** does NOT apply; the **critical** and **complex logic** triggers still do. You MUST tier it on the content of a **single occurrence**, as if the task touched one file; mechanically renaming a symbol across 40 files is therefore `haiku`, but the same rename confined to `src/auth/` is `opus` — the critical trigger fires on that single occurrence regardless of breadth. This carve-out does NOT cover a shared-contract change (already an `opus` trigger above), so extracting a shared interface across files remains `opus`.

**Tie-breaker:** ONLY when no row matches cleanly — the task sits genuinely between two tiers — pick the **cheaper** tier. You MUST NOT bias up to `opus` to hedge; the [Escalation Rule](#escalation-rule) makes a cheap first guess recoverable, and one recovered task costs far less than over-provisioning every task.

### Role Pairing

Any model-assigned pipeline has up to three roles — **producer** (does the work), **criteria-setter** (defines what "correct" means), **evaluator** (checks the work against those criteria); in this skill they instantiate **per parallel task** as implementation / meta-judge / judge — a repeatable group shares one meta-judge across its tasks, and a shared group additionally shares one judge across its tasks. **Default: the SAME tier for all three roles of that task.**

**Only for a non-obvious task** you MAY raise **the criteria-setter alone** by one tier, so the criteria are sharper than the work being evaluated. *Non-obvious* is testable: the tier was decided by the **Tie-breaker** (no Selection Rules row matched cleanly), OR the task states no checkable acceptance condition.

| Pattern | Criteria-setter (meta-judge) | Producer + evaluator (implementation + judge) | Use when |
|---|---|---|---|
| Sharpened-haiku | `sonnet` | `haiku` | The work is trivial, but what counts as "correct" is not obvious |
| Sharpened-sonnet | `opus` | `sonnet` | Code work with ambiguous or high-consequence acceptance criteria that does not itself hit an `opus` trigger |

Producer and evaluator MUST always share a tier — for a repeatable or shared group's judge that serves more than one task, "share a tier" means the HIGHEST current implementation tier among the tasks it serves, so it is never asked to judge work above its own tier (see [Model Escalation on Retry](#531-model-escalation-on-retry)). You MUST NOT raise the evaluator alone, and MUST NOT set the criteria-setter below the producer tier. **An explicit `--model` override supersedes this whole section:** when the user passed `--model`, every role for every task runs at that tier, and Role Pairing MUST NOT raise the meta-judge above it.

### Escalation Rule

Bump **BOTH producer and evaluator** (the failing task's implementation and judge) one tier for the next attempt when either trigger fires:

1. **Low first-attempt quality** — a low score, or issues showing the model misunderstood the task rather than merely missing details.
2. **The user complains** that quality is too low or the results are wrong — at any point, including after a reported PASS.

Ladder: `haiku` → `sonnet` → `opus`. `opus` is the **ceiling** — there is no further tier. If `opus`-tier work still fails, escalate to the **user**, never loop.

- **Sole exception — hold the tier (the ONLY statement of this rule, trigger (1) only):** when trigger (1) fires but the judge's issues are a specific, fixable defect rather than a capability gap (narrow, precisely specified problems the model clearly understood), you MAY hold the tier and retry at the SAME tier with the judge's exact feedback instead of bumping. This is the ONLY circumstance in which the bump under trigger (1) is not mandatory; in every other case trigger (1) bumps. Trigger (2) (a user complaint) has NO such exception — it always bumps immediately, per the carve-out below.
- **Explicit `--model` carve-out (the ONLY statement of this rule):** an explicit `--model` is a user override, so trigger (1) MUST NOT silently overrule it — continue iterate with override model till you reach max retry limit. If target still not meet at the end, highlight the found issues and propose to the bump to user. Trigger (2) IS that approval, so it bumps immediately.
- **Scoped to the failing task only.** Escalation re-tiers the retries of THAT task's implementation and judge. It does NOT re-tier the batch: sibling tasks running concurrently, and every task in a later batch, are assessed on their own merits per the [Selection Rules](#selection-rules), starting again from the `sonnet`/`haiku` default.
- Escalation moves implementation and judge only. The task's meta-judge (or the group's, for repeatable/shared groups) is NOT re-run and NOT re-tiered — its specification is reused across the task's retries, and changing the criteria mid-task invalidates the comparison across attempts.
- Escalation is a complement to, never a substitute for, a genuine root-cause fix. You MUST still pass the judge's specific feedback into the retry; re-dispatching the same prompt at a higher tier and hoping is prohibited.
- Escalation is orthogonal to the score thresholds, the [Iteration Discretion Rule](#55-iteration-discretion-rule) and the per-target max-3-retries budget — it changes *which model* runs the next attempt, never *whether* an attempt is warranted.
- **Re-entry after a reported PASS (the ONLY statement of this rule):** a reported PASS does NOT close the work. If the user later says a target's result is wrong or its quality too low, re-enter that target's retry path under trigger (2), and that target's retry budget **resets** — the complaint opens a fresh cycle of up to 3 retries even if the earlier cycle was exhausted.

### Cross-Provider Equivalence

When this skill runs outside the Anthropic model context, map the tier to the nearest model of the same class:

| Tier | Role | Comparable models from other providers |
|---|---|---|
| `haiku` | Fast and cheap; mechanical work | `gemini-flash-lite`, `gemma` class, `gpt-oss` class, small open-weight models |
| `sonnet` | Balanced workhorse; most code writing | `gemini-pro` class and full `gemini-flash` (**not** the `-lite` variant, which is `haiku`-tier), `GPT-5-mini` class, large `Qwen` / `DeepSeek` class |
| `opus` | Frontier reasoning; critical or complex work | whatever the provider sells as its extended / deliberate-reasoning tier — currently `GPT-5.5`, deep-think modes, `Kimi K3` class, any model whose advantage is longer deliberation rather than throughput |

The mapping is by **capability tier, not by name** — exact names drift as vendors ship new models. Every rule above is expressed in tiers, so on another provider: map tier → your model of that class, then apply the selection, pairing and escalation rules unchanged.

## Process

### Phase 1: Parse Input and Identify Targets

Extract targets from the command arguments:

```
Input patterns:
1. --files "src/a.ts,src/b.ts,src/c.ts"    --> File-based targets
2. --targets "UserService,OrderService"    --> Named targets
3. Infer from task description             --> Parse file paths from task
```

**Parsing rules:**
- If `--files` provided: Split by comma, validate each path exists
- If `--targets` provided: Split by comma, use as-is
- If neither: Attempt to extract file paths or target names from task description
- `STRICT_MODE = --strict present || false` - disables the [Iteration Discretion Rule](#55-iteration-discretion-rule); a target then passes ONLY when `score >= 4.0`, otherwise it is retried until max retries
- Strip ALL flags from the task text before building sub-agent prompts — **never** pass them into a sub-agent prompt

Example: `/do-in-parallel Simplify error handling --files "src/a.ts,src/b.ts" --strict`

### Phase 2: Task Analysis with Zero-shot CoT

Before dispatching, analyze the task systematically:

```
Let me analyze this parallel task step by step to determine the optimal configuration:

1. **Task Type Identification**
   "What type of work is being requested across all targets?"
   - Code transformation / refactoring
   - Code analysis / review
   - Documentation generation
   - Test generation
   - Data transformation
   - Simple lookup / extraction

2. **Per-Target Complexity Assessment**
   "How complex is the work for EACH individual target?"
   - High: Requires deep understanding, architecture decisions, novel solutions
   - Medium: Standard patterns, moderate reasoning, clear approach
   - Low: Simple transformations, mechanical changes, well-defined rules

3. **Per-Target Output Size**
   "How extensive is each target's expected output?"
   - Large: Multi-section documents, comprehensive analysis
   - Medium: Focused deliverable, single component
   - Small: Brief result, minor change

4. **Independence Check**
   "Are the targets truly independent?"
   - Yes: No shared state, no cross-dependencies, order doesn't matter
   - Partial: Some shared context needed, but can run in parallel
   - No: Dependencies exist --> Use sequential execution instead
```

#### Independence Validation (REQUIRED before parallel dispatch)

Verify tasks are truly independent before proceeding:

| Check | Question | If NO |
|-------|----------|-------|
| File Independence | Do targets share files? | Cannot parallelize - files conflict |
| State Independence | Do tasks modify shared state? | Cannot parallelize - race conditions |
| Order Independence | Does execution order matter? | Cannot parallelize - sequencing required |
| Output Independence | Does any target read another's output? | Cannot parallelize - data dependency |

**Independence Checklist:**
- [ ] No target reads output from another target
- [ ] No target modifies files another target reads
- [ ] Order of completion doesn't matter
- [ ] No shared mutable state
- [ ] No database transactions spanning targets

If ANY check fails: STOP and inform user why parallelization is unsafe. Recommend `/launch-sub-agent` for sequential execution.

#### Requirement Grouping Analysis (REQUIRED before Meta-Judge dispatch)

After identifying individual tasks and validating inde