feat: initial monorepo with PRD, 12 ADRs, and plugin skeletons

2026-06-19 18:37:27 -04:00
commit fe434553a8
15 changed files with 599 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Zulip Platform Plugins — Domain Vocabulary
+
+This document captures the shared language and architectural invariants for the multi-platform Zulip agent communication system.
+
+## Domain Terms
+
+| Term | Definition |
+|------|------------|
+| **Agent** | An AI agent operating on a platform (Hermes/Agent Zero/PI/openclaw) that can receive and respond to Zulip messages |
+| **Adapter / Plugin** | A platform-native component that bridges Zulip events to the agent framework |
+| **@mention** | A Zulip mention (`@**Tanko Bot**`) that triggers the named agent to respond |
+| **@all-bots** | A dedicated Zulip bot user that, when @mentioned, triggers ALL agents across all platforms |
+| **Topic** | A Zulip conversation thread within a stream |
+| **Private topic** | An agent-named topic (e.g., `tanko-private`) where only the bot and its owner participate |
+| **Owner** | The human user associated with an agent bot, stored in per-agent config |
+
+## Naming Conventions
+
+- Agent Zulip bot display names: lowercase, dash-separated, `-bot` suffix — e.g., `tanko-bot`, `mumuni-bot`
+- Agent Zulip bot emails: `<name>@chat.sysloggh.net` — e.g., `tanko-bot@chat.sysloggh.net`
+- Private topics: `<agent-name>-private` — e.g., `tanko-private`
+- Owner privacy: agent should never expose owner name to other agents or users
+
+## Agent Registry
+
+| Agent | Platform | Zulip Bot | CT | Private Topic |
+|-------|----------|-----------|-----|---------------|
+| tanko | Hermes (Python) | tanko-bot | amdpve CT 112 | tanko-private |
+| mumuni | Hermes (Python) | mumuni-bot | minipve CT 114 | mumuni-private |
+| koonimo | Hermes (Python) | koonimo-bot | amdpve CT 113 | koonimo-private |
+| koby | Hermes (Python) | koby-bot | amdpve CT 111 | koby-private |
+| kagentz | Agent Zero | kagentz-bot | amdpve CT 105 | kagentz-private |
+| abiba | PI/openclaw (TypeScript) | abiba-bot | amdpve CT 100 | abiba-private |
+
+## @all-bots Resolution
+
+@all-bots refers to all 6 agents across all frameworks (Hermes, Agent Zero, PI/openclaw). When @all-bots is mentioned in any topic:
+
+1. Each per-agent bot receives the event (since they all share `narrow: stream agent-hub`)
+2. Each bot checks: "Is `All Bots` in `mentioned_users`?"
+3. If yes, bot forwards the message to its agent
+4. @all-bots is a **dedicated Zulip bot user** with display name `All Bots` and email `all-bots@chat.sysloggh.net`
+
+## Response Rules
+
+- **Own topic**: Agent always responds (to its private topic)
+- **Collaboration topic** (any topic that isn't a private topic): Agent responds only when @mentioned
+- **@all-bots**: All agents respond
+- **Private topics**: Only the agent owner + bot are participants; bot enforces this
+
+## Monorepo Structure
+
+All 3 platform plugins live in a single Gitea repository at `git@192.168.68.17:homelab/zulip-platform-plugins.git`
+
+## Guardian Directives
+
+- All destructive actions require user confirmation before execution
+- Plugin updates are version-controlled through Gitea
+- Config files are per-agent and pushed alongside code