Coordination: assigning tasks to agents

Documented against OpenRig 0.7.7. Help text uses "node" where these pages say seat, for a seat's position in the running rig.

What it is for

A queue item is one unit of owned work: a row in the daemon's database with a destination seat, a body, a state and an append-only history of transitions. It survives the owner's turn ending, the owner compacting and the owner being replaced. A seat cannot close work without saying where it went, and handing work to another seat closes yours and opens theirs in one transaction, so nothing strands between seats. Durable does not mean automatic: a row can still need a person or a peer to notice it. What the queue guarantees is that the work stays recorded and attributable, with an owner and a history, whatever happens to the seats.

Around the queue sit three smaller surfaces. A stream is an append-only intake log for observations nobody has to act on yet. A seat can subscribe to the stream items addressed to it or tagged with its topics (rig stream subscribe), read them a page at a time (rig stream read), and record what it did about one with rig stream act: the row it opened or joined, a decline with its reason, or a pointer to the row it repeats. A view is a named lens over coordination state, such as what is held, what is waiting on a person, or which claimed rows have stalled. A project record turns a raw observation into a routed, typed, deduplicated row instead of a hand-made one.

The three verbs you will use first

Create a row for a seat. The destination is the seat that owns the work (help sometimes says "node" for a seat's position in the running rig). Multiline bodies go through --body-file; --mission and --slice attach the work to the work tree as tags. A row for a person is a decision by default; --human-intent update makes it a quiet note for them instead, never an approval request.

rig queue create --destination dev-impl@my-rig --body-file brief.md --mission search-experience --slice 01-search-page

Claim it, then close it honestly. Claim moves pending to in-progress. Closing to done requires a closure reason from a fixed set: handed_off_to, denied, canceled, no-follow-on, escalation, superseded. To wait for another row instead, block on it (below). A note without --state never changes state, and rig queue update <id> --summary "<text>" corrects a row's subject on its own. Closure records delivery, not acceptance; acceptance is the next stage's verdict on its own row.

rig queue claim qitem-20260901100000-abcd1234ef567890
rig queue update qitem-20260901100000-abcd1234ef567890 --note "matching any title word, not the whole phrase"
rig queue update qitem-20260901100000-abcd1234ef567890 --state done --closure-reason no-follow-on --note "accepted, one loose end"

Hand it on. One transaction: the source row closes as handed-off and a new row opens at --to. Omit the body to carry the source body forward.

rig queue handoff qitem-20260901100000-abcd1234ef567890 --to build-checker@my-rig --note "candidate ready; keyboard path per requirement 2"

Reading the board

rig queue list defaults to active rows in your current rig, like docker ps; -a adds history and -A crosses rigs. --owned shows only the obligations assigned to you. rig queue show <id> gives a bounded preview; --full --json prints the complete item record without truncation. It is the item, not its history: the transitions are a separate read. rig queue transitions <id> is the audit trail of what happened to a row. rig view show held lists what is parked and on what; rig view show escalations lists what waits on a person; rig view show pickup derives whether a claimed row is working, stalled after claim, parked or unclaimed.

Waiting on a blocker

rig queue block <id> --on <blocker> puts a task on hold with a note on how to continue and one live wake-up: a watchdog job (--wake-watchdog), a timer (--wake-after 15m), or another live task it waits on. The blocker can be a live task, a typed gate or a person. Waiting on a person needs a plain-language summary and a durable evidence reference, because a person will judge it. Closing a blocked row would be a lie; sitting on it silently looks identical to a crash. rig queue resolve writes the person's decision, or the evidence that a typed gate is satisfied, onto the row and wakes the owner; a wait on another row ends when that row does, not through resolve.

What it does not do

• Closing a row is not acceptance. handed_off_to records delivery; the receiver's own verdict lives on the receiver's row.
• A message (rig send) is not a row. If another seat must act, create or hand off a row.
• queue list reports up to its --limit (default 100); a board can be larger. Confirm the returned count is under the limit before claiming nothing is held.
• Tags and priority are set at create or handoff; the list view is a projection and show --full is the record.

Where it goes next

• Workflows: a declared spec that projects the next row when a step closes, so you stop relaying.
• The terminal UI: attention and pickup are these rows seen from the operator's side.
• Messaging: the informing channel that sits beside the obligating one.