task-router

# 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?
  YE