name: orchestrator
description: Meta-skill that analyzes complex tasks and spawns specialized agents with relevant skills. Use for multi-step features, large refactors, or any work requiring coordination across domains.
license: MIT
metadata:
author: thesimpleapp
version: "1.0"

Orchestrator

Meta-skill for intelligent task routing and parallel agent coordination.

When to Use

• Multi-step features spanning frontend + backend + database
• Large refactoring efforts
• Sprint planning with multiple parallel workstreams
• Any task requiring 3+ different skill domains

Task Analysis Framework

INPUT: User request
   ↓
┌─────────────────────────────────────┐
│           ANALYZE TASK              │
│                                     │
│  1. What domains are involved?      │
│     □ Frontend (React/Flutter)      │
│     □ Backend (API/Edge Functions)  │
│     □ Database (Supabase/Postgres)  │
│     □ Testing (Unit/E2E)            │
│     □ Infrastructure (Deploy)       │
│                                     │
│  2. What's the dependency graph?    │
│     - Which tasks can run parallel? │
│     - Which need sequential order?  │
│                                     │
│  3. What context is needed?         │
│     - Database schema               │
│     - Business rules                │
│     - Existing patterns             │
└─────────────────────────────────────┘
   ↓
SPAWN SPECIALIZED AGENTS

Skill-to-Domain Mapping

Agent Spawning Patterns

Pattern 1: Parallel Feature Development

## Task: Build user dashboard with analytics

### Batch 1 (Parallel - No Dependencies)
Agent A: flutter-excellence
  → Build dashboard UI components
  → Files: lib/features/dashboard/presentation/

Agent B: supabase-mastery
  → Create analytics tables + RLS
  → Files: supabase/migrations/

Agent C: react-excellence (if web dashboard)
  → Build web dashboard components
  → Files: src/features/dashboard/

### Batch 2 (Sequential - Needs Batch 1)
Agent D: flutter-excellence OR react-excellence
  → Connect UI to Supabase
  → Depends on: Agent A/C + Agent B complete

### Batch 3 (Parallel - Testing)
Agent E: Unit tests for components
Agent F: Integration tests for API
Agent G: E2E tests for user flows

Pattern 2: Codebase Improvement

## Task: Clean up messy codebase

### Phase 1: Analysis (Sequential)
Agent A: codebase-analysis
  → Generate ANALYSIS_REPORT.md
  → Identify tech debt and patterns

### Phase 2: Planning (Sequential)
Agent B: architecture-cleanup
  → Create refactoring plan
  → Batch tasks for parallel execution

### Phase 3: Execution (Parallel)
Agent C-F: Execute refactoring batches
  → Each handles independent modules

### Phase 4: Verification (Sequential)
Agent G: code-review
  → Verify changes maintain quality

Pattern 3: New Feature Sprint

## Task: Implement feature from spec

### Phase 1: Context Loading
Load: context-loader
  → Database schema
  → Business rules
  → Existing patterns

### Phase 2: Design
Agent A: sprint-planning
  → Break into tasks
  → Identify parallel batches

### Phase 3: Implementation
Spawn agents per batch from sprint plan

### Phase 4: Quality
Agent X: code-review + security-review
  → Final quality gate

Context Requirements

Before spawning agents, ensure context is loaded:

## Required Context Checklist

□ Database Schema
  - Load from: supabase/schema.sql OR supabase/migrations/
  - Key tables and relationships

□ Business Rules
  - Load from: .claude/rules/business-logic.md
  - Domain constraints and logic

□ Existing Patterns
  - Load from: .claude/standards/ OR agent-os/standards/
  - Code conventions to follow

□ Current Sprint
  - Load from: docs/SPRINT.md (if exists)
  - Active tasks and priorities

Agent Communication Protocol

Agents don't share context directly. Coordinate via:

1. Shared Files - Write to agreed locations
2. Task Completion Signals - Mark todos complete
3. Handoff Documents - Create HANDOFF.md for next agent

Handoff Document Template

# Handoff: [Agent Name] → [Next Agent]

## Completed
- [x] Task 1
- [x] Task 2

## Files Created/Modified
- `path/to/file.ts` - Description

## Notes for Next Agent
- Important context
- Gotchas discovered
- Decisions made

## Blockers (if any)
- Issue and suggested resolution

Dynamic Skill Loading

When task domain is unclear, use discovery:

## Discovery Process

1. Search codebase for technology markers
   - pubspec.yaml → Flutter project
   - package.json + next.config → React/Next.js
   - supabase/ folder → Supabase integration

2. Load appropriate skills based on discovery
   - Flutter detected → flutter-excellence
   - React detected → react-excellence
   - Supabase detected → supabase-mastery

3. Check for existing standards
   - .claude/standards/ → Load project conventions
   - CLAUDE.md → Load project context

Orchestration Commands

Use these patterns when spawning agents:

# Spawn single specialized agent
"Use Task tool with subagent_type=Explore to analyze codebase structure"

# Spawn parallel agents
"Launch these agents in parallel:
 - Agent A: [task] using [skill]
 - Agent B: [task] using [skill]"

# Sequential with dependency
"After Agent A completes, spawn Agent B with context from HANDOFF.md"

Anti-Patterns

AVOID:
✗ Spawning too many agents (overwhelms coordination)
✗ Parallel agents modifying same files
✗ Agents without clear task boundaries
✗ Skipping context loading phase
✗ No handoff between dependent agents

PREFER:
✓ 2-4 parallel agents max per batch
✓ Clear file ownership per agent
✓ Specific, measurable task definitions
✓ Load context before spawning
✓ Explicit handoff documents

Integration with Sprint Planning

Orchestrator works with sprint-planning skill:

1. /sprint-planning → Creates task breakdown with batches
2. /orchestrator → Reads batches, spawns agents
3. Agents execute → Mark todos complete
4. Orchestrator monitors → Triggers next batch