agent-routing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Agent Routing -- Choose the Right Execution Pattern

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 the 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 the main session is writing it**: Single session (voice context already 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 lightweight subagents for initial research, but all writing/editing stays in the main session.

**Typical tasks:**
- Adding 1-2 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 for 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 lighter models to mechanical tasks (copy-pattern, scan, format). Assign heavier models to creative or judgment tasks.

### 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 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. 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]

From shawnla90/recursive-drift, MIT.

More from shawnla90/recursive-drift