Agent Orchestrate

Agent Orchestration

CRITICAL: This skill teaches you how to dispatch tasks to multiple worker agents.

When you're asked to work on multiple tasks, or to "dispatch agents", "parallelize work", or "orchestrate" - use Sibyl's MetaOrchestrator via the CLI, NOT Claude Code's built-in Task tool.

Why This Matters

Claude Code's built-in Task tool spawns inline subagents within YOUR process. This is useful for research, but NOT for parallel task execution because:

• Subagents run sequentially, not in parallel
• No budget controls or quality gates
• No coordination between workers
• Context bloat as results accumulate

Sibyl's MetaOrchestrator spawns separate Claude processes that:

• Run truly in parallel (up to N concurrent)
• Have isolated worktrees (no git conflicts)
• Go through implement → review → rework loops
• Track budget and can pause when limits hit
• Report progress through the message bus

Quick Start

# One-liner: dispatch all todo tasks with 3 parallel agents
sibyl agent dispatch --status todo --strategy parallel --max 3

# With budget limit
sibyl agent dispatch --status todo --budget 25.00 --gates lint,test

# Specific tasks
sibyl agent dispatch task_abc123 task_def456 --strategy parallel

The Dispatch Command

sibyl agent dispatch is the high-level command that handles everything:

sibyl agent dispatch [TASK_IDS...] [OPTIONS]

Options:
  --status, -s    Filter tasks by status (todo, doing, blocked)
  --priority      Filter tasks by priority
  --strategy      Execution strategy: parallel, sequential, priority
  --max, -m       Max concurrent agents (default: 3)
  --budget, -b    Budget limit in USD
  --gates, -g     Quality gates (comma-separated: lint,test,typecheck)
  --dry-run       Show what would be dispatched
  --project, -p   Project ID (auto-resolves from cwd)

Examples

# Dispatch all todo tasks
sibyl agent dispatch --status todo

# Dispatch high-priority tasks only
sibyl agent dispatch --status todo --priority high,critical

# Parallel with 4 workers and $50 budget
sibyl agent dispatch --status todo --strategy parallel --max 4 --budget 50.00

# Sequential with quality gates
sibyl agent dispatch task_abc --strategy sequential --gates lint,test,typecheck

# Dry run first
sibyl agent dispatch --status todo --dry-run

Lower-Level Commands

For fine-grained control, use the sibyl agent orchestrate subcommands:

# Initialize orchestrator
sibyl agent orchestrate init

# Queue specific tasks
sibyl agent orchestrate queue task_abc123 task_def456

# Set strategy
sibyl agent orchestrate strategy parallel --max 4

# Set budget
sibyl agent orchestrate budget 50.00 --alert 0.8

# Start processing
sibyl agent orchestrate start --gates lint,test

# Monitor progress
sibyl agent orchestrate status

# Pause/resume
sibyl agent orchestrate pause
sibyl agent orchestrate resume

Strategies

Quality Gates

Quality gates run after each implementation cycle:

• lint - Run linter (ruff, eslint, etc.)
• test - Run test suite
• typecheck - Run type checker (pyright, tsc)

If any gate fails, the worker enters a rework cycle (up to 3 attempts).

sibyl agent dispatch --status todo --gates lint,test,typecheck

Monitoring

# Check orchestration status
sibyl agent orchestrate status

# Output shows:
#   - Queue size and active workers
#   - Completed/failed counts
#   - Budget utilization
#   - Rework cycles

Workflow: Orchestrating a Sprint

# 1. See what's available
sibyl task list --status todo

# 2. Preview what would be dispatched
sibyl agent dispatch --status todo --dry-run

# 3. Launch with controls
sibyl agent dispatch --status todo \
  --strategy parallel \
  --max 3 \
  --budget 30.00 \
  --gates lint,test

# 4. Monitor progress
sibyl agent orchestrate status

# 5. Pause if needed
sibyl agent orchestrate pause

When to Use What

Use Sibyl orchestration (sibyl agent dispatch) when:

• You need multiple implementation tasks done in parallel
• Tasks are independent and can run concurrently
• You want budget controls and quality gates
• You're orchestrating a sprint or batch of work

Use Claude Code's built-in Task tool when:

• Researching or exploring code (reading files, searching)
• Asking specialized agents questions
• Delegating subtasks within a single implementation

Key insight: These are complementary, not exclusive!

Worker agents spawned by Sibyl orchestration are encouraged to use their built-in Task tool for research, exploration, and subtask delegation. The hierarchy is:

MetaOrchestrator (Sibyl)
├── Spawns parallel worker agents for independent TASKS
│
Worker Agent 1                    Worker Agent 2
├── Uses Task tool for research   ├── Uses Task tool for research
├── Spawns subagents as needed    ├── Spawns subagents as needed
└── Implements assigned task      └── Implements assigned task

The rule is simple:

• Cross-task parallelism → Sibyl orchestration (separate processes, isolated worktrees)
• Within-task work → Built-in Task tool (subagents, research, exploration)

Architecture

MetaOrchestrator (Tier 1)
├── Manages sprint/project-level coordination
├── Maintains task queue
├── Spawns TaskOrchestrators per strategy
└── Tracks budget and metrics

TaskOrchestrator (Tier 2)
├── Manages single task lifecycle
├── Runs implement → review → rework loop
├── Enforces quality gates
└── Reports to MetaOrchestrator

Worker Agent (Tier 3)
├── Actual Claude process
├── Has isolated git worktree
├── Implements the code
└── Communicates via message bus

Troubleshooting

"No tasks to dispatch"

• Ensure you have tasks with matching status/priority
• Check project context: sibyl context
• Try --dry-run to see what matches

"No orchestrator or project specified"

• Link your directory to a project: sibyl project link <project_id>
• Or specify explicitly: --project proj_abc123

Budget exhausted

• Check status: sibyl agent orchestrate status
• Increase budget: sibyl agent orchestrate budget 100.00
• Resume: sibyl agent orchestrate resume