Clear a worklist

To see the top Task your Role may take, run next:

$ npx startup-builder next

{"task": {"$id": "https://api.sb/captionyard.com/tasks/task_1","title": "Caption lesson 4 for order_12","role": "delivery-manager","due": "2026-10-23T17:00:00Z","brief": "A caption file for lesson 4 that a deaf student follows without the audio.","inputs": { "order": "order_12", "video": "https://captionyard.com/files/lesson-4.mp4" },"checks": [{ "id": "captions-synced", "passes": "Every cue starts within 100 ms of its speech." },{ "id": "glossary-applied", "passes": "Every course term matches the Customer's glossary." }],"skills": ["caption-style"],"context": ["order_12", "glossary_3"],"budget": { "steps": 40, "spend": { "amount": 0.6, "currency": "USD" } }}}

A Task is self-contained: what done means, its inputs, each check's definition, the skill packages to load, the ids to fetch, and its budget.

Tasks come from Workflows waiting on a Worker, failing checks, and missing fields. They rank by due time, then by the Key Result each one moves.

To take it, claim it:

$ npx startup-builder claim task_1

The claim is a 15-minute lease, renewed while you work. Only the lease holder can finish the Task, so two Workers never do the same work.

Do the work. Every call you make records the Task as its reason.

To finish, run done with the result:

$ npx startup-builder done task_1 --json '{"result":"https://captionyard.com/files/lesson-4.vtt"}'

done runs the Task's checks first. A Task closes only when every check passes, never on a Worker's word. A failing check refuses done, names the check, and leaves the Task with you.

To hand a Task back, release it with a reason:

$ npx startup-builder release task_1 --reason "needs the course glossary"

The next Worker reads the reason first. A lease that lapses releases the Task the same way.

To run a swarm, start more sessions, each with its own Worker key, running the same loop:

while task=$(npx startup-builder next | jq -r '.task."$id" // empty'); [ -n "$task" ]; do
  npx startup-builder claim "$task" || continue
  ./work.sh "$task"   # your agent works the Task, then runs done or release
done

An MCP agent runs the same loop as one do program:

const [task] = await $.Task.list({ where: 'status = pending', sort: '-priority', limit: 1 })
if (!task) return 'empty'
await $.Task.claim({ task: task.$id })
return task // work it, then call Task.complete or Task.return

Add Workers by adding sessions, not threads inside one session. A failed claim means another Worker took the Task first; the loop moves on.