Skip to content

Expand subagent delegation guidance #522

@Aaronontheweb

Description

@Aaronontheweb

Context

Subagents are rarely used because current guidance sets a high bar for delegation.

Current Guidance

When to delegate:

  • Deep web research requiring multiple searches and synthesis
  • Code analysis on large files or multiple files
  • Summarization of long documents or web pages

When NOT to delegate:

  • Simple searches (use web_search directly)
  • Tasks requiring MCP tools (subagents only have web_search, web_fetch, file_read, attach_file)
  • Interactive browser tasks (cannot use browser MCP tools)

Proposed Expansion

Where subagents could help more:

  1. Parallel research - Spawn separate subagents for each perspective when needing multiple angles on a topic. Example: "Research competitor X" + "Research competitor Y" + "Research market trends" all at once.

  2. Background prep - Delegate research that doesn't block immediate response. "Before our meeting tomorrow, gather info on Z" - they work asynchronously.

  3. Pre-synthesis - Have them do heavy lifting of gathering sources, then I synthesize and add context. Saves time on multi-source research.

  4. Domain specialists - Create subagents like "competitor-researcher" or "tech-stacker" with tailored instructions for specific repeatable tasks.

Practical Changes:

  • Lower bar from "deep research requiring multiple searches" to "any research with 2+ sources"
  • Use for parallelizable work (multiple independent queries)
  • Let them do preliminary passes on topics before diving deep

Caveats to Keep:

  • Coordination overhead is real - spawning + waiting + integrating results takes time
  • For most tasks, direct handling is faster
  • They still can't do MCP tool discovery or browser automation
  • Minimum viable change principle still applies - don't add tooling unless needed

Suggested Update to AGENTS.md

Update the "Subagent Delegation" section to:

## Subagent Delegation

Use spawn_agent to delegate bounded, self-contained tasks to specialist subagents.
Available subagents are listed in the [available-subagents] context block.

**When to delegate:**
- Research requiring 2+ sources or multiple searches
- Parallelizable tasks (multiple independent queries can run concurrently)
- Background prep work that doesn't block immediate response
- Code analysis on large files or multiple files
- Summarization of long documents or web pages
- Preliminary passes on topics before diving deep

**When NOT to delegate:**
- Simple single searches (use web_search directly)
- Tasks requiring MCP tools (subagents only have web_search, web_fetch, file_read, attach_file)
- Interactive browser tasks (subagents cannot use browser MCP tools)
- Tasks where coordination overhead outweighs parallelization benefits

spawn_agent is NOT the same as search_tools. Subagents are named specialists
(e.g., "research-assistant", "code-analyst", "summarizer"). MCP tools are
discovered via search_tools.

**Parallelization tip:** When researching multiple independent topics, spawn
separate subagents for each - they run concurrently and reduce total wait time.

Metadata

Metadata

Assignees

No one assigned

    Labels

    subagentsspawn_agent, SubAgentActor, definition loader, discovery context layer, and related features

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions