Skip to main content
A mission groups related tasks into an orchestrated workflow. Missions handle dependency resolution, quality gates, checkpoints, and scheduling so you can express multi-step agent work as a single declarative object.

​
Mission fields

FieldTypeDescription
idstringAuto-generated unique identifier
namestringHuman-readable mission name
dataobjectArbitrary JSON payload available to all tasks
promptstringHigh-level instruction for the mission
statusMissionStatusCurrent lifecycle state
deadlinestringISO 8601 timestamp — hard deadline for the entire mission
schedulestringCron expression or ISO timestamp (see Scheduling)
endDatestringISO 8601 timestamp — stop recurring missions after this date
qualityThresholdnumberMinimum score (1-5) for tasks to pass assessment
executionCountnumberNumber of times this mission has run

​
Lifecycle

Missions follow a strict status state machine: 
draft → scheduled    → active → completed
     → recurring     → active → paused → active
                              → completed
                              → failed
                              → cancelled
StatusMeaning
draftCreated but not yet started
scheduledWill fire once at a specific time
recurringWill fire on every cron tick
activeCurrently executing tasks
pausedHalted at a checkpoint or manually
completedAll tasks finished successfully
failedOne or more tasks failed after retries
cancelledManually cancelled

​
Example mission

{
  "name": "weekly-report",
  "prompt": "Generate the weekly engineering report",
  "data": { "team": "backend", "week": 12 },
  "schedule": "0 9 * * 1",
  "endDate": "2026-12-31T00:00:00Z",
  "qualityThreshold": 3.5,
  "tasks": [
    {
      "title": "Gather PR data",
      "assignTo": "data-collector",
      "dependsOn": []
    },
    {
      "title": "Write summary",
      "assignTo": "writer",
      "dependsOn": ["Gather PR data"]
    },
    {
      "title": "Review and publish",
      "assignTo": "reviewer",
      "dependsOn": ["Write summary"]
    }
  ],
  "team": {
    "name": "report-crew",
    "volatile": true,
    "agents": [
      { "name": "data-collector", "role": "Fetch metrics from GitHub" },
      { "name": "writer", "role": "Draft the report" },
      { "name": "reviewer", "role": "Review for accuracy" }
    ]
  },
  "qualityGates": [
    {
      "afterTasks": ["Write summary"],
      "blocksTasks": ["Review and publish"],
      "minScore": 4.0,
      "requireAllPassed": true,
      "notifyChannels": ["slack:eng-reports"]
    }
  ],
  "checkpoints": [
    {
      "afterTasks": ["Review and publish"],
      "blocksTasks": [],
      "message": "Approve the final report before distribution"
    }
  ]
}

​
Volatile teams

Missions can define their own short-lived team of agents. Set volatile: true on the team definition and the agents are created when the mission starts and automatically cleaned up when it completes. This is useful for one-off or recurring workflows that need purpose-built agents without polluting your project’s permanent agent roster.
Volatile agents inherit the project’s BYOK credentials and sandbox configuration. They do not persist memory between mission runs.

​
Quality gates

A quality gate blocks downstream tasks until upstream tasks meet a minimum assessment score.
FieldTypeDescription
afterTasksstring[]Tasks that must be assessed before the gate
blocksTasksstring[]Tasks held until the gate passes
minScorenumberMinimum average score (1-5) required
requireAllPassedbooleanIf true, every task in afterTasks must individually pass
notifyChannelsstring[]Channels to notify on gate failure
If a quality gate fails, blocked tasks will not execute. The mission will pause until the upstream tasks are fixed and reassessed, or the mission is cancelled.

​
Checkpoints

A checkpoint pauses the mission for human review.
FieldTypeDescription
afterTasksstring[]Tasks that trigger the checkpoint
blocksTasksstring[]Tasks held until a human approves
messagestringMessage shown to the reviewer
The mission moves to paused status. Execution resumes when a human approves the checkpoint via the dashboard or API.

​
Delays

A delay inserts a timed wait between tasks. Durations use ISO 8601 format.
FieldTypeDescription
afterTasksstring[]Tasks that trigger the delay
blocksTasksstring[]Tasks held until the delay elapses
durationstringISO 8601 duration (PT2H, PT30M, P1D)
DurationMeaning
PT30M30 minutes
PT2H2 hours
P1D1 day
PT1H30M1 hour 30 minutes
P7D7 days

​
Mission report

When a mission completes, a MissionReport is generated: 
{
  "allPassed": true,
  "totalDuration": 14230,
  "avgScore": 4.2,
  "results": [
    {
      "task": "Gather PR data",
      "status": "done",
      "score": 4.5,
      "duration": 3200
    },
    {
      "task": "Write summary",
      "status": "done",
      "score": 3.8,
      "duration": 7800
    },
    {
      "task": "Review and publish",
      "status": "done",
      "score": 4.3,
      "duration": 3230
    }
  ]
}

​
CLI

polpo mission create --file mission.json