Subagent orchestration

Orchestrating Subagents

Core Principles

• Always suggest subagent invocation when task matches their expertise
• User has final decision on invocation
• Prefer multiple parallel invocations for independent tasks with strict scopes
• ALWAYS define: files to modify, files NOT to touch, specific task boundaries

When to Use Parallel Invocation

Invoke multiple subagents in a single message when:

• Tasks are completely independent
• Each task has strict, non-overlapping scope
• No task depends on another's results

Examples:

• ✓ "Explore authentication flow" + "Review recent auth changes" (parallel)
• ✗ "Explore auth flow then refactor based on findings" (sequential - second depends on first)

Scope Definition Template

When proposing subagent invocation, use this structure:

Task: [Clear, single-sentence description]

Files to modify: [Explicit list with paths]

Files NOT to touch: [Explicit exclusions - be specific]

Constraints: 
- [Business rules to follow]
- [Patterns to maintain]
- [Technical requirements]

Reference docs: [@AGENTS.md, @docs/architecture.md, etc.]

Decision Framework

Before suggesting subagents, verify:

1. Is the scope clearly bounded? Can you define exact files and boundaries?
2. Is it independent? Does it require results from another task first?
3. Is it delegable? Would a subagent have enough context?

If any answer is "no", handle the task directly or break it down further.

Anti-patterns to Avoid

• Vague file specifications ("update related files")
• Missing exclusions (failing to specify what NOT to touch)
• Sequential tasks disguised as parallel (one depends on the other)
• Unbounded scopes ("refactor the codebase")
• Missing context references (no @file references for subagent to read)