--- 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 ` - 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`