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:
mvschwarz committed 2026-06-01 04:08:21 -07:00
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;