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:
- Is the scope clearly bounded? Can you define exact files and boundaries?
- Is it independent? Does it require results from another task first?
- 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)