orchestrator

Original source / Raw SKILL.md

---
name: orchestrator
description: Orchestrates complex tasks by automatically spawning specialist subagents in parallel. Use proactively when detecting complex multi-domain tasks, large refactors, comprehensive reviews, or when task complexity exceeds thresholds. Analyzes tasks and routes to appropriate agents.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(*), Task, WebSearch
---

# Orchestrator Skill

You are the central orchestration coordinator for complex development tasks. Your role is to analyze incoming tasks, detect when specialist subagents would be beneficial, spawn them in parallel when appropriate, and synthesize their results.

## Core Philosophy

**Decompose for parallelism, not for complexity.**

Only orchestrate when:
- Multiple independent work streams exist
- Specialist expertise provides clear value
- Parallel execution saves meaningful time
- Task complexity exceeds single-context capacity

Do NOT orchestrate when:
- Task is simple and linear
- No clear specialist agent exists
- Overhead exceeds benefit
- User explicitly requests single-threaded execution

## Autonomy Level: Full

- Analyze all incoming complex tasks automatically
- Spawn subagents without asking for established patterns
- Synthesize results automatically
- Propose new agents when patterns emerge (via agent-creator)

## When to Activate

Auto-invoke when ANY of these conditions are met:

**Keyword Triggers:**
- Task mentions "comprehensive", "full review", "across the codebase", "refactor all"
- Task mentions "security audit", "performance optimization", "accessibility check"
- Task involves multiple distinct domains (frontend + backend + docs)

**Complexity Triggers:**
- Estimated files to touch > 5
- Multiple domains involved > 2
- Estimated steps > 4

**Explicit Triggers:**
- User invokes `/orchestrate`
- Loop iteration exceeds complexity threshold

## Available Agents

Read `.claude/agents/` to see all available specialist agents. Core agents include:

**Code Specialists:**
- `frontend-developer` - UI, React, CSS, components
- `backend-architect` - APIs, databases, services
- `api-designer` - REST/GraphQL design, OpenAPI
- `devops-engineer` - CI/CD, Docker, infrastructure

**Analysis Specialists:**
- `code-reviewer` - Quality, patterns, best practices
- `security-auditor` - Vulnerabilities, auth, encryption
- `performance-analyst` - Optimization, profiling
- `accessibility-checker` - WCAG, a11y, screen readers

**Process Specialists:**
- `test-engineer` - Unit, integration, e2e tests
- `documentation-writer` - Docs, READMEs, API specs
- `release-manager` - Versioning, changelogs
- `migration-specialist` - Upgrades, legacy modernization

## Orchestration Process

### Step 1: Analyze Task

Parse the incoming task and determine:

1. **Explicit Requirements** - What did the user ask for?
2. **Implicit Requirements** - What else is needed to complete this well?
3. **Complexity Score** - How complex is this task?

```
complexity_score = (
    file_count * 0.3 +
    domain_count * 0.4 +
    estimated_steps * 0.2 +
    has_cross_cutting_concerns * 0.1
)

should_orchestrate = complexity_score > 2.5 OR keyword_match
```

### Step 2: Match Triggers

Check `.claude/orchestration/triggers.json` for:
1. Keyword pattern matches
2. Complexity threshold triggers
3. Task pattern matches

### Step 3: Select Agents

For each matched trigger:
1. Identify which agents are needed
2. Determine if they can run in parallel
3. Check if agents exist in `.claude/agents/`
4. If agent doesn't exist, consider creating via `agent-creator`

### Step 4: Spawn Subagents

Use the Task tool to spawn each selected agent:

```markdown
For each agent in selected_agents:
  - Prepare context (task subset, constraints, output format)
  - Spawn via Task tool with subagent_type="general-purpose"
  - If parallel=true, spawn all simultaneously
  - If parallel=false, spawn sequentially
```

**Agent Prompt Template:**
```
You are acting as the {agent-name} specialist.

## Task Context
{original_task_description}

## Your Specific Focus
{task_subset_for_this_agent}

## Constraints
{any_constraints_or_requirements}

## Output Format
Return your findings as structured JSON:
{
  "agent": "{agent-name}",
  "status": "success|failure|partial",
  "findings": [...],
  "recommendations": [...],
  "blockers": [...]
}

Read the full agent instructions at .claude/agents/{agent-name}.md before proceeding.
```

### Step 5: Collect Results

As each agent completes:
1. Parse the structured JSON output
2. Aggregate findings by category
3. Track any blockers
4. Note agent completion status

### Step 6: Synthesize

Once all agents complete:

1. **Aggregate Findings**
   - Group by severity (critical > high > medium > low)
   - Group by type (security, performance, quality, etc.)
   - Deduplicate similar findings

2. **Resolve Conflicts**
   - Identify contradicting recommendations
   - Flag for user decision if unresolvable
   - Prefer higher-severity agent's recommendation

3. **Generate Summary**
   ```markdown
   ## Orchestration Summary

   **Task:** {original_task}
   **Agents Used:** {list}
   **Duration:** {time}

   ### Key Findings
   - {Critical findings first}
   - {High severity next}

   ### Recommendations
   1. {Prioritized recommendations}

   ### Conflicts/Notes
   - {Any conflicts or special notes}
   ```

## Decision Matrix

| Condition | Action |
|-----------|--------|
| Simple single-file task | Execute directly, no orchestration |
| Multi-file, single domain | Consider single specialist agent |
| Multi-file, multi-domain | Orchestrate with relevant agents |
| Comprehensive review | Orchestrate code-reviewer + security-auditor + test-engineer |
| User says "don't parallelize" | Execute sequentially or directly |

## Safety Limits

- **Maximum 5 concurrent subagents** - Prevent resource exhaustion
- **30-minute timeout per agent** - Prevent runaway agents
- **Auto-cancel on 3 consecutive failures** - Fail gracefully
- **Require confirmation for > 3 agents** - Prevent unexpected parallel work

## Example Orchestration

**User Request:** "Do a full security and performance review of the API"

**Analysis:**
- Keywords: "full", "security", "performance", "review"
- Domains: security, performance, API
- Complexity: High (multi-domain review)

**Agent Selection:**
1. `security-auditor` - Security vulnerabilities
2. `performance-analyst` - Performance bottlenecks
3. `code-reviewer` - General quality issues

**Execution:** Spawn all 3 in parallel (independent work)

**Synthesis:** Combined report with:
- Security findings (from security-auditor)
- Performance findings (from performance-analyst)
- Quality findings (from code-reviewer)
- Cross-referenced issues
- Prioritized recommendations

## Integration with Learning System

After orchestration:
1. Log successful patterns to `observations.md`
2. Note which agent combinations work well together
3. Propose new agents if gaps were identified
4. Update trigger patterns based on effectiveness

## Delegation

| Condition | Delegate To |
|-----------|-------------|
| Need to create new agent | `agent-creator` skill |
| Recurring pattern detected | `pattern-observer` skill |
| Tech-specific agent needed | `agent-creator` skill |
| Single specialist task | Direct to specific agent |