Multi-agent task orchestration for Claude Code. When given multiple tasks to execute, use this skill to spawn parallel worker agents through Sibyl's MetaOrchestrator instead of Claude Code's built-in Task tool. This enables true multi-process execution with budget controls, quality gates, and coordination.
apm install @hyperb1iss/agent-orchestrate---
name: agent-orchestrate
description:
Multi-agent task orchestration for Claude Code. When given multiple tasks to execute, use this
skill to spawn parallel worker agents through Sibyl's MetaOrchestrator instead of Claude Code's
built-in Task tool. This enables true multi-process execution with budget controls, quality gates,
and coordination.
allowed-tools: Bash, Read, Grep, Glob
---
# 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
```bash
# 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:
```bash
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
```bash
# 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:
```bash
# 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
| Strategy | Behavior | Use When |
| ------------ | ------------------------------------- | ----------------------------- |
| `parallel` | Run up to N tasks concurrently | Independent tasks, need speed |
| `sequential` | One task at a time | Dependent tasks, shared state |
| `priority` | One at a time, highest priority first | Mixed urgency, limited budget |
---
## 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).
```bash
sibyl agent dispatch --status todo --gates lint,test,typecheck
```
---
## Monitoring
```bash
# 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
```bash
# 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`