Orchestrate Team of Agents

Choose an execution pattern

The number of agents is not the important decision. Choose based on coupling: whether the outputs can be produced independently, whether later work depends on earlier results, and whether the work needs a measurable loop.

Need	Use	Runtime behavior	Best first instruction
One specialist result	`delegate_task`	One synchronous sub-agent returns one result to the lead	“Delegate the repository map to the `researcher`; do not edit files.”
Two to five independent results	`delegate_parallel`	Up to five sub-agents run concurrently and return labeled outputs	“Review security, accessibility, tests, and performance in parallel; consolidate findings by severity.”
Shared tasks and dependencies	Agent Team	The first idle teammate claims the next unblocked task from a lead-managed graph	“Create a team of compatible implementers with disjoint files and dependency-gated tasks.”
Current external evidence	`/deep-research`	Scopes subquestions, reads sources, cross-checks claims, and saves a cited report	`/deep-research Compare durable workflow engines for our TypeScript service...`
Repeated measurable improvement	`/autoresearch`	Changes one variable, benchmarks it, keeps or reverts, logs the run, and repeats	`/autoresearch reduce unit test runtime --metric total_ms ...`

How the pieces fit together

The interactive Autohand session remains the lead. It owns the user goal, sees the registered agent definitions, chooses a delegation mechanism, and verifies the combined result. A sub-agent receives a narrower system prompt and only the tools allowed by its definition.

Discover. Run /agents definitions, create a definition with /agents new, or ask Autohand to find an exact specialist in the catalog.
Partition. Give every worker a distinct question, file boundary, output format, and completion test.
Execute. Delegate once, launch an independent swarm, or build a task graph for a persistent team.
Integrate. The lead resolves contradictory findings, checks cross-file assumptions, and runs repository-level validation.
Close. Record the result, shut down persistent teammates, and leave reviewable artifacts rather than only chat summaries.

/deep-research and /autoresearch reuse the same runtime. Deep research can discover agent and parallel-research tools for broad investigations. Autoresearch can delegate idea generation, measurement analysis, and finalization while the lead experiment loop retains ownership of the benchmark and keep/revert decision.

Run a first parallel delegation

Start Autohand in the repository you want to inspect, list the definitions available to the session, and give the lead an explicit integration contract.

cd /path/to/project
autohand

/agents definitions

Review the current branch with independent reviewer, security-auditor,
accessibility-tester, and performance-engineer sub-agents. Use parallel
delegation, keep every worker read-only, and return one deduplicated report.
For each finding include severity, file and line, evidence, impact, and the
smallest safe fix. Do not edit files.

If a named catalog role is not installed, ask the lead to search the default catalog, show the exact match and requested tool access, and wait for installation approval before delegating.

Define the operating contract

Parallelism only helps when the lead can merge the outputs. Put these details in the initial instruction instead of relying on workers to infer them:

Scope: exact directories, services, commits, or external questions each worker owns.
Mutation policy: read-only, patch allowed, command execution allowed, or isolated worktree required.
Dependencies: which result must exist before another task can start.
Output schema: findings, patch, report path, benchmark metric, or task status expected from each worker.
Evidence: file and line references for code claims; URLs and dates for external claims; command output for verification.
Stop condition: tests passing, no high-severity findings, confidence threshold reached, or experiment budget exhausted.

Avoid shared write ownership. Team children share the current workspace; the task queue does not create isolated worktrees. Do not send two write-capable agents into the same files concurrently. Separate them by directory or phase, or create isolated worktrees outside the team runtime before integration.

Use this guide family

Sub-agents and delegation Definitions, discovery paths, built-ins, permissions, and delegation limits Sub-agent Catalog Find, inspect, approve, and install existing specialist roles Agent teams and tasks Persistent teammates, task dependencies, status, messages, and shutdown /deep-research Scope current questions, cross-check sources, and save cited reports /autoresearch Configure metrics, safeguards, hooks, sub-agent phases, and experiment artifacts Agent orchestration playbooks Copyable playbooks for engineering, operations, research, and optimization

Selection rules that scale

Use a built-in agent when its tool boundary already fits the task. Built-ins cover codebase research, review, tests, documentation, dead-code cleanup, and TODO resolution.
Use a catalog agent for domain expertise such as PostgreSQL, Kubernetes, accessibility, compliance, or language-specific implementation.
Use a definition from a configured external directory when the role depends on repository conventions, internal commands, or a narrow ownership boundary that should travel with the project.
Use direct delegate_task or delegate_parallel calls when an exact named specialist must receive exact work. Use a team queue only when each idle teammate can safely handle each task that may become available.
Prefer one lead and three to five distinct workers over a large group of overlapping generalists.
Make the lead independently validate the integrated state. A worker saying “done” is an input to verification, not the completion criterion.