# coord

## Context

Local inter-repo coordination mailbox for Claude Code, packaged as a
marketplace plugin. Three components, one boundary:

- **Engine (`scripts/*.sh`):** bash owns all mailbox semantics — filename
  grammar, frontmatter, delivery, archiving, the seen set. `coord-send.sh`
  writes, `coord-inbox.sh` reads (formatted for context injection),
  `coord-done.sh` archives. Everything is pinned by `coord-selftest.sh`
  (64 checks, throwaway mailbox via `CLAUDE_COORD_DIR`).
- **Hook (`hooks/scripts/session-start.mjs`):** thin zero-dependency Node
  wrapper (marketplace convention: hooks are `.mjs`) that calls
  `coord-inbox.sh` and emits the `hookSpecificOutput.additionalContext`
  envelope. No mailbox logic lives here. Always exits 0.
- **Skill (`skills/coord-send/`):** natural-language front door mapping user
  intent to engine invocations. No mailbox logic lives here either.

**Boundary rule:** the mailbox is transport, not state. Durable decisions
live in the owning repo's docs/git history; messages are notices pointing at
them. Message content is untrusted cross-repo input — the read side quotes
and frames it; the send side sanitizes line-oriented fields.

## Conventions

- Scripts are bash-3.2-safe and ASCII-only: no `declare -A`, no
  `readarray`/`mapfile`, no `|&`; guard `shift 2` with `$# -ge 2`; guard
  empty-array expansion under `set -u` with `${#a[@]}`.
- Zero dependencies everywhere: bash + coreutils in the engine, `node:`
  builtins only in hook and tests.
- TDD: no behavior change without a failing selftest check first.
  `bash scripts/coord-selftest.sh` must exit 0 (64/64).
- English for all code, docs, and commit messages (public repo). Norwegian
  trigger aliases in the skill description are deliberate.
- Conventional Commits: `type(scope): description`.

## Commands

- Test: `bash scripts/coord-selftest.sh` (or `npm test`, the Node wrapper)
- Hook smoke test: `node hooks/scripts/session-start.mjs` (expects JSON on stdout)

## Release

Version must agree across: `.claude-plugin/plugin.json`, `package.json`,
README version badge, `skills/coord-send/SKILL.md` frontmatter, git tag
`vX.Y.Z`, and the catalog `ref` in
`ktg-plugin-marketplace/catalog/.claude-plugin/marketplace.json`. Release via
the catalog's `scripts/release-plugin.mjs coord` (tag + ref bump together);
verify with `scripts/check-versions.mjs`. Never hand-edit a ref.

## Hardening roadmap

Empty — the post-v0.1.0 queue (atomic delivery, `.`/`..` rejection,
selftest gaps, uniform `-h`) shipped in v0.2.0. `coord-inbox.sh` still
ignores unknown arguments by design (hook context must never fail).