arpitnath/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?
  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!