Skip to main content
Checkpoints are planned stopping points inside a mission. When a checkpoint is reached, the mission pauses, sends notifications, and waits for you to explicitly resume it. Nothing happens automatically — the mission sits in paused status until you decide to continue. This is the human-in-the-loop mechanism for reviewing intermediate results before proceeding with later tasks.

​
Checkpoints vs Approval Gates vs Quality Gates

CheckpointsApproval GatesQuality Gates
What it doesPauses the mission at a defined pointPauses a task and asks approve/rejectBlocks tasks until a score threshold is met
ScopeMission-levelTask-levelMission-level (group of tasks)
TriggerAlways — when afterTasks completeConditional — when a hook fires and condition matchesAutomatic — when afterTasks complete
ResolutionManual resume (no decision needed)Approve, reject, or revise (decision required)Automatic — passes or fails based on scores
Mission statuspausedStays active (task is awaiting_approval)Stays active (tasks are blocked)
Use case”Stop here so I can review before continuing""Should this task proceed?""Is the quality good enough to continue?”

​
Quick Start

Add a checkpoints array to your mission: 
{
  "tasks": [
    { "title": "Analyze codebase", "assignTo": "analyst" },
    { "title": "Apply refactoring", "assignTo": "coder", "dependsOn": ["Analyze codebase"] },
    { "title": "Run tests", "assignTo": "tester", "dependsOn": ["Apply refactoring"] }
  ],
  "checkpoints": [
    {
      "name": "review-analysis",
      "afterTasks": ["Analyze codebase"],
      "blocksTasks": ["Apply refactoring"],
      "notifyChannels": ["slack-alerts"],
      "message": "Analysis complete — review findings before applying changes"
    }
  ]
}
When Analyze codebase completes, the mission pauses. You get a Slack notification. You review the analysis output. When you’re satisfied, you resume the checkpoint and Apply refactoring starts.

​
Checkpoint Fields

FieldTypeRequiredDescription
namestringYesUnique name within the mission (used in events and API)
afterTasksstring[]YesTasks that must complete before the checkpoint triggers
blocksTasksstring[]YesTasks that are blocked until the checkpoint is resumed
notifyChannelsstring[]NoNotification channels to alert when the checkpoint is reached
messagestringNoMessage included in the notification

​
Resuming a Checkpoint

When a checkpoint is active, the mission shows status paused. Resume it through any interface: 
# List active checkpoints
curl http://localhost:3000/api/v1/projects/my-project/missions/checkpoints

# Resume a checkpoint
curl -X POST http://localhost:3000/api/v1/projects/my-project/missions/{missionId}/checkpoints/review-analysis/resume
After resume, the mission transitions back to active and the blocked tasks become eligible for execution.

​
Mission Status Lifecycle

draft → active → paused → active → paused → active → completed
                    ↑                  ↑
              checkpoint          checkpoint
               reached              reached
A mission can hit multiple checkpoints. Each one pauses the mission, and each resume returns it to active. The mission only reaches completed when all tasks are done (and all checkpoints have been passed).

​
Examples

​
Code review before deployment

{
  "tasks": [
    { "title": "Build artifacts", "assignTo": "build-agent" },
    { "title": "Run test suite", "assignTo": "test-agent", "dependsOn": ["Build artifacts"] },
    { "title": "Deploy to staging", "assignTo": "deploy-agent", "dependsOn": ["Run test suite"] },
    { "title": "Deploy to production", "assignTo": "deploy-agent", "dependsOn": ["Deploy to staging"] }
  ],
  "checkpoints": [
    {
      "name": "pre-staging",
      "afterTasks": ["Run test suite"],
      "blocksTasks": ["Deploy to staging"],
      "notifyChannels": ["slack-deploys"],
      "message": "Tests passed. Review results before deploying to staging."
    },
    {
      "name": "pre-production",
      "afterTasks": ["Deploy to staging"],
      "blocksTasks": ["Deploy to production"],
      "notifyChannels": ["slack-deploys", "email-leads"],
      "message": "Staging deploy complete. Verify staging before production deploy."
    }
  ]
}
Two checkpoints: one before staging, one before production. Each requires explicit human approval to proceed.

​
Analysis review before implementation

{
  "tasks": [
    { "title": "Analyze security vulnerabilities", "assignTo": "security-analyst" },
    { "title": "Prioritize findings", "assignTo": "security-analyst", "dependsOn": ["Analyze security vulnerabilities"] },
    { "title": "Fix critical vulnerabilities", "assignTo": "security-fixer", "dependsOn": ["Prioritize findings"] },
    { "title": "Verify fixes", "assignTo": "security-analyst", "dependsOn": ["Fix critical vulnerabilities"] }
  ],
  "checkpoints": [
    {
      "name": "review-priorities",
      "afterTasks": ["Prioritize findings"],
      "blocksTasks": ["Fix critical vulnerabilities"],
      "message": "Review the prioritized vulnerability list before fixing begins"
    }
  ]
}

​
Combining with quality gates

Checkpoints and quality gates can coexist in the same mission. Quality gates are automatic (they check scores), checkpoints are manual (they always pause): 
{
  "tasks": [
    { "title": "Write implementation", "assignTo": "coder" },
    { "title": "Write tests", "assignTo": "tester", "dependsOn": ["Write implementation"] },
    { "title": "Final review", "assignTo": "reviewer", "dependsOn": ["Write tests"] }
  ],
  "qualityGates": [
    {
      "name": "impl-quality",
      "afterTasks": ["Write implementation"],
      "blocksTasks": ["Write tests"],
      "minScore": 3.5
    }
  ],
  "checkpoints": [
    {
      "name": "manual-review",
      "afterTasks": ["Write tests"],
      "blocksTasks": ["Final review"],
      "notifyChannels": ["slack-team"],
      "message": "Implementation and tests complete — review before final sign-off"
    }
  ]
}
Here, Write tests is blocked by a quality gate (automatic — checks implementation score). Final review is blocked by a checkpoint (manual — always pauses).

​
Notifications

If notifyChannels is set on a checkpoint, Polpo automatically registers notification rules for checkpoint:reached and checkpoint:resumed events. The notification includes the checkpoint name, message, and the mission/task context. See Notifications for channel configuration.

​
Events

EventWhenPayload
checkpoint:reachedA checkpoint is triggered (all afterTasks done)missionId, group, checkpointName, message, afterTasks, blocksTasks, reachedAt
checkpoint:resumedA checkpoint is manually resumedmissionId, group, checkpointName

​
Checkpoints in Playbooks

Checkpoints work in Playbooks — use {{placeholders}} in task titles referenced by afterTasks and blocksTasks: 
{
  "checkpoints": [
    {
      "name": "review-{{module}}",
      "afterTasks": ["Analyze {{module}}"],
      "blocksTasks": ["Apply fixes to {{module}}"],
      "message": "Review analysis of {{module}} before applying fixes"
    }
  ]
}