---

name: agent-fleet-orchestration description: Use when a task splits into independent parts that can run in parallel across multiple subagents, or when a single agent context is getting too large to hold the whole job. Covers decomposition, context isolation, briefs, and merge safety.

Agent Fleet Orchestration

When to trigger

The work has two or more parts with no data dependency between them (research across sources, edits across separate files, audits across categories), or one agent's context is bloating with file dumps it does not need to keep.

Decompose for independence

Split so that no two agents write the same file and no agent needs another's output mid-run. If part B needs part A's result, that is a sequence, not a fleet. Run A, then fan out B.

Brief each agent tightly

Every subagent gets:

• A single, concrete objective and the exact deliverable shape (a file path, a JSON blob, a short answer).
• Its scope boundary: which files or directories it owns and must not touch.
• A tool budget: read-only search agents should not have write tools.
• Instruction to return the conclusion, not the raw material. A search agent returns the finding and the file:line, not the file contents.

Context isolation is the point

The reason to fan out is not just speed. A subagent runs the noisy work (reading twenty files, running a long test suite) in its own context and hands back only the distilled result, keeping the orchestrator's context clean. Delegate the search, keep the conclusion.

Merge safety

• Assign non-overlapping file ownership up front. Two agents editing one file race and lose writes.
• Serialize anything that touches shared state: a lockfile, a package manifest, a shared config. One agent owns it at a time.
• Collect results, then apply. Do not let agents merge into the main branch independently.

Pitfalls

• Over-splitting adds coordination cost that outweighs the parallelism. Three quick sequential edits can beat three agents plus a merge step.
• An agent told to "research and also implement" will burn its budget reading and leave the implementation thin. One objective per agent.
• If you spawn a fleet, do not also do the same search yourself. Wait for the result instead of duplicating the work.