ap-tasks

ap-tasks

When to use

• Several agents (or you + an agent) must share a list of work units without stepping on each other.
• You want "done" to be provable, not self-reported.
• You are handing a task to an unclaimed queue that any session on the board can pick up.

Create tasks

task_create({
  "title": "Migrate auth module to new API",
  "description": "Files under src/auth/. Keep test coverage. See plan.md section 3.",
  "owner": "self",
  "verify": { "command": "pnpm", "args": ["test", "auth"], "cwd": "/repo" }
})

title is required; description is for whoever claims it. Leave owner absent to make the task claimable — anyone on the board can pick it up. boardId defaults to your session's lineage board (tree:<root>) or the workspace board (ws:<slug>). The optional verify gate (a shell command, exit 0 = pass) makes done gated.

The claim cycle: read → claim → work → update

Every task carries a rev (revision number). task_claim is compare-and-swap: it succeeds only if the task is pending, has no owner, and the rev you pass matches what you last read.

// 1. List open tasks
task_list({ "boardId": "ws:studio" })

// 2. Claim before touching anything
task_claim({ "taskId": "task_7", "rev": 3 })
//    → ok, you own it, status flips to in_progress

// 3. Do the work, then close it
task_update({ "taskId": "task_7", "rev": 4, "status": "done", "note": "Migrated, 12 tests green" })

// 4. Dropping without finishing
task_update({ "taskId": "task_7", "rev": 5, "owner": null, "status": "pending" })

ALWAYS claim before working and update when done. Unclaimed work is invisible to the rest of the board; work you never close blocks everyone downstream.

Conflicts

On a lost race, task_claim returns { "conflict": true, "current": {...} } — someone moved first. Re-read current, then either pick a different task or retry the claim with the fresh rev. Never force: there is no override for a rev mismatch, and silently overwriting another agent's claim corrupts the board.