---
name: orchestration
description: Delegation and sub-agent orchestration patterns for async jobs, fan-out, fan-in, retries, redirects, and failure disposition.
---

# Orchestration Skill

Use this skill when deciding whether to delegate, how to split work, and how to manage delegated jobs.

## When to delegate vs do it directly

Delegate when the task is likely to take many tool rounds, needs deep analysis, or benefits from running in parallel.

Delegate when work includes:
- Multi-file investigation with synthesis
- Long-running file/code changes
- Independent subproblems that can run in parallel
- Validation-heavy work with retries

Do it directly when work is quick:
- Single short answer from current context
- One or two simple tool calls
- Tiny edits with immediate response

If you do 2+ exploratory tool calls and still don't have a clear execution path, delegate instead of continuing inline.

## Core orchestration tools

- `delegate_task`: Start async delegated work
- `list_jobs`: Check delegated job status
- `cancel_job`: Stop running delegated work
- `retry_job`: Re-run failed delegated work
- `redirect_job`: Course-correct running/failed delegated work with new instructions

## Patterns

### 1) Single delegated task

Use when there is one clear unit of work.

Include:
- `task` with concrete outcome
- `deliverables` with explicit outputs
- `constraints` for guardrails
- `validation_cmds` when correctness is testable

### 2) Sequential pipeline (`depends_on`)

Use for ordered steps where B must wait for A.

- Create A
- Create B with `depends_on: [A_id]`
- Add more steps similarly

Set `on_dependency_failure` on each downstream job to control what happens when an upstream step fails:
- `"abort"` — default, fail the downstream job immediately
- `"skip"` — proceed anyway, note the gap in the job's context
- `"retry_once"` — walk the model/subagent fallback chain first, then abort if exhausted

Use `"skip"` when the downstream job can produce a useful result even without that input.
Use `"retry_once"` when the failure is likely transient (network, rate limit, flaky tool).

### 3) Parallel fan-out + fan-in synthesis (`children`)

Use when sub-tasks can run independently but the user should receive one combined result.

- Pass `children=[{task: ...}, ...]` to `delegate_task`
- The parent `task` becomes the synthesis step
- Parent runs only after all children complete
- User receives one consolidated completion notification

Set `on_child_failure` on the parent to control what happens when a child fails:
- `"abort"` — default, fail the entire graph immediately
- `"skip"` — synthesize with whatever children succeeded; the parent prompt receives a gap note
- `"retry_once"` — retry the failed child on the next model/subagent tier before deciding

Choose disposition before the graph starts — it expresses what "good enough" looks like:

| Situation | Disposition |
|---|---|
| All children are critical (e.g. code changes) | `abort` |
| Non-critical research child, partial result is fine | `skip` |
| Child does external calls, transient failures expected | `retry_once` |
| Gate child for all downstream work | `abort` |

### 4) Mixed graph (pipeline + fan-out)

Fan-out children can themselves have `depends_on` for serial steps within a parallel branch. The parent synthesis still waits for all branches to resolve.

```
delegate_task(
  task="synthesize",
  on_child_failure="skip",
  children=[
    {task: "branch A step 1", id: "a1"},
    {task: "branch A step 2", depends_on: ["a1"]},
    {task: "branch B (independent)"},
  ]
)
```

## Subagent fallback chain

When a subagent is specified, the runtime has three tiers:
1. Primary — the named subagent profile (e.g. `implementer`)
2. Secondary — fallback subagent if primary fails
3. Tertiary — main LLM as final fallback

`retry_once` disposition walks this chain before giving up. If no subagent is specified, the job already ran on main — `retry_once` means one literal re-run, then abort.

## Retry and redirect

- Use `retry_job` when a job failed and needs a re-run with optional corrective feedback.
- Use `redirect_job` when a running job is off-track or a failed job needs a different approach.

Provide specific correction feedback — what to do differently, not generic "try again".

## Contract quality checklist

Before delegating:
- Task states the desired end state clearly
- Deliverables name exact files/artifacts when possible
- Constraints capture must-follow limits
- Validation commands are meaningful and fast
- `on_child_failure` / `on_dependency_failure` set intentionally (don't always accept `abort`)

## Anti-patterns

Avoid:
- Delegating trivial questions
- Unnecessary chains when one task is enough
- Vague tasks with no deliverables
- Overusing fan-in for simple sequential work
- Leaving failure disposition as `abort` when partial results are acceptable
- A single agent handling a large multi-phase rename or refactor — use a graph

Keep orchestration simple and outcome-focused.
