Agent Routing: Delegation & Invocation Quality

Use this skill to (1) identify when to delegate work to specialist agents, and (2) ensure every subagent invocation carries comprehensive context and a precise output description. Poor invocations waste tokens and produce unusable results.

Agent & Subagent Catalog

User-Facing Agents (handoff targets)

Subagents (invoked via runSubagent)

Routing Decision Framework

┌─────────────────────────────────────────────────────────────────┐
│                  SHOULD I DELEGATE?                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Can I handle this directly in <10 steps?                    │
│     YES → Proceed inline                                        │
│     NO  → Consider delegation                                   │
│                                                                 │
│  2. Do I need information I don't have?                         │
│     YES → Delegate to `research` or `extract` subagent          │
│     NO  → Continue                                              │
│                                                                 │
│  3. Do I need documentation context?                            │
│     YES → Delegate to `doc-awareness` subagent                  │
│     NO  → Continue                                              │
│                                                                 │
│  4. Is this a specialized domain?                               │
│     Tests/coverage → `backend-test` agent                       │
│     Security/quality → `review` agent                           │
│     Architecture → `advisor` agent                              │
│     Multi-file edits → `multi-edit` subagent                    │
│     Complex commands → `command` subagent                       │
│     NO  → Continue inline                                       │
│                                                                 │
│  5. Will output benefit from structured review?                 │
│     YES → Offer `review` handoff after completion               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Trigger Heuristics

Signal Words → Agent Mapping

Complexity Triggers

Subagent vs Handoff

Subagent Invocation Protocol

Every subagent invocation MUST satisfy two quality requirements:

1. Comprehensive context — the subagent has everything it needs to work autonomously
2. Precise output description — the subagent knows exactly what to return and how

Subagents are stateless and context-isolated. They cannot see your conversation history, open files, prior tool calls, or any other ambient context. Every piece of information they need must be explicitly included in the prompt.

The Invocation Quality Checklist

Before every runSubagent call, verify these 7 elements:

┌─────────────────────────────────────────────────────────────────┐
│           SUBAGENT INVOCATION QUALITY CHECKLIST                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  CONTEXT (what the subagent needs to know)                      │
│  ─────────────────────────────────────────                      │
│  C1. TASK — What specific work to perform                       │
│  C2. SCOPE — Boundaries (files, modules, directories)           │
│  C3. BACKGROUND — Why this matters / what led here              │
│  C4. CONSTRAINTS — Rules, patterns, conventions to follow       │
│  C5. PRIOR KNOWLEDGE — Findings from earlier steps the          │
│      subagent can't see but needs                               │
│                                                                 │
│  OUTPUT (what the caller needs back)                            │
│  ────────────────────────────────────                           │
│  O1. DELIVERABLE — What artifact/information to return          │
│  O2. FORMAT — Structure, sections, level of detail              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Context Assembly Rules (C1–C5)

Output Description Rules (O1–O2)

The Integration Rule

The caller MUST specify how they will USE the subagent's output. This is the single most effective way to ensure the subagent returns the right level of detail and focus:

"I will use your findings to [write tests / make an architecture decision / construct edit instructions / present options to the user]"

This sentence tells the subagent:

• What level of detail is needed (implementation-ready vs. summary)
• What perspective to take (test-writer vs. architect vs. editor)
• What to prioritize (actionable patterns vs. exhaustive coverage)

Per-Subagent Invocation Templates

research — Information Gathering

Research [specific topic]:
- [Specific question 1]
- [Specific question 2]

Scope: [directories, modules, file patterns to search]
Background: [why this research is needed — 1-3 sentences]
Prior knowledge: [what we already know, so the subagent doesn't re-discover it]

Output: [what findings I need — patterns, file references, architecture overview]
I will use your findings to [implement feature X / decide between approaches / write tests].

Good example: "Research how WebSocket routes are registered in the broker module. Scope: backend/src/trading_api/modules/broker/ws/. Background: We're adding a new WS route for position updates and need to follow the existing pattern. Prior knowledge: We know WsRouterBase is the base class (from backend/src/trading_api/core/). Output: Step-by-step pattern showing class inheritance, route registration, and service wiring with file:line citations. I will use your findings to implement the new route."

Bad example: "Research WebSocket stuff" — No scope, no background, no output spec, no usage intent.

extract — File Analysis

Extract mode (specific data points):

Analyze [target files/pattern] to find:
- [Specific question 1]
- [Specific question 2]

Scope: [exact files or directory patterns]
Background: [why these data points matter]
Prior knowledge: [relevant context from earlier steps]

Output: Summary answer + per-file findings with line citations.
I will use your findings to [specific downstream action].

Digest mode (holistic summary):

Digest [target file/module/directory] for [stated purpose]:
- Focus on: [aspects that matter]
- Ignore: [aspects to skip]

Background: [what I'm trying to accomplish]

Output: Compressed module overview covering purpose, key components, dependencies, and patterns.
I will use this digest to [orient myself / plan implementation / write documentation].

doc-awareness — Documentation Discovery

Context: [what you're working on — task, feature, module, problem area]
Background: [why documentation context is needed — 1-2 sentences]
Prior knowledge: [docs already consulted, so the subagent doesn't re-read them]

Output: [what kind of documentation insight you need — patterns, conventions, step-by-step guidance, constraints]
I will use your findings to [implement correctly / follow project conventions / understand constraints].

Good example: "Context: Adding a new REST endpoint to the broker module (GET /positions). Background: This endpoint needs auth, versioning, and OpenAPI spec generation. Prior knowledge: We've already read the module's existing api/v1.py and understand the router pattern. Output: Versioning conventions, OpenAPI spec generation flow, and authentication middleware wiring — focus on what we haven't seen in api/v1.py. I will use your findings to ensure the endpoint follows all project conventions."

request-refinement — Gap Analysis

Analyze this user request for completeness and ambiguity:

**User Request**: "{the user's exact original request}"

**Available Context**:
- Current file: {file path or "none"}
- Conversation history: {summary of relevant prior context}
- Project type: {e.g., "full-stack trading platform with modular backend"}

**Prior knowledge**: {any context gathered that helps scope the request}

**Caller Intent**: I will use your report to either proceed (if no critical gaps) or ask the user targeted questions via `mode-interactive` (if critical gaps exist).

Output: Structured gap report with context decomposition table, bridged assumptions with rationale, and critical gaps with suggested clarification questions ranked by impact.

multi-edit — Batch Code Editing

Apply mode (pre-specified edits):

Apply these edits:

File: path/to/file1.py
- Old: `exact string to replace with 3-5 lines context`
  New: `replacement string`

File: path/to/file2.ts
- Old: `exact string to replace with 3-5 lines context`
  New: `replacement string`

Background: [why these changes are being made]
Constraints: [e.g., preserve API compatibility, follow existing naming patterns]

Output: Edit report showing success/failure per file with line references, plus verification results.
Verify: [get_errors | lint | format | none]

Derive mode (intent-driven):

Make these changes across [scope/files]:
- [High-level change description 1]
- [High-level change description 2]

Background: [why these changes are needed]
Constraints: [patterns to follow, APIs to preserve, naming conventions]
Prior knowledge: [reference implementation showing the pattern, e.g., "Follow the pattern in `modules/auth/api/v1.py`"]

Output: Edit report with all changes applied, verification results, and any errors introduced.
Verify: [get_errors | lint | format | none]

command — Terminal Execution

Execute the following command(s):
1. {command or description} [timeout: {N}s] [cwd: {path}]
2. {command or description} [timeout: {N}s] [cwd: {path}]

Background: [why these commands are being run]
Execution: {parallel | sequential | auto}

Output: Execution report with exit codes, duration, and extracted findings.
Extract: {specific patterns — errors, test failures, coverage numbers, build artifacts}

Invocation Quality Self-Check

Run this 4-point check before every runSubagent call:

BEFORE INVOKING: {subagent_name}
├── 1. CONTEXT COMPLETE?
│   ├── Can the subagent do its job with ONLY what I've written? (no ambient context)
│   ├── Have I specified scope boundaries? (C2: files, dirs, modules)
│   ├── Have I explained WHY? (C3: background + Integration Rule: usage intent)
│   └── Have I included prior knowledge it can't access? (C5: earlier findings)
│
├── 2. OUTPUT SPECIFIED?
│   ├── Is the deliverable named? (O1: list, report, digest, edit plan, gap analysis)
│   ├── Is the format/structure clear? (O2: table, sections, per-file breakdown)
│   └── Does the subagent know how I'll USE its output? (Integration Rule)
│
├── 3. RIGHT SUBAGENT?
│   ├── Read-only codebase search → research
│   ├── File-specific data points or module digest → extract
│   ├── Documentation guidance → doc-awareness
│   ├── Request gap analysis → request-refinement
│   ├── Multi-file code changes → multi-edit
│   └── Complex/large-output terminal commands → command
│
└── 4. WORTH DELEGATING?
    ├── Is this >10 steps or requires isolated exploration? → YES, delegate
    └── Is this <5 steps with context I already have? → NO, do inline

Invocation Anti-Patterns

Integration with Existing Skills