> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Missions

> Run dependency-aware groups of tasks

A mission stores a declarative task graph and executes it as one workflow. It supports dependencies, temporary agents, quality gates, human checkpoints, timed delays, notifications, deadlines, and schedules.

## Storage model

A persisted `Mission` has `id`, `name`, `data`, `status`, and timestamps. `data` is a JSON string containing the mission document. Optional top-level persisted fields are `prompt`, `deadline`, `schedule`, `endDate`, `qualityThreshold`, `notifications`, `executionCount`, and `user`.

The mission document inside `data` has this shape:

```json theme={null}
{
  "tasks": [
    {
      "title": "Gather pull request data",
      "description": "Collect merged pull requests for the current week.",
      "assignTo": "data-collector"
    },
    {
      "title": "Write the report",
      "description": "Summarize the collected engineering activity.",
      "assignTo": "writer",
      "dependsOn": ["Gather pull request data"],
      "expectations": [
        {"type": "file_exists", "paths": ["weekly-report.md"]}
      ]
    }
  ],
  "team": [
    {"name": "data-collector", "role": "Collects engineering metrics"},
    {"name": "writer", "role": "Writes concise internal reports"}
  ],
  "qualityGates": [
    {
      "name": "report-quality",
      "afterTasks": ["Write the report"],
      "blocksTasks": ["Publish the report"],
      "minScore": 4,
      "requireAllPassed": true
    }
  ],
  "checkpoints": [],
  "delays": []
}
```

Task titles must be unique. `dependsOn`, gate, checkpoint, and delay references use those titles. Dependencies must exist and cannot contain cycles.

## Create and execute

The SDK and REST API require `data` to be serialized:

```typescript theme={null}
const document = {
  tasks: [
    {
      title: "Prepare release notes",
      description: "Summarize changes since the previous release.",
      assignTo: "writer"
    }
  ]
};

const mission = await client.createMission({
  name: "release-notes",
  prompt: "Prepare release documentation.",
  data: JSON.stringify(document)
});

await client.executeMission(mission.id);
```

The canonical execute route is `POST /v1/missions/{missionId}/execute`. Cloud also exposes its run alias where supported.

Local `.polpo/missions/*.json` files may keep `data` as an object; `polpo deploy` serializes it before sending the API request. Put `tasks`, `team`, and gates inside `data`, not beside it.

## Lifecycle

Mission status is one of `draft`, `scheduled`, `recurring`, `active`, `paused`, `completed`, `failed`, or `cancelled`.

* Direct execution starts from `draft`, `scheduled`, `recurring`, `failed`, or `cancelled`.
* A checkpoint pauses execution until explicitly resumed.
* A recurring run returns to `recurring` after success or failure.
* A scheduled one-shot returns to `scheduled` after failure so the scheduler can retry it; after success it remains completed.

## Temporary team

`data.team` is an array of agent configs. At mission start, Polpo registers each member as a volatile agent tied to that mission run. With the default `volatileCleanup: "on_complete"`, those agents are removed after the group reaches a terminal state. Set project `enableVolatileTeams` to false to disable registration, or `volatileCleanup: "manual"` to retain them.

Temporary agents receive `volatile` and `missionGroup` internally. Do not put a `{ name, volatile, agents }` wrapper around `data.team`.

## Gates, checkpoints, and delays

All three constructs require a unique `name`, non-empty `afterTasks`, and non-empty `blocksTasks`.

| Construct    | Behavior                                                                     | Additional fields                                             |
| ------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Quality gate | Evaluates completed upstream task quality before unblocking downstream tasks | `minScore`, `requireAllPassed`, `condition`, `notifyChannels` |
| Checkpoint   | Unconditionally pauses until explicitly resumed                              | `message`, `notifyChannels`                                   |
| Delay        | Starts after upstream tasks are terminal and resumes automatically           | ISO 8601 `duration`, `message`, `notifyChannels`              |

Use durations such as `PT30M`, `PT2H`, or `P1D`.

## Report

A completed `MissionReport` contains `missionId`, execution `group`, `allPassed`, `totalDuration`, a `tasks` array, aggregated `filesCreated`, `filesEdited`, and optional outcomes and `avgScore`. Each task report contains title, `done` or `failed` status, duration, optional score, file lists, and outcomes.

See the [Missions API](/agent-api/missions) for editing mission tasks, gates, checkpoints, delays, team members, and notifications.