CLAUDE.md — apiary

1# Apiary — AI Worker Instructions

3Apiary is an MCP server for Enclave-based agent coordination. Read this file before making changes.

5## Define ordering discipline

7Every Sigil library file in apiary follows this order inside `(begin ...)`:

91. Type / struct definitions

102. Constants

113. Pure helpers (no upward references)

124. Internal procedures (may call helpers)

135. Public entry points

146. Tool registration functions LAST (they reference everything above)

Forward references from tool-registration functions to helpers defined later in the file have caused silent crashes in related Sigil work. With this discipline, those bugs cannot recur — the offending code wouldn't compile.

18## Trusted set filter

20Every bot applies the same channel-message filter:

22```

23trusted_set = {owner} ∪ {reports-to} ∪ {subordinates} ∪ {listened peers}

25IF sender ∈ trusted_set THEN

26 IF message starts with "@<my-nick>: " → deliver as mention

27 IF message starts with "@<other-nick>: " → ignore

28 ELSE → deliver as broadcast

29ELSE

30 ignore

31```

33A bot does NOT receive its own messages — apiary suppresses self-echo before MCP delivery.

35## Mention syntax

Strict `@<nick>: <body>` in IRC. The `@` is mandatory and disambiguates from any colon use in bodies. Apiary adds the `@` automatically when an agent calls `send-channel mention: "<nick>"`. MCP-delivered messages do NOT use `@` — they use `<sender>: <body>` format because apiary controls that side end-to-end.

39## Build conventions

- `sigil build apiary -c release --backend bytecode` for releases (the native backend currently breaks on a sigil-crypto ABI drift; bytecode-release is the workaround until that's fixed).

- Always force-rebuild with `--force` when changing code that may be cached: `sigil build apiary -c release --backend bytecode --force`.

43- Confirm the build touched changed files: look for `COMPILE apiary/<file>.sgl` in the build output.

45## Testing

47Local smoke harness at `test/smoke.sh` boots a throwaway local enclave server, runs apiary against it, and exercises:

48- Bridge connect + reconnect presence

49- Trusted-set filtering (broadcast / mention to me / mention to other / non-trusted sender)

50- listen-peer / unlisten-peer mechanics

51- Group-based voicing

52- MCP sender-mention rewriting

53- Self-echo suppression

54- Tool registration completeness for both leader and worker modes

56Unit tests in `test/*.sgl` for individual module behavior.

58## License & Copyright

60BSD-3-Clause.