queue-handoff

Name: queue-handoff
Author: mvschwarz

56stars9forks

How to install queue-handoff?

mvschwarz/openrig/queue-handoff

$npx -y skills add mvschwarz/openrig --skill queue-handoff

Installs into the current project.

Summary

Use when ending a turn, finishing a slice, blocked on another agent's work, or escalating to a human — durable work handoff via queue items so the system keeps moving across compactions, missed messages, and interruptions. Covers the hot-potato terminal-turn-rule (active work end

Files · 1

View on GitHub

SKILL.md

1	# Queue Handoff
2
3	Durable work handoff via queue items. Lets the system keep moving
4	through compactions, missed messages, and interruptions by passing the
5	ball forward instead of leaving work suspended in chat or in-flight
6	without an owner.
7
8	## Use this when
9
10	- Ending a turn on substantive work. Active work should end by
11	passing the ball to an owner or to the human — never by going idle
12	with the rig appearing dormant.
13	- Finishing a slice that has a clear next step. Default-nudge:
14	receiver gets a wake-ping plus the durable queue item.
15	- Blocked on another agent's work. Park the qitem with
16	`closure_reason: blocked_on` and the blocker qitem id.
17	- Escalating to the human. Make the escalation a durable attention
18	item, not just a chat message.
19
20	## Don't use this when
21
22	- The work is genuinely complete and there's no follow-on owner. Use
23	`closure_reason: no-follow-on` (terminal completion) or
24	`canceled`/`denied` as appropriate.
25	- The handoff would be too small and turn work into bureaucracy. Bundle
26	the work into a coherent slice instead of decomposing every step.
27	- The handoff would be too broad and lose ownership/proof/closure
28	criteria. Shape the qitem so the receiver knows the expected next
29	action and closure evidence.
30
31	## The hot-potato terminal-turn-rule
32
33	Active work ends by passing the ball to a named next owner or to the
34	human. The qitem state machine enforces this:
35
36	`pending → in-progress → done` requires `closure_reason` from one of:
37
38	- `handed_off_to` — work continues at a different seat (target = new owner)
39	- `blocked_on` — parked pending another qitem (target = blocker qitem id)
40	- `denied` — receiver rejected the work
41	- `canceled` — sender or receiver withdrew
42	- `no-follow-on` — terminal completion, nothing else needed
43	- `escalation` — kicked up to a higher tier (target = escalation target)
44
45	Three of those (`handed_off_to`, `blocked_on`, `escalation`) additionally
46	require `closure_target`. The daemon enforces this at the domain layer;
47	every surface (CLI, MCP, future UI) inherits the same guarantee.
48
49	## Default-nudge semantics (the syntax footgun)
50
51	\| Command \| Nudges by default? \| When to use \|
52	\|---\|---\|---\|
53	\| `rig queue create` \| yes \| New qitem created from scratch \|
54	\| `rig queue handoff` \| yes \| Transactional close-as-handed-off + create-new \|
55	\| `rig queue handoff-and-complete` \| yes \| Atomic close + create-new; default nudge wakes the new owner \|
56	\| `rigx queue handoff` (filesystem v0 prototype; recovery-only fallback since 2026-05-11) \| yes \| Legacy artifact; qitems invisible to daemon-backed reads; deprecated with removal queued. Use `rig queue handoff` (daemon-backed) for all new substantive work. \|
57
58	Footgun: `--no-nudge` accidentally added to a live-loop handoff.
59	The shipped 0.3.1 CLI nudges by default on every queue write surface
60	(`rig queue create`, `rig queue handoff`, AND `rig queue handoff-and-complete`).
61	The only suppression flag is `--no-nudge` — appropriate for intentional
62	cold park, human-gate signal, or a deliberate poll-driven workflow, but
63	NOT for live-loop handoffs where motion matters.
64
65	Rule: in a live loop, omit `--no-nudge` and trust the default.
66	`--no-nudge` is the opt-out, not the opt-in. If you find yourself
67	reaching for `--notify`, stop — that flag does not exist on the
68	shipped 0.3.1 CLI; you may be following a stale instruction that
69	inverted the default-nudge polarity.
70
71	## Queue-body hygiene (token + parse safety)
72
73	The qitem body is durable DATA the daemon stores and replays on every
74	`rig queue show <id>` / `--json` read. Keep it small and parse-safe — a
75	bloated or malformed body costs every future reader, not just the
76	recipient.
77
78	- No large command output in bodies. Do NOT paste `rig ps`/`--nodes`
79	dumps, big JSON blobs, full proof output, diffs, or transcript chunks
80	into a qitem body. Link the artifact PATH (e.g

People who liked this also viewed

6 picks

Type

queue-handoff

56stars9forks

View on GitHub

How to install queue-handoff?

mvschwarz/openrig/queue-handoff

$npx -y skills add mvschwarz/openrig --skill queue-handoff

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Queue Handoff
2
3	Durable work handoff via queue items. Lets the system keep moving
4	through compactions, missed messages, and interruptions by passing the
5	ball forward instead of leaving work suspended in chat or in-flight
6	without an owner.
7
8	## Use this when
9
10	- Ending a turn on substantive work. Active work should end by
11	passing the ball to an owner or to the human — never by going idle
12	with the rig appearing dormant.
13	- Finishing a slice that has a clear next step. Default-nudge:
14	receiver gets a wake-ping plus the durable queue item.
15	- Blocked on another agent's work. Park the qitem with
16	`closure_reason: blocked_on` and the blocker qitem id.
17	- Escalating to the human. Make the escalation a durable attention
18	item, not just a chat message.
19
20	## Don't use this when
21
22	- The work is genuinely complete and there's no follow-on owner. Use
23	`closure_reason: no-follow-on` (terminal completion) or
24	`canceled`/`denied` as appropriate.
25	- The handoff would be too small and turn work into bureaucracy. Bundle
26	the work into a coherent slice instead of decomposing every step.
27	- The handoff would be too broad and lose ownership/proof/closure
28	criteria. Shape the qitem so the receiver knows the expected next
29	action and closure evidence.
30
31	## The hot-potato terminal-turn-rule
32
33	Active work ends by passing the ball to a named next owner or to the
34	human. The qitem state machine enforces this:
35
36	`pending → in-progress → done` requires `closure_reason` from one of:
37
38	- `handed_off_to` — work continues at a different seat (target = new owner)
39	- `blocked_on` — parked pending another qitem (target = blocker qitem id)
40	- `denied` — receiver rejected the work
41	- `canceled` — sender or receiver withdrew
42	- `no-follow-on` — terminal completion, nothing else needed
43	- `escalation` — kicked up to a higher tier (target = escalation target)
44
45	Three of those (`handed_off_to`, `blocked_on`, `escalation`) additionally
46	require `closure_target`. The daemon enforces this at the domain layer;
47	every surface (CLI, MCP, future UI) inherits the same guarantee.
48
49	## Default-nudge semantics (the syntax footgun)
50
51	\| Command \| Nudges by default? \| When to use \|
52	\|---\|---\|---\|
53	\| `rig queue create` \| yes \| New qitem created from scratch \|
54	\| `rig queue handoff` \| yes \| Transactional close-as-handed-off + create-new \|
55	\| `rig queue handoff-and-complete` \| yes \| Atomic close + create-new; default nudge wakes the new owner \|
56	\| `rigx queue handoff` (filesystem v0 prototype; recovery-only fallback since 2026-05-11) \| yes \| Legacy artifact; qitems invisible to daemon-backed reads; deprecated with removal queued. Use `rig queue handoff` (daemon-backed) for all new substantive work. \|
57
58	Footgun: `--no-nudge` accidentally added to a live-loop handoff.
59	The shipped 0.3.1 CLI nudges by default on every queue write surface
60	(`rig queue create`, `rig queue handoff`, AND `rig queue handoff-and-complete`).
61	The only suppression flag is `--no-nudge` — appropriate for intentional
62	cold park, human-gate signal, or a deliberate poll-driven workflow, but
63	NOT for live-loop handoffs where motion matters.
64
65	Rule: in a live loop, omit `--no-nudge` and trust the default.
66	`--no-nudge` is the opt-out, not the opt-in. If you find yourself
67	reaching for `--notify`, stop — that flag does not exist on the
68	shipped 0.3.1 CLI; you may be following a stale instruction that
69	inverted the default-nudge polarity.
70
71	## Queue-body hygiene (token + parse safety)
72
73	The qitem body is durable DATA the daemon stores and replays on every
74	`rig queue show <id>` / `--json` read. Keep it small and parse-safe — a
75	bloated or malformed body costs every future reader, not just the
76	recipient.
77
78	- No large command output in bodies. Do NOT paste `rig ps`/`--nodes`
79	dumps, big JSON blobs, full proof output, diffs, or transcript chunks
80	into a qitem body. Link the artifact PATH (e.g

People who liked this also viewed

6 picks

Type