docs: add community-organizer protocol spec

Defines the vocabulary, NIP-52 event shapes, NIP-72 community model,
and lifecycle for a chat-captured + Nostr-stored community organizer
spanning the `tracker` maubot plugin (forthcoming) and renderers like
inky-impression.

Reuses existing standards (RFC 5545 VTODO, NIP-52, NIP-72,
ActivityStreams vocab) instead of inventing new event kinds, so other
communities can adopt the same shape and renderers interop across
implementations. Spec lands before any plugin code so the contract
isn't an after-the-fact derivation from the implementation.

CLAUDE.md + README now point at the spec as the source of truth for
verb/event/tag changes — future sessions update the spec first, not
the plugin code.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Padreug 2026-05-24 15:12:37 +02:00
commit 1f195fb36d
3 changed files with 685 additions and 4 deletions

View file

@ -1,4 +1,6 @@
# CLAUDE.md — maubot-plugins
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What this repo is
@ -17,6 +19,14 @@ their source dir after `zip -j ../<plugin>.mbp ...`.
- **Per-plugin docs:** `<plugin>/README.md` covers commands, schema,
quirks, etc.
- **Repo-wide build/upload flow:** root `README.md`.
- **Community-organizer protocol spec:** `docs/community-organizer-spec.md`
defines the vocabulary, event shapes (NIP-52 + NIP-72), lifecycle
states, and tag conventions shared across the `tracker` plugin, the
`inky-impression` renderer, and any future surface (webapp form, CLI,
etc.). **Read this before changing any verb behavior, tag shape, or
event structure** — it's the contract other implementations (and
other communities) build against. Don't redesign these in plugin code;
update the spec first.
- **Maubot patterns and footguns:** `~/dev/CLAUDE.md` under
"Maubot plugin development" — covers `database_type` semantics,
`@command.new` vs `@command.passive`, multi-line caveats, etc.
@ -46,9 +56,27 @@ zip -j ../<plugin>.mbp maubot.yaml *.py
```
For brand-new plugins, also create the bot's Matrix account first
(via Continuwuity registration token), add it as a Client in the
maubot UI, then create an Instance binding the plugin to that
client.
(via Continuwuity registration token from the admin room — `!admin
token issue --once`, then register through Element), add it as a
Client in the maubot UI, then create an Instance binding the plugin
to that client. Existing example: `@journalbot:ariege.io` for
`journal/`.
### `maubot.yaml` conventions for new plugins
- **`id`: use the `dev.aiolabs.<name>` namespace.** Maubot keys plugins
by this string in its DB and on disk (`/var/lib/maubot/plugins/
dev.aiolabs.<name>-v<ver>.mbp`), so it must be globally unique across
every maubot ecosystem — reverse-DNS is the convention (cf.
`xyz.maubot.reminder`). Reserving `dev.aiolabs.*` for our plugins
keeps ids predictable and rename-safe. Changing the id later is a
fork, not a rename: every existing instance gets orphaned.
- **`database_type:` if you need storage → `asyncpg`** (or `sqlalchemy`
for legacy code). That field names the API style, NOT the storage
backend. `sqlite` or `postgres` there fails at instance start with
`RuntimeError: Unrecognized database type ...` — the storage backend
is chosen at the daemon level via `plugin_databases.{sqlite,postgres}`
in the maubot config and is independent of what the plugin declares.
## Commits