Agent Routing — Choose the Right Execution Pattern

Decides whether a task needs Agent Teams, subagents, or a single focused session. Consult this before creating any team or spawning more than 2 subagents. Before spinning up agents or teams, run this decision framework. The goal is to match the execution pattern to the task, not default to the most complex option.

Step 0: Decision-Lock Check

Before analyzing execution pattern, check for an existing CONTEXT.md:

1. CONTEXT.md exists (in reports/YYYY-MM-DD_slug/ or feature working directory) → Read the ## Decisions section. Use locked decisions to inform the 5-dimension analysis below. Do not re-ask anything already decided.

2. No CONTEXT.md AND task is complex (3+ files across 2+ concerns) → Recommend /discuss first:

   This task touches [N] files across [concerns]. Recommend running /discuss to lock decisions before routing.

   If the user says "skip" or "just go", proceed to Step 1 without a CONTEXT.md.

3. Task is small (1-2 files, single concern) → Skip directly to Step 1. No discussion needed.

Step 1: Task Analysis

Evaluate the task against these 5 dimensions. Be honest — do not inflate complexity to justify a team.

1. File Count

How many files will be WRITTEN or EDITED (not read)?

• 1-2 files: Single session territory
• 3-4 files: Subagent territory
• 5+ files across different concerns: Team territory

2. Concern Separation

Are the outputs independent or do they need coordination?

• All outputs go in the same file or closely related files: Single session
• Outputs are in different files but follow the same pattern: Subagents (each mirrors a known pattern independently)
• Outputs are in different files AND require different expertise (content vs code vs config vs deploy): Team

3. Handoff Requirement

Does any task need the OUTPUT of another task before it can start?

• No handoffs — all tasks can run with existing context: Subagents
• Linear handoff — A feeds B feeds C: Single session (sequential in one context is faster than agent-to-agent messaging)
• Fan-out handoff — A feeds B, C, D simultaneously: Team (A completes, then B/C/D run in parallel)

4. Review Requirement

Does output need human-style judgment before the next step?

• No review needed — mechanical output: Subagents
• Self-review sufficient — one agent can check its own work: Single session
• Cross-review needed — one agent's output should be evaluated by a different agent with different context: Team

5. Voice/Quality Gate

Does the output require voice compliance, brand checking, or quality enforcement?

• No voice requirements (code, config, data): Any pattern works
• Voice required but I (the main session) am writing it: Single session (I already have voice context loaded)
• Voice required AND someone other than the main session is writing: Team with Writer + Reviewer roles

Step 2: Route to Pattern

Score the task. Count how many dimensions point to each pattern:

Pattern A: Single Focused Session

Use when: 3+ dimensions point to "single session"

The main session handles everything. Use read-only Explore subagents (small/fast model) for initial research and lightweight subagents for web lookups, but all writing/editing stays in the main session.

Typical tasks:

• Adding 1-2 wiki entries to a data file
• Updating a page + its data source
• Writing a new skill file
• Bug fixes across a few related files
• Any task where YOU are the only writer

Subagent budget: 1-2 lightweight agents (Explore for repo scan, a small model for web research). These protect context window, not parallelize work.

Pattern B: Parallel Subagents

Use when: 3+ dimensions point to "subagents"

Launch independent subagents via the Task tool. Each gets a specific prompt, works in isolation, reports back. No inter-agent communication. Parent orchestrates waves.

Typical tasks:

• Building 3+ pages that mirror an existing pattern
• Writing multiple independent data entries
• Running research across several unrelated topics
• Parallel file generation where outputs do not reference each other

Subagent budget: 2-5 agents. Assign a small/fast model to mechanical tasks (copy-pattern, scan, format). Assign a stronger model to creative or judgment tasks. Run them in waves.

Pattern C: Agent Teams

Use when: 3+ dimensions point to "team" AND at least one of these is true:

• Multiple agents need to MESSAGE each other (not just report to parent)
• A shared task list with dependencies is needed to enforce sequencing
• Different agents need different ROLES with different context (Writer reads voice files, Reviewer reads checklist, Deploy reads build config)
• The task will take 15+ minutes and agents need to self-coordinate

Typical tasks:

• Full website feature: data file + page components + navigation + deploy
• Content pipeline: research agent feeds writer, writer feeds reviewer, reviewer approves deploy
• Multi-system changes: frontend + backend + tests + CI config where each agent owns a layer
• Any task where 3+ agents need to coordinate across 5+ files with handoffs

Team budget: 2-4 agents maximum. Every teammate runs its own context window (~7x token multiplier). Keep teams small and focused. Clean up immediately when done.

Step 3: Announce the Decision

Before executing, state the routing decision to the user:

Routing: [Pattern A/B/C]

• Decisions: [CONTEXT.md path, or "none — inline decisions"]
• Files to edit: [count]
• Concerns: [list]
• Handoffs needed: [yes/no]
• Review needed: [yes/no]
• Voice gate: [yes/no]
• Why this pattern: [1 sentence]

This gives the user a chance to override. If they say "use teams anyway" after seeing the analysis, respect that — they may want to test the infrastructure or have context you do not.

Anti-Patterns (What NOT to Do)

1. Team for a 1-2 file edit. The coordination overhead (TeamCreate, 5+ TaskCreate calls, SendMessage, shutdown) costs more than just writing the code.

2. Redundant research agents. Do not spawn a team researcher AND a subagent researcher for the same topic. Pick one. A small-model subagent for mechanical lookups, a strong-model team researcher for deep analysis requiring judgment.

3. Team where you are the only writer. If the main session is writing all the code anyway, teammates become expensive advisors who report after the work is done. Use subagents for research and write the code yourself.

4. Subagents for sequential tasks. If task B needs the output of task A, running them as subagents means A finishes, reports back, then you launch B. That is just a slower single session with extra overhead. Keep sequential work in one context.

5. Defaulting to teams because the user said "agents." The user may say "use agents on this" meaning "parallelize where it makes sense," not "create a full team with task lists and messaging." Run this framework first. Often "use agents" means Pattern B (2-3 subagents), not Pattern C (full team).

Quick Reference