mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-08 17:31:56 -10:00
skill(slice-21 FR-1): surface coordination primitives + §1b doctrine at top of openrig-user boot skill (OPR.0.3.2.21.FR-1)
Every booting agent (especially orchestrators) now internalizes the
send vs queue vs queue-handoff coordination model from the first read
of its boot skill, not as a buried 2026-05-11 CANONICAL SURFACE NOTE
inside the Runtime-Gated Coordination Primitives section.
The fix is a content-only edit to the shipped openrig-user skill.
No CLI primitives change; rig send / rig queue / rig queue handoff
are correct and shipping. The slice closes a doctrine-load-bearing
gap that surfaced in dogfood + external-host orchestrator review:
"agents don't default to the queue system" because the boot skill
didn't make the model load-bearing.
What was added (packages/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md):
(1) New "Coordination primitives — when to use which" section
inserted at line 15, before the existing "Runtime-Gated
Coordination Primitives" section. The new section is the first
practical content the reader sees after the brief title /
scope intro, putting it in the first ~14% of the file.
(2) Three sub-sections covering each primitive with definition +
runnable example:
- rig send <seat> "<text>" — intra-pod direct messaging /
nudges. NOT for durable work. Receipt model and Verified
semantics noted.
- rig queue create — durable work item. Survives restarts.
Tagging discipline noted. Temp-file body pattern noted
explicitly (the body parser does not tolerate raw backticks
or flag-like tokens).
- rig queue handoff — hot-potato handoff. Chain-of-record
preserved. Phase-boundary tag forward.
(3) §1b doctrine sub-section: turn ends by passing the ball, never
by going idle holding the slice waiting on a confirmation the
process does not include. Two valid pauses named (genuine
blocker / scope-or-architecture question that requires owner
input); everything else proceeds.
(4) Anti-patterns list: four patterns named with the fix recipe
for each (rig send for durable work → queue create; idle-hold
→ queue handoff; rigx queue for new work → rig queue;
inline backtick-heavy body → temp-file pattern).
Harmonization of the existing 2026-05-11 CANONICAL SURFACE NOTE
(in the Runtime-Gated Coordination Primitives section): the buried
bullet at the previous lines 32-34 is rewritten as a back-pointer
to the new top-of-skill section, preserving the 2026-05-11
historical-traceability anchor while removing the canonical-claim
duplication. Auxiliary verbs (rig queue update / show / list) are
retained on the back-pointer line so operators can still find them
adjacent to the runtime-gating discussion.
Acceptance per FR-1 IMPL-PRD:
- HG-1: section at top of skill (lines 15-105 of 734 = first ~14%). PASS.
- HG-2: all 3 primitives covered with definition + example. PASS.
- HG-3: §1b doctrine surfaced explicitly with turn-ends-by-passing-the-ball language. PASS.
- HG-4: anti-patterns list present. PASS.
- HG-5: CANONICAL SURFACE NOTE harmonized via back-pointer. PASS.
- HG-6: frontmatter unchanged + markdown structure clean (visual check). PASS.
- HG-7 / HG-8: deferred to per-commit guard + full-tip qa dogfood.
Optional rig-injected overlay mirror (orchestrator/guidance/role.md
Communication section) is in scope but lands as a separate second
commit on this branch per IMPL-PRD §93 estimate — keeps this commit
bounded to the primary skill surface.
Branch: slice-21-fr-1-coordination-model-boot-instinct off LOCAL
main ea03680d. LOCAL only, NO push.
This commit is contained in:
1 parent
ea03680de4
commit
43f2259ff7
1 file changed
+98
-3
@@ -12,6 +12,97 @@ This is not the config-layer or builder guide. Use the substrate control-plane g
|
||||
and experimental overlays. Use the OpenRig builder guidance when changing OpenRig behavior,
|
||||
doctrine, or release posture.
|
||||
|
||||
## Coordination primitives — when to use which
|
||||
|
||||
Three coordination surfaces, used together for forward-momentum work. Internalize this
|
||||
on first read — it shapes every turn you take in a rig.
|
||||
|
||||
### `rig send <seat> "<text>"` — intra-pod direct messaging / nudges
|
||||
|
||||
Use when you need to ask a quick question or give a teammate context that does not
|
||||
carry handoff semantics. **NOT for durable work.** NOT for state that must survive
|
||||
across turns. The message lands in the target's pane; there is no durable queue
|
||||
record. The CLI prints `Sent to ...` (and `Verified: yes/no` with `--verify`); read
|
||||
the receipt and move on.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
rig send velocity-guard@openrig-velocity "Heads up — filing per-commit handoff on slice-22 Bug 1 BONUS at tip 6b8673b6." --verify
|
||||
```
|
||||
|
||||
### `rig queue create --source <X> --destination <Y> --tags <...> --body "<...>"` — durable work item
|
||||
|
||||
Use for any substantive work that must not fall through chat — slice handoffs,
|
||||
guard verdicts, QA results, full-tip reviews, multi-item batches. Survives agent
|
||||
restarts. Tracked in the daemon SQLite schema. Surfaces in Project / queue views
|
||||
+ in the destination seat's inbox. Tag with mission / slice / gate / checkpoint
|
||||
so future-you (and any peer) can find it.
|
||||
|
||||
Body discipline: substantive bodies go through a temp-file pattern, not inline
|
||||
`--body` with raw backticks — `rig queue create` body parsing breaks on
|
||||
unescaped backticks and rejects flag-like tokens.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
rig queue create \
|
||||
--source redo-driver-2@openrig-velocity \
|
||||
--destination redo-guard-2@openrig-velocity \
|
||||
--tags "mission:release-0.3.2,slice:22-rig-up-paper-cut-fix-round,gate:guard,handoff:per-commit,checkpoint:bug-1-bonus" \
|
||||
--body "$(cat /tmp/per-commit-body.txt)"
|
||||
```
|
||||
|
||||
### `rig queue handoff <qitem-id> --destination <next> ...` — hot-potato handoff
|
||||
|
||||
Use when you have completed your turn on a qitem and the work moves to the next
|
||||
owner. **This is forward momentum.** The ball passes to the destination seat;
|
||||
chain-of-record (the prior qitem id) is preserved so the verdict trail is intact;
|
||||
tags carry the phase boundary forward (e.g. `gate:guard` → `gate:qa`).
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
rig queue handoff qitem-20260601012431-d78aa805 \
|
||||
--destination velocity-qa@openrig-velocity \
|
||||
--tags "mission:release-0.3.2,slice:22-rig-up-paper-cut-fix-round,gate:qa,handoff:adversarial-dogfood"
|
||||
```
|
||||
|
||||
### §1b doctrine — turn ends by passing the ball
|
||||
|
||||
**A turn ends by passing the ball, never by going idle holding the slice waiting
|
||||
on a confirmation the process does not include.** If the work was authorized, the
|
||||
per-commit guard + adversarial QA + orch heavy-verify are the guardrails — not an
|
||||
operator pre-commit gate. Do the authorized work and pass the ball.
|
||||
|
||||
Valid pauses are only:
|
||||
|
||||
- A genuine blocker — file a blocked-state qitem against the blocking peer or
|
||||
surface explicitly to orch.
|
||||
- A founder-scope or architecture question that changes the plan — surface to
|
||||
orch with the specific decision needed.
|
||||
|
||||
Implementing already-authorized work is neither of these. Proceed without
|
||||
phantom-gating on an imagined "next prompt" or "operator confirmation" that the
|
||||
process does not require.
|
||||
|
||||
### Anti-patterns
|
||||
|
||||
- Using `rig send` for durable work → use `rig queue create` instead. Sends do
|
||||
not survive restarts and do not show up in queue/project views.
|
||||
- Idle-holding a slice for an imagined "next prompt" or "operator confirmation"
|
||||
that the process does not require → pass the ball via `rig queue handoff` and
|
||||
proceed to the next slice or stand by for the inbound verdict. See the §1b
|
||||
doctrine above.
|
||||
- Hand-coding `rigx queue` for new work → `rig queue` is the daemon-backed
|
||||
canonical surface since the 2026-05-11 host-CLI fix. `rigx queue` is a
|
||||
recovery-only fallback; qitems written via `rigx queue` are invisible to
|
||||
daemon-backed reads and break fleet-wide routing discipline.
|
||||
- Inlining a multi-line / backtick-heavy body into `rig queue create --body`
|
||||
→ write the body to `/tmp/<descriptive-name>.txt` first, then
|
||||
`--body "$(cat /tmp/<file>.txt)"`. The body parser does not tolerate raw
|
||||
backticks or flag-like tokens inline.
|
||||
|
||||
## Runtime-Gated Coordination Primitives
|
||||
|
||||
OpenRig v0.3.1 is published publicly as `@openrig/[email protected]` and GitHub Release
|
||||
@@ -29,9 +120,13 @@ Default posture:
|
||||
|
||||
- Treat daemon `rig queue`, `rig stream`, `rig project`, `rig view`, `rig watchdog`, and
|
||||
`rig workflow` as the product coordination surfaces when the active daemon is v0.2.0 or newer.
|
||||
- **CANONICAL SURFACE NOTE (2026-05-11)**: `rig queue` (daemon-backed SQLite) is the
|
||||
canonical surface for queue routing since the 2026-05-11 host-CLI fix landed. Use
|
||||
`rig queue create / handoff / update / show / list` for all substantive work.
|
||||
- **CANONICAL SURFACE NOTE (2026-05-11)**: `rig queue` (daemon-backed SQLite) became
|
||||
the canonical queue-routing surface when the 2026-05-11 host-CLI fix landed. The
|
||||
coordination model is now load-bearing at the top of this skill — see
|
||||
"Coordination primitives — when to use which" above for the send / queue /
|
||||
queue-handoff usage model and the §1b doctrine. Auxiliary queue verbs:
|
||||
`rig queue update / show / list` complement `rig queue create / handoff`
|
||||
for in-flight inspection and state mutation.
|
||||
- Use temporary substrate overlays such as `rigx queue`, `rigx stream`, `rigx project`, and
|
||||
`rigx view-proto` only where the current OpenRig workstream explicitly says that legacy/control
|
||||
layer is still in use. For queue specifically, `rigx queue` is recovery-only fallback;
|
||||
|
||||
Reference in new issue
Block a user