docs: add HQ multi-agent framework documentation from PKM

- Project plan, agent roster, architecture, roadmap - Decision log, full system plan, Discord setup/migration guides - System implementation status (as-built) - Cluster pivot history - Orchestration engine plan (Phases 1-4) - Webster and Auditor reviews
2026-02-15 21:44:07 +00:00
parent 3289a76e19
commit cf82de4f06
15 changed files with 6933 additions and 0 deletions
--- a/docs/hq/07-DISCORD-MIGRATION.md
+++ b/docs/hq/07-DISCORD-MIGRATION.md
@@ -0,0 +1,105 @@
+
+# 🔄 Discord Migration — Atomizer-HQ
+
+> Migration from Slack to Discord for multi-agent deployment. **COMPLETED 2026-02-14.**
+
+## Why Discord?
+
+- **One bot per agent** — each agent appears as its own Discord user with unique name, avatar, presence
+- **Better role/permission system** — fine-grained channel access per bot
+- **Free** — no per-seat pricing like Slack
+- **Richer interaction** — threads, reactions, embeds, slash commands per bot
+- **Future potential** — could invite external collaborators
+
+## Architecture Evolution
+
+| Aspect | Slack Phase 0 | Bridge Attempt (abandoned) | Multi-Instance Cluster (current) |
+|--------|--------------|---------------------------|----------------------------------|
+| Infrastructure | Single gateway, port 18790 | Single gateway + discord-bridge.js | 8 independent OpenClaw instances |
+| Bot identity | Single bot, display name override | 8 tokens via bridge middleware | 8 native Discord bots |
+| Discord features | N/A | No streaming, no threads, no reactions | Full native support |
+| Fault isolation | All agents share one process | Bridge = single point of failure | Each agent independent |
+| Ports | 18790 | 18790 | 18800–18828 (spaced by 4) |
+
+## Discord Server: Atomizer-HQ
+
+**Guild ID:** 1471858733452890132
+**Antoine's Discord ID:** 719982779793932419
+
+### Server Structure
+
+```
+Atomizer-HQ
+├── 📋 COMMAND
+│   ├── #ceo-office          → Manager (CEO ↔ Manager private)
+│   ├── #announcements        → Manager (read-only for others)
+│   └── #daily-standup        → All agents report
+├── 🔧 ENGINEERING
+│   ├── #technical            → Tech Lead + Optimizer
+│   ├── #code-review          → Tech Lead
+│   ├── #fea-analysis         → Tech Lead + Optimizer
+│   └── #nx-cad               → NX Expert + Tech Lead
+├── 📊 OPERATIONS
+│   ├── #task-board           → Secretary
+│   ├── #meeting-notes        → Secretary
+│   └── #reports              → (future: Reporter)
+├── 🔬 RESEARCH
+│   ├── #literature           → Webster
+│   └── #materials-data       → Webster + Tech Lead
+├── 🏗️ PROJECTS
+│   └── #active-projects      → Manager + relevant agents
+├── 📚 KNOWLEDGE
+│   ├── #knowledge-base       → (future: KB agent)
+│   └── #lessons-learned      → All
+└── 🤖 SYSTEM
+    ├── #agent-logs           → System/debug
+    ├── #inter-agent          → Agent coordination
+    └── #it-ops               → (future: IT agent)
+```
+
+### Roles
+
+| Role | Agents | Permissions |
+|------|--------|-------------|
+| CEO | Antoine | Full admin |
+| Executive | Manager, Tech Lead, Auditor | All channels, manage messages |
+| Professional | Optimizer, Study Builder, NX Expert | Engineering + assigned channels |
+| Support | Secretary | Operations + assigned channels |
+| Research | Webster | Research channels + read engineering |
+
+## Model Tiers
+
+| Tier | Model | Agents |
+|------|-------|--------|
+| Executive | Claude Opus 4.6 | Manager, Tech Lead, Auditor |
+| Professional | Claude Sonnet 4.5 | Optimizer, Study Builder, NX Expert |
+| Support | Claude Haiku 4 | Secretary |
+| Research | Gemini 2.5 Pro | Webster |
+
+## Setup Checklist — COMPLETE ✅
+
+- [x] Discord server created
+- [x] 8 Discord bot applications created
+- [x] Bot tokens stored securely (`~/atomizer/config/.discord-tokens.env`)
+- [x] Categories & channels set up
+- [x] Roles & permissions configured
+- [x] All 8 bots invited to server
+- [x] OpenClaw configs written (one per instance)
+- [x] Systemd template service created
+- [x] Cluster management script (`cluster.sh`)
+- [x] All 8 agents running and responding on Discord
+
+## What Was Tried and Abandoned
+
+### Discord Bridge (discord-bridge.js) — 2026-02-14 AM
+A Node.js middleware using `discord.js` that routed messages between Discord and a single OpenClaw gateway. **Abandoned** because:
+- No streaming (waited for full LLM response)
+- Polled session `.jsonl` files on disk (fragile)
+- Single listener pattern (Manager bot failure = total outage)
+- Lost Discord features (threads, reactions, attachments)
+
+The bridge was replaced same day with the multi-instance cluster approach.
+
+---
+
+*Created: 2026-02-13 by Mario | Completed: 2026-02-14*