diff --git a/docs/SESSIONS.md b/docs/SESSIONS.md index 162be5a3..f0cfa55d 100644 --- a/docs/SESSIONS.md +++ b/docs/SESSIONS.md @@ -8,3 +8,4 @@ are never rewritten or removed; corrections are new entries. |---|---|---|---| | 2026-09-03 | assistant (conductor + worker) | POC through M12: containerized pi proof, config layer, missions/tasks, release model, adapter seam, workspaces/capabilities, named sessions, retention, session forking, conductor auto-apply, roles/ convention | 13 tags; suites 24/58/14 + 17 conductor + verify green; releases 0.0.1–0.0.7; issues #1–#34 closed | | 2026-09-03 | assistant (conductor) | User layer: profile updates (pets, family), ms-user skill review/revision (confirmation rules merged, propose-not-apply, missing-file flow, privacy scope, dispatch = all of user/, rule 9 scratch-file constraint), USER.md.bak removed | skills/ms-user/SKILL.md rewritten; ~/.mosaic-dev/user/USER.md updated (Family, Pets); USER.md.bak deleted | +| 2026-09-03 | assistant | ms-communications skill: inter-agent messaging protocol consolidated from tools/tmux/README.md and agent-send.sh (channel, preamble grammar, flip-on-reply, triage classes, etiquette, receiving protocol, delivery mechanics) | skills/ms-communications/SKILL.md created; unslop-check clean | diff --git a/skills/ms-communications/SKILL.md b/skills/ms-communications/SKILL.md new file mode 100644 index 00000000..9a42aa1d --- /dev/null +++ b/skills/ms-communications/SKILL.md @@ -0,0 +1,84 @@ +--- +name: ms-communications +description: Use this skill whenever sending a message to, or receiving one from, another Mosaic agent. +disable-model-invocation: false +--- + +# ms-communications + +Agent-to-agent messaging: one channel, one addressing grammar, honest triage. +Messages are transport. The durable record lives in run records, issues, and +SESSIONS.md, never in a pane that scrolls away. + +## Channel + +- `tools/tmux/agent-send.sh` is the only send path. It prepends the preamble, + submits reliably (bracketed paste, Enter flush, draft detection), and ships + itself over ssh for remote targets. Never raw `tmux send-keys`; that is how + messages die as unsubmitted drafts. +- Non-Fleet seats use the default docket. +- Fleet seats use the named socket: `-L mosaic-fleet` (or `MOSAIC_TMUX_SOCKET`). + Fleet traffic stays off the user's default tmux server. +- Address durable fleet seats exactly: `=coder0`, not a prefix that might match + two sessions. +- Tool spec and internals: `tools/tmux/README.md`. + +## Preamble (required) + +``` +[: -> :] +[ -> class=] # with triage class +``` + +`host` is `hostname -s` of the sender's machine; `session` is the tmux session +name. `agent-send.sh` writes the preamble for you. Two rules carry the protocol: + +1. Replying? Flip it: `[ -> ] ...`. Answer under your own lane. +2. A preamble-less cross-agent message is malformed. If you receive one, ask + the sender to resend before acting on it. + +## Triage classes + +| Class | Meaning | Recipient behavior | +|---|---|---| +| (absent) | fail-safe default | treat as `actionable` | +| `actionable` | decision, blocker, or gate | act, then reply | +| `human` | from a human operator | deliver; respond promptly | +| `reaction` | emoji or ack | note it; no reply expected | +| `terminal-log` | log-only noise | file it; never act | +| `digest` | machine-wake, coalescible | batch; wake and continue | + +Class honestly. Never downgrade a question you want answered to `terminal-log`. + +## Etiquette + +1. Write for a context-wiped reader. Preamble plus body must carry the ask, the + evidence (run id, issue number, path), and any deadline. The recipient has + no "as I mentioned earlier". +2. One topic per message. Two asks in one paste is how the second gets lost. +3. Reply, even when the reply is "ACK, on it" or "cannot, reason follows". + Silence is not an ack. A refusal with a reason is recoverable; a guess is not. +4. No secrets. Messages land in scrollback, logs, and possibly comms daemons. +5. Waiting on a condition? Arm `agent-watch` on the condition, not a poll of a + colleague's pane. Waiting on a seat? Message them (see ms-agent-watch). + +## Receiving + +1. Read the preamble first. Confirm you are the `dst`. Note the `src`. +2. Triage by class (table above). `actionable` or absent: act now, or reply why not. +3. Reply with the preamble flipped. Cite the run id or issue you acted on. + +## Delivery mechanics + +- Exit codes: `0` delivered or queued, `1` target not found, `2` still draft, + `3` usage error, `4` ambiguous socket (the session name exists on more than + one tmux server; disambiguate with `-L`). +- A refusal is evidence. Diagnose it; do not route around it with raw send-keys. +- rc=2 from an `agent-watch` delivery means the text reached your pane as a + draft. Go read the pane; `auto-submit-drafts.sh` flushes stable drafts. + +## When not to message + +- Waiting on yourself: do the next thing. +- Facts that must survive the exchange belong in the run record, the issue, or + SESSIONS.md. A message that matters gets persisted where the record lives.