Kjell Tore Guttormsen
ec92c866c1
Reading IS delivery in this engine: coord-inbox.sh prints a broadcast and then records it as seen. That made "what is pending elsewhere" unanswerable -- asking the read path per repo would have consumed every repo's broadcast backlog as a side effect, once, silently, and unrecoverably, since the seen set is delivery history that retraction deliberately leaves alone. coord-count.sh answers it by counting files and writing nothing: no seen set, no .origin. It keys on MAILBOXES rather than repos -- it enumerates $COORD/* and never scans a filesystem for checkouts -- so a repo without a mailbox is not missing from the count, it is absent from the domain. Drained mailboxes are omitted rather than reported as zero, because the question is "who is owed a reply" and a list of zeroes answers a different one at every reader's expense. The read path now closes with one aggregate line built from it. The case that motivated this is the session whose own inbox is empty: it saw silence and concluded "all clear" while mail sat unanswered everywhere else. BREAKING (injection contract): the read path is no longer silent whenever THIS repo has nothing pending. It is a silent no-op only when the whole mailbox is empty. Coupling the line to having your own mail would have hidden it from its only real audience. Three selftest assertions that used "no output at all" as a proxy for "nothing was delivered" now assert the absence of the content itself, which is what they always meant. The line is an AGGREGATE of two integers, never a roster. A list of names would reproduce other repos' situation inside this repo's injection -- the state boundary the mailbox exists to respect -- and mailbox names are cross-repo input. Two integers cannot carry anything that escapes the framing. Its disclaimer is engine behavior, not politeness (Rule 7): the line lands directly beneath "handle this inbox FIRST", and without it the numbers read as an extension of that obligation and a session starts answering other repos' mail. Pinned in selftest section 26 exactly as section 20 pins the priority text. The hook's header drops "(unread messages)" for the same reason -- it would now announce mail that does not exist. Selftest 116 -> 136. Every new negative check is anchored to a positive assertion in the same output, because a missing script makes "X is absent" true by vacuity and would have gone green proving nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U6EixQo6hpoRCVtiAXdnFs
178 lines
8.5 KiB
Markdown
178 lines
8.5 KiB
Markdown
---
|
|
name: coord-send
|
|
description: >-
|
|
Send an inter-repo coordination message through the local coord mailbox — a
|
|
natural-language front door over the `coord-send` script. Use this whenever the
|
|
user wants to notify, tell, message, ping, or coordinate with another repository
|
|
(or all repositories) about work happening in the current repo: "send info to all
|
|
repos", "tell repo-x the bug is fixed", "let repo Y and Z know",
|
|
"broadcast that the spec changed", "reply to that coord message", or a
|
|
deferred/conditional notice like "when the build is green, notify repo X". Also
|
|
triggers on Norwegian phrasings: "send info til alle repo", "varsle repo X", "gi
|
|
beskjed til Y og Z", "kringkast at …", "svar på coord-meldingen", "når Z er ferdig,
|
|
varsle X". Trigger even when the user names a repo plus something to convey without
|
|
saying "coord" explicitly — routing a message to another repo IS this skill. Also
|
|
covers retiring a broadcast that has become wrong or obsolete: "retract that
|
|
broadcast", "that announcement is outdated, pull it", "trekk tilbake kringkastingen",
|
|
"den broadcasten er utdatert".
|
|
version: "0.8.0"
|
|
---
|
|
|
|
# coord-send — natural-language front door for inter-repo messages
|
|
|
|
This skill turns a plain request ("tell repo X that Y happened") into the right
|
|
`coord-send` invocation. The script is the engine; this skill is only the mapping
|
|
from intent to arguments. It never edits mailbox files by hand — always go through
|
|
the script, because the script owns the filename grammar, frontmatter, and delivery
|
|
guarantees.
|
|
|
|
## Boundary — why messages are thin
|
|
|
|
The mailbox is **transport, not state**. A coord message is a *notice*, not the
|
|
source of truth. The durable record of any decision lives in the owning repo's
|
|
state files / docs and its git history. So when you compose a body, write a
|
|
self-contained heads-up and point at where the real record lives (a commit
|
|
hash, a doc path) — don't try to make the message itself the canonical artifact.
|
|
Coordination content is also private: it never belongs on a public surface.
|
|
|
|
## The engine
|
|
|
|
Resolve the script path portably — this one expression is correct both when the
|
|
skill runs bundled inside the plugin and when the scripts are installed as
|
|
personal scripts under `~/.claude/scripts/`:
|
|
|
|
CSEND="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/scripts/coord-send.sh"
|
|
|
|
Interface (body comes from a quoted heredoc so nothing in it is shell-expanded):
|
|
|
|
# to one repo
|
|
"$CSEND" --to <repo> --subject "<subject>" <<'BODY'
|
|
<message body>
|
|
BODY
|
|
|
|
# to every repo (accumulates; first-time newcomers see it too)
|
|
"$CSEND" --broadcast --subject "<subject>" <<'BODY'
|
|
<message body>
|
|
BODY
|
|
|
|
# reply to a message this repo received (routes to the original sender and
|
|
# marks the original handled; target + "Re: …" subject are inferred)
|
|
"$CSEND" --reply-to <message-filename> <<'BODY'
|
|
<message body>
|
|
BODY
|
|
|
|
# retire one of THIS repo's own broadcasts (no subject, no body)
|
|
"$CSEND" --retract <broadcast-filename>
|
|
|
|
Sender identity (`--from`) defaults to the basename of the current git toplevel, so
|
|
you almost never set it. Outside a git repo there is no default — the send refuses
|
|
with exit 2 rather than naming itself after the working directory, so on a global
|
|
surface (`~/repos`, `$HOME`) pass `--from <repo>` and make the identity a choice.
|
|
Exit 0 = delivered; exit 2 = usage/IO error (read stderr and fix the arguments
|
|
rather than retrying blindly).
|
|
|
|
## Choosing the target
|
|
|
|
- **One named repo** → `--to <repo>`. The repo name is its directory basename; use
|
|
the name the user gave. No registration exists — sending to a new name just creates
|
|
that repo's inbox, so a typo silently creates a dead mailbox. If unsure a name is
|
|
real, check `~/repos/` or existing `~/.claude/coord/<repo>/` before sending.
|
|
- **Several named repos** ("X and Y") → loop `--to` once per repo with the same
|
|
subject and body. There is no multi-target flag; the loop is the mechanism:
|
|
|
|
for repo in repo-x repo-y; do
|
|
"$CSEND" --to "$repo" --subject "<subject>" <<'BODY'
|
|
<body>
|
|
BODY
|
|
done
|
|
|
|
- **All repos** → `--broadcast`. Prefer this only when the notice genuinely concerns
|
|
everyone, because broadcasts accumulate and every future first-time repo sees the
|
|
standing backlog. For a bounded, known set, loop `--to` instead so unrelated future
|
|
repos don't inherit it. A broadcast that later turns out wrong can be retired with
|
|
`--retract` (see below), but only for repos that have not received it yet.
|
|
- **A reply to something received** → `--reply-to <filename>`. Use the filename from
|
|
the injected inbox/archive; it resolves the sender and closes the original in one
|
|
step.
|
|
|
|
## Retracting a broadcast
|
|
|
|
When a broadcast has become wrong or obsolete, retire it — don't send a correction
|
|
and leave the original standing, because every future first-time repo would receive
|
|
both. `--retract <broadcast-filename>` archives it out of the delivery queue.
|
|
|
|
Three things to be honest about when you report it:
|
|
|
|
- **It is un-send, not recall.** Repos that already received the broadcast keep it.
|
|
Retraction only stops delivery to repos that haven't seen it yet. If the old news
|
|
actively misleads someone who already got it, a correcting broadcast is still
|
|
needed — retraction alone does not reach them.
|
|
- **Only the sender may retract.** The `from:` field must match this repo's identity.
|
|
If the announcing repo has since been renamed, its old identity no longer resolves,
|
|
so pass `--from <old-sender>` explicitly (read the sender off the file). Say that
|
|
you did.
|
|
- **Nothing is deleted.** The message moves to `_broadcast/archive/`. Never remove a
|
|
mailbox file by hand — the script owns the filename grammar and delivery guarantees.
|
|
|
|
Find the filename in `~/.claude/coord/_broadcast/inbox/` (or from the injected
|
|
`--- broadcast: <filename> ---` line) rather than guessing it.
|
|
|
|
## Composing the message
|
|
|
|
Derive a short, specific `--subject` from the intent if the user didn't give one
|
|
("ingest bug fixed", not "update"). In the body, state what happened, what the
|
|
recipient should know or do, and a pointer to the durable record (commit hash, doc
|
|
path). Keep it to the point — this is a notice, not a report. Match the repo's
|
|
language convention for message content; keep it sober and factual.
|
|
|
|
## Deferred and conditional sends
|
|
|
|
"When Z is done, notify X" means: do **not** send now. Hold the intent — the target,
|
|
subject, and body — and continue the work. The moment condition Z is satisfied *in
|
|
this session*, fire the send. This works because you carry the intent across turns
|
|
within a session.
|
|
|
|
Be honest about the limit: a skill cannot persist intent across sessions. If the
|
|
session is ending and the condition still hasn't been met, surface the pending
|
|
message to the user so it isn't silently lost — don't imply it will fire later on
|
|
its own.
|
|
|
|
## After sending
|
|
|
|
Report what actually happened: the target(s), the subject, and the delivered
|
|
filename(s) from the script's stdout. If a send failed (exit 2), say so with the
|
|
stderr reason rather than claiming success. Delivery reaches the recipient at *their*
|
|
next session start (the receive side is a hook), so tell the user it's queued, not
|
|
that the other repo has seen it.
|
|
|
|
## Examples
|
|
|
|
**Example 1 — single repo, composed body**
|
|
Input: "tell repo-x the ingest bug is fixed, it was commit abc1234"
|
|
Action: `--to repo-x --subject "ingest bug fixed"`, body naming the fix and
|
|
pointing at commit abc1234 and the owning doc.
|
|
|
|
**Example 2 — broadcast**
|
|
Input: "let all the repos know the shared spec grew a new validation rule"
|
|
Action: `--broadcast --subject "spec: new validation rule"`, body summarizing
|
|
the change and pointing at the spec's owning repo.
|
|
|
|
**Example 3 — bounded multi-target**
|
|
Input: "gi beskjed til repo-x og repo-y om at gaten er re-pinnet"
|
|
Action: loop `--to repo-x` then `--to repo-y`, same subject "shared gate re-pinned".
|
|
|
|
**Example 4 — deferred**
|
|
Input: "når testene er grønne, varsle repo-y"
|
|
Action: keep working; once the test run passes this session, send
|
|
`--to repo-y` with the green result. If the session ends first, surface the
|
|
pending notice to the user.
|
|
|
|
**Example 5 — reply**
|
|
Input: "svar på coord-meldingen fra repo-x at vi tar det"
|
|
Action: `--reply-to <that-message-filename>`, body acknowledging and stating the plan.
|
|
|
|
**Example 6 — retract**
|
|
Input: "den gamle kringkastingen om plugin-navnet er utdatert, trekk den"
|
|
Action: locate the file in `_broadcast/inbox/`, then `--retract <that-filename>`
|
|
(adding `--from <old-sender>` if this repo has been renamed since). Report that
|
|
repos which already received it are unaffected.
|