sub-agent-orchestrator

---
name: sub-agent-orchestrator
description: Manages parent/child agent relationships with task delegation and result aggregation. Supports sequential chains, parallel fans, conditional routing, retry logic, timeout handling, and YAML-based visual workflow definition.
tools: Read, Write, Agent, Bash
user_invocable: true
---

# Sub-Agent Orchestrator

Design and execute multi-agent pipelines where each step is a different agent that depends on the previous one. Define roles, dependencies, and handoffs in YAML, then run sequential, parallel, conditional, loop, and map-reduce workflows with retry, timeout, and validation.

Unlike Agent Army (homogeneous parallel code changes) and Agent Swarm (homogeneous parallel data processing), this orchestrator coordinates heterogeneous pipelines where the output of A feeds the input of B.

## Contents

- `references/patterns.md` -- The six workflow patterns and the comparison to Agent Army/Swarm.
- `references/workflow-schema.md` -- Full YAML workflow definition language.
- `references/examples.md` -- Complete worked workflows (research-to-proposal, lead scoring).
- `references/execution-engine.md` -- Per-step execution model, retry, timeout, validation, edge cases.
- `references/templates.md` -- Reusable workflow scaffolds.
- `references/visual-and-reporting.md` -- Text diagrams and the execution report template.

## Workflow

1. Determine the mode from the request:
   - Run a workflow file: read the YAML at the given path.
   - Define and run inline: convert the natural-language description into a workflow YAML (see `references/workflow-schema.md`), then show it for approval.
   - Dry run: parse, validate, resolve inputs, and show the execution plan without deploying agents.
   - Inspect: parse the YAML and produce a human-readable description plus a text diagram (see `references/visual-and-reporting.md`).

2. Parse and validate the workflow: confirm required fields, that agent IDs resolve, and that there are no circular dependencies. Report syntax or reference errors with the offending line. See `references/execution-engine.md`.

3. Resolve inputs: collect every required input from the user before starting; apply defaults for optional inputs.

4. Build the execution DAG and run each step in topological order using the matching execution model (sequential, parallel, conditional, loop, map). See `references/execution-engine.md`.

5. After each agent completes, validate its output against the agent's schema and rules. On failure, apply the retry/timeout/failure policy (skip, abort, or fallback).

6. On completion, present results using the execution report template in `references/visual-and-reporting.md`. For partial or failed runs, report what completed, what failed, and any collected partial output.

## Choosing a pattern

Match the task shape to a pattern, then scaffold from `references/templates.md`:

- Strict ordering of distinct steps: sequential chain.
- One input scored or analyzed from multiple angles: parallel fan-out/fan-in.
- Input routed by classification: conditional routing.
- Output must meet a quality bar: loop with a validator.
- Large input chunked and recombined: map-reduce.
- A step needs a backup approach on failure: pipeline with fallback.

See `references/patterns.md` for diagrams and examples of each.