Antoine/Atomizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f14cbfd6aaac0391db8d97d0e3b5f1eee7cc612d
Atomizer/hq/workspaces/manager/context-docs/02-ARCHITECTURE.md
Antoine 3289a76e19 feat: add Atomizer HQ multi-agent cluster infrastructure 
- 8-agent OpenClaw cluster (Manager, Tech-Lead, Secretary, Auditor,
  Optimizer, Study-Builder, NX-Expert, Webster)
- Orchestration engine: orchestrate.py (sync delegation + handoffs)
- Workflow engine: YAML-defined multi-step pipelines
- Agent workspaces: SOUL.md, AGENTS.md, MEMORY.md per agent
- Shared skills: delegate, orchestrate, atomizer-protocols
- Capability registry (AGENTS_REGISTRY.json)
- Cluster management: cluster.sh, systemd template
- All secrets replaced with env var references
2026-02-15 21:18:18 +00:00

600 lines
23 KiB
Markdown
Raw Blame History

---
tags:
- Project/Atomizer
- Agentic
- Architecture
up: "[[P-Atomizer-Overhaul-Framework-Agentic/MAP - Atomizer Overhaul Framework Agentic]]"
date: 2026-02-07
status: draft
---
# 🏗️ Architecture — Atomizer Engineering Co.
> Technical architecture: Clawdbot configuration, Slack setup, memory systems, and infrastructure.
---
## 1. Clawdbot Multi-Agent Configuration
### Config Structure (clawdbot.json)
This is the core configuration that makes it all work. Each agent is defined with its own workspace, model, identity, and tools.
```json5
{
agents: {
list: [
// === CORE AGENTS ===
{
id: "manager",
name: "The Manager",
default: false,
workspace: "~/clawd-atomizer-manager",
model: "anthropic/claude-opus-4-6",
identity: {
name: "The Manager",
emoji: "🎯",
},
// Manager sees all project channels
},
{
id: "secretary",
name: "The Secretary",
workspace: "~/clawd-atomizer-secretary",
model: "anthropic/claude-opus-4-6",
identity: {
name: "The Secretary",
emoji: "📋",
},
},
{
id: "technical",
name: "The Technical Lead",
workspace: "~/clawd-atomizer-technical",
model: "anthropic/claude-opus-4-6",
identity: {
name: "The Technical Lead",
emoji: "🔧",
},
},
{
id: "optimizer",
name: "The Optimizer",
workspace: "~/clawd-atomizer-optimizer",
model: "anthropic/claude-opus-4-6",
identity: {
name: "The Optimizer",
emoji: "⚡",
},
},
// === SPECIALISTS (Phase 2) ===
{
id: "nx-expert",
name: "The NX Expert",
workspace: "~/clawd-atomizer-nx-expert",
model: "anthropic/claude-sonnet-5",
identity: {
name: "The NX Expert",
emoji: "🖥️",
},
},
{
id: "postprocessor",
name: "The Post-Processor",
workspace: "~/clawd-atomizer-postprocessor",
model: "anthropic/claude-sonnet-5",
identity: {
name: "The Post-Processor",
emoji: "📊",
},
},
{
id: "reporter",
name: "The Reporter",
workspace: "~/clawd-atomizer-reporter",
model: "anthropic/claude-sonnet-5",
identity: {
name: "The Reporter",
emoji: "📝",
},
},
{
id: "auditor",
name: "The Auditor",
workspace: "~/clawd-atomizer-auditor",
model: "anthropic/claude-opus-4-6",
identity: {
name: "The Auditor",
emoji: "🔍",
},
},
{
id: "study-builder",
name: "The Study Builder",
workspace: "~/clawd-atomizer-study-builder",
model: "openai/gpt-5.3-codex", // or anthropic/claude-opus-4-6
identity: {
name: "The Study Builder",
emoji: "🏗️",
},
},
// === SUPPORT (Phase 3) ===
{
id: "researcher",
name: "The Researcher",
workspace: "~/clawd-atomizer-researcher",
model: "google/gemini-3.0",
identity: {
name: "The Researcher",
emoji: "🔬",
},
},
{
id: "developer",
name: "The Developer",
workspace: "~/clawd-atomizer-developer",
model: "anthropic/claude-sonnet-5",
identity: {
name: "The Developer",
emoji: "💻",
},
},
{
id: "knowledge-base",
name: "The Knowledge Base",
workspace: "~/clawd-atomizer-kb",
model: "anthropic/claude-sonnet-5",
identity: {
name: "The Knowledge Base",
emoji: "🗄️",
},
},
{
id: "it-support",
name: "IT Support",
workspace: "~/clawd-atomizer-it",
model: "anthropic/claude-sonnet-5",
identity: {
name: "IT Support",
emoji: "🛠️",
},
},
],
},
// Route Slack channels to agents
bindings: [
// Manager gets HQ and all project channels
{ agentId: "manager", match: { channel: "slack", peer: { kind: "group", id: "CHID_atomizer_hq" } } },
// Secretary gets its own channel
{ agentId: "secretary", match: { channel: "slack", peer: { kind: "group", id: "CHID_atomizer_secretary" } } },
// Project channels → Manager (who then @mentions specialists)
// Or use thread-based routing once available
// Specialized channels
{ agentId: "researcher", match: { channel: "slack", peer: { kind: "group", id: "CHID_atomizer_research" } } },
{ agentId: "developer", match: { channel: "slack", peer: { kind: "group", id: "CHID_atomizer_dev" } } },
{ agentId: "knowledge-base", match: { channel: "slack", peer: { kind: "group", id: "CHID_atomizer_kb" } } },
],
}
```
> ⚠️ **Note:** The channel IDs (`CHID_*`) are placeholders. Replace with actual Slack channel IDs after creating them.
### Key Architecture Decision: Single Gateway vs Multiple
**Recommendation: Single Gateway, Multiple Agents**
One Clawdbot gateway process hosting all agents. Benefits:
- Shared infrastructure (one process to manage)
- `sessions_send` for inter-agent communication
- `sessions_spawn` for sub-agent heavy lifting
- Single config file to manage
If resource constraints become an issue later, we can split into multiple gateways on different machines.
---
## 2. Workspace Layout
Each agent gets a workspace following Clawdbot conventions:
```
~/clawd-atomizer-manager/
├── AGENTS.md ← Operating instructions, protocol rules
├── SOUL.md ← Personality, tone, boundaries
├── TOOLS.md ← Local tool notes
├── MEMORY.md ← Long-term role-specific memory
├── IDENTITY.md ← Name, emoji, avatar
├── memory/ ← Per-project memory files
│ ├── starspec-wfe-opt.md
│ └── client-b-thermal.md
└── skills/ ← Agent-specific skills
└── (agent-specific)
```
### Shared Skills (all agents)
```
~/.clawdbot/skills/
├── atomizer-protocols/ ← Company protocols
│ ├── SKILL.md
│ ├── QUICK_REF.md ← One-page cheatsheet
│ └── protocols/
│ ├── OP_01_study_lifecycle.md
│ ├── OP_02_...
│ └── SYS_18_...
└── atomizer-company/ ← Company identity + shared knowledge
├── SKILL.md
└── COMPANY.md ← Who we are, how we work, agent directory
```
### Workspace Bootstrap Script
```bash
#!/bin/bash
# create-agent-workspace.sh <agent-id> <agent-name> <emoji>
AGENT_ID=$1
AGENT_NAME=$2
EMOJI=$3
DIR=~/clawd-atomizer-$AGENT_ID
mkdir -p $DIR/memory $DIR/skills
cat > $DIR/IDENTITY.md << EOF
# IDENTITY.md
- **Name:** $AGENT_NAME
- **Emoji:** $EMOJI
- **Role:** Atomizer Engineering Co. — $AGENT_NAME
- **Company:** Atomizer Engineering Co.
EOF
cat > $DIR/SOUL.md << EOF
# SOUL.md — $AGENT_NAME
You are $AGENT_NAME at Atomizer Engineering Co., a multi-agent FEA optimization firm.
## Core Rules
- Follow all Atomizer protocols (see atomizer-protocols skill)
- Respond when @-mentioned in Slack channels
- Stay in your lane — delegate outside your expertise
- Update your memory after significant work
- Be concise in Slack — expand in documents
## Communication
- In Slack: concise, structured, use threads
- For reports/documents: thorough, professional
- When uncertain: ask, don't guess
EOF
cat > $DIR/AGENTS.md << EOF
# AGENTS.md — $AGENT_NAME
## Session Init
1. Read SOUL.md
2. Read MEMORY.md
3. Check memory/ for active project context
4. Check which channel/thread you're in for context
## Memory
- memory/*.md = per-project notes
- MEMORY.md = role-specific long-term knowledge
- Write down lessons learned after every project
## Protocols
Load the atomizer-protocols skill for protocol reference.
EOF
cat > $DIR/MEMORY.md << EOF
# MEMORY.md — $AGENT_NAME
## Role Knowledge
*(To be populated as the agent works)*
## Lessons Learned
*(Accumulated over time)*
EOF
echo "Created workspace: $DIR"
```
---
## 3. Slack Workspace Architecture
### Dedicated Slack Workspace: "Atomizer Engineering"
**This gets its own Slack workspace** — separate from Antoine's personal workspace. Professional, clean, product-ready for video content and demos.
**Workspace name:** `Atomizer Engineering` (or `atomizer-eng.slack.com`)
### Permanent Channels
| Channel | Purpose | Bound Agent | Who's There |
|---------|---------|-------------|-------------|
| `#hq` | Company coordination, general discussion | Manager | All agents can be summoned |
| `#secretary` | Antoine's dashboard, directives | Secretary | Secretary + Antoine |
| `#research` | Research requests and findings | Researcher | Researcher, anyone can ask |
| `#dev` | Development and coding work | Developer | Developer, Manager |
| `#knowledge-base` | Knowledge base maintenance | Knowledge Base | KB Agent, anyone can ask |
| `#audit-log` | Auditor findings and reviews | Auditor | Auditor, Manager |
### Project Channels (Created Per Client Job)
**Naming convention:** `#<client>-<short-description>`
Examples:
- `#starspec-m1-wfe`
- `#clientb-thermal-opt`
### R&D / Development Channels
For developing new Atomizer capabilities — vibration tools, fatigue analysis, non-linear methods, new extractors, etc. Antoine works directly with agents here to explore, prototype, and build.
**Naming convention:** `#rd-<topic>`
| Channel | Purpose | Key Agents |
|---------|---------|------------|
| `#rd-vibration` | Develop vibration/modal analysis tools | Technical Lead, Developer, Researcher |
| `#rd-fatigue` | Fatigue analysis capabilities | Technical Lead, Developer, NX Expert |
| `#rd-nonlinear` | Non-linear solver integration | Technical Lead, NX Expert, Researcher |
| `#rd-surrogates` | GNN/surrogate model improvements | Optimizer, Developer, Researcher |
| `#rd-extractors` | New data extractors | Developer, Post-Processor, Study Builder |
**How R&D channels work:**
1. Antoine creates `#rd-<topic>` and posts the idea or problem
2. Manager routes to Technical Lead as the R&D point person
3. Technical Lead breaks down the R&D challenge, consults with Researcher for state-of-the-art
4. Developer prototypes, Auditor validates, Antoine reviews and steers
5. Once mature → becomes a standard capability (new protocol, new extractor, new skill)
6. Manager (as Framework Steward) ensures it's properly integrated into the Atomizer framework
**Antoine's role in R&D channels:**
- Ask questions, poke around, explore ideas
- The agents are his collaborators, not just executors
- Technical Lead acts as the R&D conversation partner — understands the engineering, translates to actionable dev work
- Antoine can say "what if we tried X?" and the team runs with it
**Lifecycle:**
1. Antoine or Manager creates channel
2. Manager is invited (auto-bound)
3. Manager invites relevant agents as needed
4. After project completion: archive channel
### Thread Discipline
Within project channels, use threads for:
- Each distinct task or subtask
- Agent-to-agent technical discussion
- Review cycles (auditor feedback → fixes → re-review)
Main channel timeline should read like a project log:
```
[Manager] 🎯 Project kickoff: StarSpec M1 WFE optimization
[Technical] 🔧 Technical breakdown complete → [thread]
[Optimizer] ⚡ Algorithm recommendation → [thread]
[Manager] 🎯 Study approved. Launching optimization.
[Post-Processor] 📊 Results ready, 23% WFE improvement → [thread]
[Auditor] 🔍 Audit PASSED with 2 notes → [thread]
[Reporter] 📝 Report draft ready for review → [thread]
[Secretary] 📋 @antoine — Report ready, please review
```
---
## 4. Inter-Agent Communication
### Primary: Slack @Mentions
Agents communicate by @-mentioning each other in project channels:
```
Manager: "@technical, new job. Break down the attached requirements."
Technical: "@manager, breakdown complete. Recommending @optimizer review the parameter space."
Manager: "@optimizer, review Technical's breakdown in this thread."
```
### Secondary: sessions_send (Direct)
For urgent or private communication that shouldn't be in Slack:
```
sessions_send(agentId: "auditor", message: "Emergency: results look non-physical...")
```
### Tertiary: sessions_spawn (Heavy Tasks)
For compute-heavy work that shouldn't block the agent:
```
sessions_spawn(agentId: "postprocessor", task: "Generate full Zernike decomposition for trial 47-95...")
```
### Communication Rules
1. **All project communication in project channels** (traceability)
2. **Technical discussions in threads** (keep channels clean)
3. **Only Manager initiates cross-agent work** (except Secretary → Antoine)
4. **Auditor can interrupt any thread** (review authority)
5. **sessions_send for emergencies only** (not routine)
---
## 5. Memory System Implementation
### Company Memory (Shared Skill)
```
~/.clawdbot/skills/atomizer-protocols/
├── SKILL.md
│ description: "Atomizer Engineering Co. protocols and procedures"
│ read_when: "Working on any Atomizer project"
├── QUICK_REF.md ← Most agents load this
├── COMPANY.md ← Company identity, values, how we work
├── protocols/
│ ├── OP_01_study_lifecycle.md
│ ├── OP_02_study_creation.md
│ ├── OP_03_optimization.md
│ ├── OP_04_results.md
│ ├── OP_05_reporting.md
│ ├── OP_06_troubleshooting.md
│ ├── OP_07_knowledge.md
│ ├── OP_08_delivery.md
│ ├── SYS_10_file_management.md
│ ├── SYS_11_nx_sessions.md
│ ├── SYS_12_solver_config.md
│ ├── SYS_13_extractors.md
│ ├── SYS_14_hooks.md
│ ├── SYS_15_surrogates.md
│ ├── SYS_16_dashboard.md
│ ├── SYS_17_insights.md
│ └── SYS_18_validation.md
└── lac/
├── critical_lessons.md ← Hard-won insights from LAC
└── algorithm_guide.md ← When to use which algorithm
```
### Agent Memory Lifecycle
```
New Project Starts
│
├─ Agent reads: MEMORY.md (long-term knowledge)
├─ Agent checks: memory/<project>.md (if returning to existing project)
│
├─ During project: updates memory/<project>.md with decisions, findings
│
└─ Project Ends
├─ Agent distills lessons → updates MEMORY.md
└─ memory/<project>.md archived (kept for reference)
```
### Cross-Agent Knowledge Sharing
Agents share knowledge through:
1. **Slack channels** — conversations are visible to all invited agents
2. **Shared skill files** — updated protocols/lessons accessible to all
3. **Git repo** — Atomizer repo synced via Syncthing
4. **KB Agent** — can be asked "what do we know about X?"
---
## 6. Infrastructure Diagram
```
┌────────────────────────────────────────────────────────────────┐
│ CLAWDBOT SERVER (Linux) │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Clawdbot Gateway │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │Manager │ │Secretary│ │Technical│ │Optimizer│ │ │
│ │ │Agent │ │Agent │ │Agent │ │Agent │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ │ │ │ │ │ │ │
│ │ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │ │
│ │ │NX Expert│ │PostProc │ │Reporter │ │Auditor │ │ │
│ │ │Agent │ │Agent │ │Agent │ │Agent │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ + Researcher, Developer, KB, IT │ │
│ └──────────────────────┬────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼────────────────────────────────┐ │
│ │ Shared Resources │ │
│ │ /home/papa/repos/Atomizer/ (Git, via Syncthing) │ │
│ │ /home/papa/obsidian-vault/ (PKM, via Syncthing) │ │
│ │ /home/papa/ATODrive/ (Work docs) │ │
│ │ ~/.clawdbot/skills/atomizer-*/ (Shared skills) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ Syncthing │
│ │ │
└─────────────────────────┼───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ WINDOWS (Antoine's PC) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ NX/Simcenter │ │ Claude Code │ │ Atomizer │ │
│ │ (FEA Solver) │ │ (Local) │ │ Dashboard │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ Study files synced to Linux via Syncthing │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SLACK WORKSPACE │
│ │
│ #hq #secretary #<client>-<project> #rd-<topic> │
│ #research #dev #knowledge-base #audit-log │
│ │
│ All agents have Slack accounts via Clawdbot │
└─────────────────────────────────────────────────────────────────┘
```
---
## 7. Security & Isolation
### Agent Access Boundaries
| Agent | File Access | External Access | Special Permissions |
|-------|------------|-----------------|---------------------|
| Manager | Read Atomizer repo, PKM projects | Slack only | Can spawn sub-agents |
| Secretary | Read PKM, ATODrive | Slack + Email (draft only) | Can message Antoine directly |
| Technical | Read Atomizer repo, PKM projects | Slack only | — |
| Optimizer | Read/write study configs | Slack only | — |
| NX Expert | Read Atomizer repo, NX docs | Slack only | — |
| Post-Processor | Read study results, write plots | Slack only | — |
| Reporter | Read results, write reports | Slack + Email (with approval) | Atomaste report skill |
| Auditor | Read everything (audit scope) | Slack only | Veto power on deliverables |
| Researcher | Read Atomizer repo | Slack + Web search | Internet access |
| Developer | Read/write Atomizer repo | Slack only | Git operations |
| KB | Read/write PKM knowledge folders | Slack only | CAD Documenter skill |
| IT | Read system status | Slack only | System diagnostics |
### Principle of Least Privilege
- No agent has SSH access to external systems
- Email sending requires Antoine's approval (enforced in Secretary + Reporter AGENTS.md)
- Only Developer can write to the Atomizer repo
- Only Reporter + Secretary can draft client communications
- Auditor has read-all access (necessary for audit role)
---
## 8. Cost Estimation
### Per-Project Estimate (Typical Optimization Job)
| Phase | Agents Active | Estimated Turns | Estimated Cost |
|-------|--------------|-----------------|----------------|
| Intake | Manager, Technical, Secretary | ~10 turns | ~$2-4 |
| Planning | Technical, Optimizer, NX Expert | ~15 turns | ~$5-8 |
| Execution | Optimizer, Post-Processor | ~20 turns | ~$6-10 |
| Analysis | Post-Processor, Auditor | ~15 turns | ~$5-8 |
| Reporting | Reporter, Auditor, Secretary | ~10 turns | ~$4-6 |
| **Total** | | **~70 turns** | **~$22-36** |
*Based on current Anthropic API pricing for Opus 4.6 / Sonnet 5 with typical context lengths.*
### Cost Optimization Strategies
1. **Wake-on-demand:** Agents only activate when @-mentioned
2. **Tiered models:** Support agents on cheaper models
3. **Sub-agent timeouts:** `runTimeoutSeconds` prevents runaway sessions
4. **Session archiving:** Auto-archive after 60 minutes of inactivity
5. **Context management:** Keep AGENTS.md lean, load skills on-demand
6. **Batch operations:** Secretary batches questions instead of individual pings
---
*Created: 2026-02-07 by Mario*
Reference in New Issue View Git Blame Copy Permalink