Orchestration Patterns

This guide covers the task orchestration patterns available in Mission Control, from simple manual assignment to fully automated multi-agent workflows.

Task Lifecycle

Every task in Mission Control follows this status flow:

inbox ──► assigned ──► in_progress ──► review ──► done
  │          │             │              │
  │          │             │              └──► rejected ──► assigned (retry)
  │          │             │
  │          │             └──► failed (max retries or timeout)
  │          │
  │          └──► cancelled
  │
  └──► assigned (triaged by human or auto-dispatch)

Key transitions:

inbox → assigned: Human triages or auto-dispatch picks it up
assigned → in_progress: Agent claims via queue poll or auto-dispatch sends it
in_progress → review: Agent completes work, awaits quality check
review → done: Aegis approves the work
review → assigned: Aegis rejects, task is requeued with feedback

Pattern 1: Manual Assignment

The simplest pattern. A human creates a task and assigns it to a specific agent.

# Create and assign in one step
curl -X POST "$MC_URL/api/tasks" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix login page CSS",
    "description": "The login button overlaps the form on mobile viewports.",
    "priority": "high",
    "assigned_to": "scout"
  }'

The agent picks it up on the next queue poll:

curl "$MC_URL/api/tasks/queue?agent=scout" \
  -H "Authorization: Bearer $MC_API_KEY"

When to use: Small teams, well-known agent capabilities, human-driven task triage.

Pattern 2: Queue-Based Dispatch

Agents poll the queue and MC assigns the highest-priority available task. No human triage needed.

Setup

Create tasks in inbox status (no assigned_to):

curl -X POST "$MC_URL/api/tasks" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Update API documentation",
    "priority": "medium"
  }'

Agents poll the queue. MC atomically claims the best task:

# Agent "scout" asks for work
curl "$MC_URL/api/tasks/queue?agent=scout" \
  -H "Authorization: Bearer $MC_API_KEY"

# Agent "iris" also asks — gets a different task (no race condition)
curl "$MC_URL/api/tasks/queue?agent=iris" \
  -H "Authorization: Bearer $MC_API_KEY"

Priority Ordering

Tasks are assigned in this order:

Priority: critical > high > medium > low
Due date: Earliest due date first (null = last)
Created at: Oldest first (FIFO within same priority)

Capacity Control

Each agent can set max_capacity to limit concurrent tasks:

# Agent can handle 3 tasks at once
curl "$MC_URL/api/tasks/queue?agent=scout&max_capacity=3" \
  -H "Authorization: Bearer $MC_API_KEY"

If the agent already has max_capacity tasks in in_progress, the response returns "reason": "at_capacity" with no task.

When to use: Multiple agents with overlapping capabilities, want automatic load balancing.

Pattern 3: Auto-Dispatch (Gateway Required)

The scheduler automatically dispatches assigned tasks to agents through the OpenClaw gateway. This is the fully hands-off mode.

How It Works

Tasks are created with assigned_to set
The scheduler's dispatchAssignedTasks job runs periodically
For each task, MC:
- Marks it in_progress
- Classifies the task complexity to select a model
- Sends the task prompt to the agent via the gateway
- Parses the response and stores the resolution
- Moves the task to review status

Model Routing

MC automatically selects a model based on task content:

Tier	Model	Signals
Complex	Opus	debug, diagnose, architect, security audit, incident, refactor, migration
Routine	Haiku	status check, format, rename, ping, summarize, translate, simple, minor
Default	Agent's configured model	Everything else

Critical priority tasks always get Opus. Low priority with routine signals get Haiku.

Override per-agent by setting config.dispatchModel:

curl -X PUT "$MC_URL/api/agents" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "config": {"dispatchModel": "9router/cc/claude-opus-4-6"}}'

Retry Handling

Failed dispatches increment dispatch_attempts and revert to assigned
After 5 failed attempts, task moves to failed
Each failure is logged as a comment on the task

When to use: Fully autonomous operation with an OpenClaw gateway. Best for production agent fleets.

Pattern 4: Quality Review (Aegis)

Aegis is MC's built-in quality gate. When a task reaches review status, the scheduler sends it to the Aegis reviewer agent for sign-off.

Flow

in_progress ──► review ──► Aegis reviews ──► APPROVED ──► done
                                          └─► REJECTED ──► assigned (with feedback)

How Aegis Reviews

Scheduler's runAegisReviews job picks up tasks in review status
Builds a review prompt with the task description and agent's resolution
Sends to the Aegis agent (configurable via MC_COORDINATOR_AGENT)
Parses the verdict:
- VERDICT: APPROVED → task moves to done
- VERDICT: REJECTED → feedback is attached as a comment, task reverts to assigned
Rejected tasks are re-dispatched with the feedback included in the prompt

Retry Limits

Up to 3 Aegis review cycles per task
After 3 rejections, task moves to failed with accumulated feedback
All review results are stored in the quality_reviews table

Setting Up Aegis

Aegis is just a regular agent with a reviewer SOUL. Create it:

# Register the Aegis agent
curl -X POST "$MC_URL/api/agents/register" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "aegis", "role": "reviewer"}'

# Set its SOUL
curl -X PUT "$MC_URL/api/agents/1/soul" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_name": "reviewer"}'

When to use: When you want automated quality checks before tasks are marked complete.

Pattern 5: Recurring Tasks (Cron)

Schedule tasks to be created automatically on a recurring basis using natural language or cron expressions.

CLI

node scripts/mc-cli.cjs cron create --body '{
  "name": "daily-standup-report",
  "schedule": "0 9 * * 1-5",
  "task_template": {
    "title": "Generate daily standup report",
    "description": "Summarize all completed tasks from the past 24 hours.",
    "priority": "medium",
    "assigned_to": "iris"
  }
}'

API

curl -X POST "$MC_URL/api/cron" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-security-scan",
    "schedule": "0 2 * * 0",
    "task_template": {
      "title": "Weekly security audit",
      "priority": "high",
      "assigned_to": "aegis"
    }
  }'

The scheduler spawns dated child tasks from the template on each trigger. Manage cron jobs with pause, resume, and remove actions.

When to use: Reports, health checks, periodic audits, maintenance tasks.

Pattern 6: Multi-Agent Handoff

Agent A completes a task, then creates a follow-up task assigned to Agent B. This chains agents into a pipeline.

Example: Research → Implement → Review

# Step 1: Research task for iris
curl -X POST "$MC_URL/api/tasks" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Research caching strategies for API layer",
    "priority": "high",
    "assigned_to": "iris"
  }'

When iris completes the research, create the implementation task:

# Step 2: Implementation task for scout (after iris finishes)
curl -X POST "$MC_URL/api/tasks" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement Redis caching for /api/products",
    "description": "Based on research in TASK-1: Use cache-aside pattern with 5min TTL...",
    "priority": "high",
    "assigned_to": "scout"
  }'

After scout finishes, Aegis reviews automatically (if auto-dispatch is active), or you create a review task:

# Step 3: Review task for aegis
curl -X POST "$MC_URL/api/tasks" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review caching implementation in TASK-2",
    "priority": "high",
    "assigned_to": "aegis"
  }'

When to use: Complex workflows where different agents have different specializations.

Pattern 7: Stale Task Recovery

MC automatically recovers from stuck agents. The requeueStaleTasks scheduler job:

Finds tasks stuck in in_progress for 10+ minutes with an offline agent
Reverts them to assigned with a comment explaining the stall
After 5 stale requeues, moves the task to failed

This happens automatically — no configuration needed.

Combining Patterns

In practice, you'll combine these patterns. A typical production setup:

Cron creates recurring tasks (Pattern 5)
Queue-based dispatch distributes tasks to available agents (Pattern 2)
Model routing picks the right model per task (Pattern 3)
Aegis reviews all completed work (Pattern 4)
Stale recovery handles agent failures (Pattern 7)

 Cron ──► inbox ──► Queue assigns ──► Agent works ──► Aegis reviews ──► done
                                          │                  │
                                          └── timeout ───────┘── requeue

Event Streaming

Monitor orchestration in real time with SSE:

# Watch all task and agent events
node scripts/mc-cli.cjs events watch --types task,agent --json

Or via API:

curl -N "$MC_URL/api/events" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Accept: text/event-stream"

Events include: task.created, task.updated, task.completed, agent.created, agent.status_changed, and more.

Reference

Quickstart — 5-minute first agent tutorial
Agent Setup — Registration, SOUL, configuration
CLI Reference — Full CLI command list
CLI Integration — Direct connections without a gateway

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Orchestration Patterns

Task Lifecycle

Pattern 1: Manual Assignment

Pattern 2: Queue-Based Dispatch

Setup

Priority Ordering

Capacity Control

Pattern 3: Auto-Dispatch (Gateway Required)

How It Works

Model Routing

Retry Handling

Pattern 4: Quality Review (Aegis)

Flow

How Aegis Reviews

Retry Limits

Setting Up Aegis

Pattern 5: Recurring Tasks (Cron)

CLI

API

Pattern 6: Multi-Agent Handoff

Example: Research → Implement → Review

Pattern 7: Stale Task Recovery

Combining Patterns

Event Streaming

Reference

FilesExpand file tree

orchestration.md

Latest commit

History

orchestration.md

File metadata and controls

Orchestration Patterns

Task Lifecycle

Pattern 1: Manual Assignment

Pattern 2: Queue-Based Dispatch

Setup

Priority Ordering

Capacity Control

Pattern 3: Auto-Dispatch (Gateway Required)

How It Works

Model Routing

Retry Handling

Pattern 4: Quality Review (Aegis)

Flow

How Aegis Reviews

Retry Limits

Setting Up Aegis

Pattern 5: Recurring Tasks (Cron)

CLI

API

Pattern 6: Multi-Agent Handoff

Example: Research → Implement → Review

Pattern 7: Stale Task Recovery

Combining Patterns

Event Streaming

Reference