claude-capsule-kit 3.0.0

package/skills/task-router/SKILL.md

@@ -0,0 +1,390 @@
+---
+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!