list_ready
List tasks ready to build now—open, settled, all dependencies done—ranked by priority and roadmap standing. Excludes in-progress work, so you can dispatch directly from the list.
Instructions
The tasks ready to build right now: open, settled, every dependency done — RANKED, best first, by (blocks + 1) x the task's priority x the standing of the ROADMAP TARGET it serves, so reach and urgency combine at both altitudes rather than one overriding the rest. A task whose target still waits on an unshipped target sorts below every task whose roadmap row is clear. Each row carries the roadmap standing that ranked it. The rank is a starting order, not a decision. A task a worker has marked in progress (start_task) is NOT listed, so this is safe to dispatch straight from.
claims reports every claim the project holds — one row per in-progress task, each with its stale_for_minutes (whole minutes since the last heartbeat). It is an age, not a verdict: a healthy build shows a small number and a worker that died still holding a task shows a growing one, so a console displays the age and a dispatcher sweeps the quiet ones with claims.filter((c) => c.stale_for_minutes >= claimStaleMinutes) (default 15). A claim is never auto-released — release one deliberately with edit_task { spec: "replan" }.
scope draws a LANE: only tasks whose folders touch it are listed, so two dispatchers can run side by side without ever writing the same files. Folder containment counts either way (src covers src/orders), a task with no scope is in every lane, and no filter means everything. Each row also carries overlap: the ids of tasks being worked right now whose scope touches that row's, computed across ALL lanes, because a claim in another lane is exactly what a lane filter would otherwise hide. Normally empty; non-empty means dispatching it would put two workers over the same folders.
tags carries the row's plain GitHub labels, so a dispatcher can branch on the KIND of work without a second call. spike is the one this flow reads: a spike ticket's deliverable is a drafted ticket, not merged code, so it is briefed differently. Labels are adopted from the issue on every pull, so one added in the web UI reaches the dispatcher.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Folders that draw this dispatcher's lane. Omit for every ready task. | |
| branch | No | Branch to scope to (optional; the backend decides its use). | |
| project | No | The project id — an opaque, supplied string, never derived. Omit to use the server's --project-id default. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| tasks | Yes | ||
| claims | Yes |