Task Router

---
name: task-router
description: |
  Decision matrix for choosing optimal approach to any task. Helps Claude
  decide when to delegate to sub-agents vs. working directly. Use when
  starting a new task or unsure of best approach.
allowed-tools: [Read]
---

# Task Router Skill

This skill provides clear decision rules for choosing the optimal approach to any task.

## Purpose

**Problem**: Claude has many tools (sub-agents, direct work, parallel calls) but no clear guidance on when to use each.
**Solution**: Decision matrix with clear rules and examples.

## When to Use

Activate this skill when:
- Starting a new task and unsure of approach
- Task seems complex (>30 min, >5 files)
- User asks "what's the best way to do X?"
- Need to validate chosen approach

## Decision Matrix

### 🤖 Use `agent-developer` Sub-Agent

**Trigger Conditions**:
- Building/creating mini-agents (Python with OpenAI Agents SDK)
- Implementing executive agent configs (YAML)
- Adding skills to skill registry
- Writing job handlers for BullMQ
- Integrating MCP servers
- System Python Architecture tasks

**Examples**:
- "Create a Slack notification mini-agent"
- "Build job handler for experiment tracking"
- "Add Google Docs skill to registry"

**Why Delegate**:
- Specialized knowledge of agent patterns
- Knows OpenAI Agents SDK deeply
- Understands System Python Architecture
- Has MCP integration best practices
- 75% faster than manual implementation

**How to Invoke**:
```
Task tool with:
- subagent_type: "agent-developer"
- prompt: "Create [specific agent/handler] with [requirements]"
```

---

### 🔍 Use `Explore` Sub-Agent

**Trigger Conditions**:
- Finding files by pattern/keyword
- Understanding how a feature works
- Locating implementation of functionality
- Searching across multiple directories
- Don't know exact file location

**Examples**:
- "Where are errors from client handled?"
- "Find all authentication-related code"
- "How does the SSE streaming work?"

**Why Delegate**:
- Multi-round investigation capability
- Pattern matching across codebase
- Faster than manual Grep/Glob
- Systematic exploration approach

**How to Invoke**:
```
Task tool with:
- subagent_type: "Explore"
- prompt: "Find [what you're looking for]"
- Specify thoroughness: "quick", "medium", "very thorough"
```

---

### 🧪 Use `labs-specialist` Sub-Agent

**Trigger Conditions**:
- Experiment tracking logic
- Validation algorithms (Type A/B)
- Playbook generation
- ML service integration (Vertex AI)
- BigQuery query logic for Labs
- Reach/Creative intelligence features

**Examples**:
- "How does experiment validation work?"
- "Implement playbook confidence scoring"
- "Fix experiment tracking job"

**Why Delegate**:
- Expert in Labs domain logic
- Knows validation algorithms
- Understands ML service architecture
- Familiar with BigQuery integration

**How to Invoke**:
```
Task tool with:
- subagent_type: "labs-specialist"
- prompt: "Explain/fix/implement [Labs-specific task]"
```

---

### 🗄️ Use `database-navigator` Sub-Agent

**Trigger Conditions**:
- Understanding database schema
- Analyzing migrations
- Finding entity relationships
- Query optimization
- JSONB structure analysis
- Foreign key dependencies

**Examples**:
- "Show me the Labs database schema"
- "What tables are related to experiments?"
- "Explain the migration 175800000*"

**Why Delegate**:
- Specialized in schema analysis
- Understands TypeORM patterns
- Can trace relationships
- Migration expertise

**How to Invoke**:
```
Task tool with:
- subagent_type: "database-navigator"
- prompt: "Analyze [database/schema/migration topic]"
```

---

### 🏗️ Use `architecture-explorer` Sub-Agent

**Trigger Conditions**:
- Understanding service boundaries
- Data flow analysis
- Integration points between services
- API communication patterns
- System design questions

**Examples**:
- "How does Frontend talk to Cognitive Engine?"
- "Explain the SSE streaming architecture"
- "What's the agent execution flow?"

**Why Delegate**:
- Holistic system understanding
- Service boundary expertise
- Data flow visualization
- Integration pattern knowledge

**How to Invoke**:
```
Task tool with:
- subagent_type: "architecture-explorer"
- prompt: "Explain [system/integration/flow]"
```

---

### ✋ Work Directly (No Sub-Agent)

**When to Work Directly**:
- Simple file edits (<50 lines changed)
- Quick bug fixes (known location)
- Documentation updates
- Configuration changes
- Reading 1-3 specific files
- Small refactors

**Examples**:
- "Fix typo in labs.controller.ts:123"
- "Update CLAUDE.md with new model"
- "Change port in config"

**Why Direct**:
- Faster for simple tasks
- No delegation overhead
- Clear, known scope

**How to Execute**:
- Use Read, Edit, Write tools directly
- Use TodoWrite for tracking if multi-step
- Parallel tool calls if multiple independent operations

---

## Special Cases

### Parallel Tool Calls

**Use When**:
- Reading multiple independent files
- Running multiple independent commands
- Checking multiple services
- Validating multiple configurations

**Example**:
```
Single message with:
- Read tool (file1.ts)
- Read tool (file2.ts)
- Read tool (file3.ts)
All in one response block
```

**Why**: 3x faster than sequential reads

---

### Plan Sub-Agent

**Use When**:
- Need to plan multi-step implementation
- Breaking down complex feature
- Creating implementation roadmap
- Analyzing technical approach

**Example**: "Plan the implementation of playbook management APIs"

---

### Exploration Journal

**Always Check When**:
- User says "continue", "resume", "pick up where we left off"
- Starting work on familiar topic
- Complex investigation (might have been explored before)

**Location**: `docs/exploration/CURRENT_SESSION.md`

**Why**: Avoid repeating work, maintain continuity

---

## Decision Flowchart

```
START: New Task Received
  ↓
Is it continuation work?
  YES → Read exploration journal first
  NO  → Continue
  ↓
Is it simple (<30 min, <5 files, known location)?
  YES → Work directly
  NO  → Continue
  ↓
Is it development (agent/handler/skill)?
  YES → Use agent-developer
  NO  → Continue
  ↓
Is it exploration (find/understand/locate)?
  YES → Use Explore sub-agent
  NO  → Continue
  ↓
Is it Labs-specific?
  YES → Use labs-specialist
  NO  → Continue
  ↓
Is it database/schema?
  YES → Use database-navigator
  NO  → Continue
  ↓
Is it architecture/integration?
  YES → Use architecture-explorer
  NO  → Continue
  ↓
DEFAULT → Work directly with TodoWrite tracking
```

---

## Quality Checks

After choosing approach, verify:

### ✅ Correct Choice If:
- Approach matches decision matrix
- Estimated time saved > delegation overhead
- Sub-agent has specialized knowledge for this task
- Task is complex enough to benefit from specialization

### ❌ Wrong Choice If:
- Using sub-agent for simple 1-file edit
- Working directly on complex multi-file feature
- Not using parallel calls for independent operations
- Forgetting to check exploration journal on continuation

---

## Examples: Good vs. Bad Decisions

### Example 1: Building Job Handler

**Task**: "Create experiment tracking job handler"

❌ **Bad**: Work directly
- Why bad: 200+ lines, needs BullMQ patterns, integration knowledge
- Result: Slow, might miss patterns, no validation

✅ **Good**: Use agent-developer sub-agent
- Why good: Specialized in job handlers, knows patterns, faster
- Result: Production-quality handler following best practices

---

### Example 2: Finding Implementation

**Task**: "Where is SSE streaming implemented?"

❌ **Bad**: Manual Grep + Read chain
- Why bad: Multiple rounds, trial and error, slow
- Result: Might miss files, incomplete understanding

✅ **Good**: Use Explore sub-agent
- Why good: Systematic search, multi-round investigation
- Result: Complete findings with file paths and line numbers

---

### Example 3: Simple Config Change

**Task**: "Update port in .env.example"

❌ **Bad**: Use agent-developer sub-agent
- Why bad: Massive overhead for 1-line change
- Result: Slower, overkill

✅ **Good**: Work directly
- Why good: Read → Edit → Done in 30 seconds
- Result: Fast, efficient

---

### Example 4: Reading Multiple Files

**Task**: "Check these 5 files for X pattern"

❌ **Bad**: Sequential reads (5 separate messages)
- Why bad: 5x slower than parallel
- Result: Wastes time and tokens

✅ **Good**: Parallel tool calls (single message, 5 Read tools)
- Why good: All reads execute simultaneously
- Result: 5x faster

---

## Integration with Hooks

This skill complements the hooks system:

1. **Pre-Task Analysis Hook** suggests which approach to use
2. **Task Router Skill** provides detailed decision matrix
3. **Quality Check Hook** validates approach was optimal

User can invoke this skill manually: "What's the best way to [task]?"

---

## Success Criteria

✅ Correct sub-agent chosen for specialized tasks
✅ Direct work used for simple operations
✅ Parallel calls used for independent operations
✅ Exploration journal checked on continuation
✅ No obvious inefficiencies in approach

---

**Remember**: The goal is OPTIMAL approach, not just ANY approach. Use sub-agents when they provide value, work directly when they don't!