Missions

What is a Mission?

A mission is a group of related tasks that Polpo executes together. Missions are stored as JSON in .polpo/missions/ and can include:

Multiple tasks with dependencies
Volatile teams (temporary agents scoped to the mission)
Custom assessment criteria per task
Quality gates that block progression until thresholds are met
Cron-based scheduling for recurring execution
Deadlines tracked by SLA monitoring

Mission Lifecycle

Status	Description
`draft`	Mission created but not yet executed
`scheduled`	One-shot scheduled mission waiting for trigger time
`recurring`	Recurring scheduled mission waiting for next cron tick
`active`	Tasks are being processed
`paused`	Mission paused at a checkpoint, waiting for human review
`completed`	All tasks finished successfully
`failed`	One or more tasks failed after exhausting retries
`cancelled`	Mission was manually aborted

Creating Missions

Missions are created via CLI, TUI, or API — not by editing the config file.

CLI
TUI
HTTP API

# Generate a mission with AI
polpo mission create "Build a REST API with auth, rate limiting, and tests"

# Review the mission
polpo mission list
polpo mission show <mission-id>

# Execute it
polpo mission execute <mission-id>

/mission

The TUI mission command lets you create missions from templates or generate them with AI.

curl -X POST http://localhost:3000/api/v1/projects/my-project/missions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Build a REST API with auth"}'

curl -X POST http://localhost:3000/api/v1/projects/my-project/missions/<mission-id>/execute

Mission Task Format

Each task inside a mission uses these fields:

{
  "title": "Implement JWT middleware",
  "description": "Build Express middleware for JWT authentication.",
  "assignTo": "auth-dev",
  "dependsOn": ["Design auth schema"],
  "expectations": [
    {
      "type": "test",
      "command": "npm test -- --grep auth",
      "weight": 0.6
    },
    {
      "type": "llm_review",
      "prompt": "Verify tests cover login, logout, token refresh, and invalid tokens",
      "weight": 0.4
    }
  ]
}

Field	Type	Description
`title`	string	Short task title (must be unique within the mission; used as dependency reference)
`description`	string	Detailed instructions for the agent
`assignTo`	string	Agent name from your team. Defaults to first agent if omitted
`dependsOn`	string[]	Titles of tasks that must finish first
`expectations`	array	Assessment criteria
`maxRetries`	number	Override default retry limit
`maxDuration`	number	Timeout in ms
`retryPolicy`	object	Escalation settings (`escalateAfter`, `fallbackAgent`)

Dependencies

Tasks can depend on other tasks by referencing their titles using the dependsOn field:

{
  "tasks": [
    {
      "title": "Build database layer",
      "assignTo": "backend-dev",
      "description": "Create SQLite database with users and posts tables"
    },
    {
      "title": "Build REST API",
      "assignTo": "backend-dev",
      "description": "Create Express routes for CRUD operations",
      "dependsOn": ["Build database layer"]
    }
  ]
}

Dependencies are matched by task title within the same mission group. A task won’t start until all its dependencies reach done status. All task titles must be unique within a mission — duplicate titles are rejected at creation time.

Volatile Teams

Missions can define agents that exist only for that mission:

{
  "team": [
    {
      "name": "migration-expert",
      "role": "Database migration specialist",
      "volatile": true
    }
  ],
  "tasks": [
    {
      "title": "Migrate legacy data",
      "assignTo": "migration-expert",
      "description": "Convert old JSON files to new format"
    }
  ]
}

When the mission completes (all tasks done or failed), Polpo automatically removes volatile agents. This prevents agent sprawl when running many specialized missions.

Cleanup Modes

{
  "settings": {
    "enableVolatileTeams": true,
    "volatileCleanup": "on_complete"
  }
}

on_complete: Agents removed immediately when their mission finishes
manual: Agents persist until explicitly removed

Quality Gates

Quality gates block mission progression until preceding tasks meet a score threshold:

{
  "qualityGates": [
    {
      "name": "design-review",
      "afterTasks": ["Design API schema", "Design database schema"],
      "minScore": 4.0
    },
    {
      "name": "implementation-review",
      "afterTasks": ["Implement API endpoints", "Implement database layer"],
      "minScore": 3.5
    }
  ],
  "tasks": [
    { "title": "Design API schema", "assignTo": "architect", "description": "..." },
    { "title": "Design database schema", "assignTo": "architect", "description": "..." },
    { "title": "Implement API endpoints", "assignTo": "backend-dev", "description": "...", "dependsOn": ["Design API schema"] },
    { "title": "Implement database layer", "assignTo": "backend-dev", "description": "...", "dependsOn": ["Design database schema"] },
    { "title": "Write integration tests", "assignTo": "backend-dev", "description": "...", "dependsOn": ["Implement API endpoints", "Implement database layer"] }
  ]
}

Tasks after a quality gate won’t start until all gate tasks are done and their average assessment score meets minScore. The quality:gate hook fires when a gate is evaluated.

Scheduling

Missions can be scheduled using cron expressions. Scheduled missions use dedicated statuses (scheduled for one-shot, recurring for repeating) instead of remaining in draft:

One-shot:   draft → scheduled → active → completed (success) / scheduled (failure, auto-retry)
Recurring:  draft → recurring  → active → recurring (always returns for next tick)

Use the create_schedule orchestrator tool to schedule a mission:

# One-shot: runs once at 2 AM
create_schedule(missionId, "0 2 * * *")

# Recurring: runs every day at 2 AM
create_schedule(missionId, "0 2 * * *", recurring=true)

Field	Type	Description
`schedule`	string	Cron expression (e.g., `"0 2 * * *"` for daily at 2 AM) or ISO timestamp for one-shot
`status`	`"scheduled"` or `"recurring"`	Set automatically by `create_schedule` — determines one-shot vs recurring behavior

The mission status itself encodes whether it’s one-shot or recurring. There is no separate recurring boolean field. A recurring mission never reaches completed or failed — it always returns to recurring after each execution cycle.

Scheduling requires "enableScheduler": true in the top-level config (enabled by default when any mission has a schedule). The schedule:trigger hook fires when a scheduled mission is triggered.

Execution

Missions can be executed via:

CLI
TUI
HTTP API
Web UI

polpo mission execute <mission-id>
polpo run    # executes all pending missions

/mission

The TUI mission command lets you create missions from templates or generate them with AI.

curl -X POST http://localhost:3000/api/v1/projects/my-project/missions/<mission-id>/execute

Mission Reports

When a mission completes, Polpo generates a MissionReport with:

interface MissionReport {
  missionId: string;
  group: string;
  allPassed: boolean;
  totalDuration: number;        // sum of all task durations (ms)
  tasks: {
    title: string;
    status: "done" | "failed";
    duration: number;
    score?: number;             // G-Eval score (1-5)
    filesCreated: string[];
    filesEdited: string[];
  }[];
  filesCreated: string[];       // aggregated across all tasks
  filesEdited: string[];
  avgScore?: number;            // average assessment score
}

Mission completion triggers the mission:completed event with the full report.

AI-Generated Missions

Polpo can generate missions from natural language prompts:

polpo mission create "Build a REST API with authentication, rate limiting, and tests"

Or interactively in the TUI:

/mission
> Generate with AI
> Prompt: Build a REST API with authentication, rate limiting, and tests

The AI generates a mission with appropriate agents, tasks, dependencies, and expectations. You can then review, edit, and execute it.

Editing Running Missions

The /edit-mission TUI command lets you modify active missions:

Add tasks to a running mission
Remove pending tasks
Reassign tasks to different agents
Retry specific failed tasks

Core

Agent Capabilities

Sharing & Registry

Mission Execution

Human-in-the-Loop

Quality & Recovery

Security

What is a Mission?

Mission Lifecycle

Creating Missions

Mission Task Format

Dependencies

Volatile Teams

Cleanup Modes

Quality Gates

Scheduling

Execution

Mission Reports

AI-Generated Missions

Editing Running Missions

Core

Agent Capabilities

Sharing & Registry

Mission Execution

Human-in-the-Loop

Quality & Recovery

Security

​What is a Mission?

​Mission Lifecycle

​Creating Missions

​Mission Task Format

​Dependencies

​Volatile Teams

​Cleanup Modes

​Quality Gates

​Scheduling

​Execution

​Mission Reports

​AI-Generated Missions

​Editing Running Missions

What is a Mission?

Mission Lifecycle

Creating Missions

Mission Task Format

Dependencies

Volatile Teams

Cleanup Modes

Quality Gates

Scheduling

Execution

Mission Reports

AI-Generated Missions

Editing Running Missions