Atomizer/docs/hq/README-ANTOINE.md

📖 README — Antoine's Implementation Guide

Everything you need to do to bring Atomizer Engineering Co. to life. Mario handles agent workspaces, configs, SOUL files, and Docker setup. You handle Slack creation and the stuff only a human can do.

Last updated: 2026-02-08 — All decisions resolved ✅

---

Quick Overview

What we're building: A dedicated Slack workspace where 13 AI agents operate as a specialized FEA optimization company. Each agent has its own personality, model, memory, and tools. You're the CEO.

How it runs: A separate Clawdbot gateway runs in Docker on the T420, alongside your existing Mario instance. Completely isolated — own config, own Slack workspace, own port. Mario stays untouched.

Phased rollout:

• Phase 0 (Week 1-2): Manager + Secretary + Technical Lead — prove the pattern
• Phase 1 (Week 3-4): + Optimizer + Study Builder + Auditor — full planning + execution
• Phase 2 (Week 5-7): + NX Expert, Post-Processor, Reporter, KB — full pipeline
• Phase 3 (Week 8-10): + Researcher, Developer, IT — complete company

---

All Decisions — Resolved ✅

ID	Decision	Status
DEC-A001	Use Clawdbot Multi-Agent (not Agent Zero)	✅
DEC-A002	Phased rollout (not big bang)	✅
DEC-A003	Manager as communication bottleneck	✅
DEC-A004	Single gateway, multiple agents	✅
DEC-A006	Dedicated Slack workspace	✅
DEC-A007	Study Builder agent (separate from Optimizer)	✅
DEC-A008	Use latest models (Sonnet 5, Codex 5.3, Gemini 3.0)	✅
DEC-A009	Autonomy with approval gates	✅
DEC-A010	Framework Steward = Manager sub-role	✅
DEC-A011	Syncthing + manual run_optimization.py launch	✅
DEC-A012	Separate Clawdbot gateway in Docker	✅
DEC-A013	Single bot, per-agent identity (organic UX)	✅
DEC-A014	Semi-auto KB ingestion + inherited CAD Documenter skill	✅

Full details in 04-DECISION-LOG.

---

Phase 0: Setup Checklist

What YOU do (Antoine)

Step 1: Install Docker on T420 (10 min)

Docker is not currently installed. We need it for the Atomizer gateway.

# SSH into T420 or run locally
sudo apt update
sudo apt install docker.io docker-compose-v2 -y
sudo usermod -aG docker papa
# Log out and back in (or reboot) for group to take effect

Verify:

docker --version
docker compose version

💡 If you'd rather I walk you through this step-by-step, just say the word.

Step 2: Create the Slack Workspace (30 min)

1. Go to https://slack.com/create
2. Create workspace:
   • Name: `Atomizer-HQ (or your preferred name)
   • URL: Something clean like atomizer-eng.slack.com
3. You're the workspace owner

Step 3: Create the Slack App (20 min)

1. Go to https://api.slack.com/apps
2. Click Create New App → From a manifest
3. Select your Atomizer Engineering workspace
4. Paste this manifest (JSON tab):

{
  "display_information": {
    "name": "Atomizer",
    "description": "Atomizer Engineering Co. — AI Agent System"
  },
  "features": {
    "bot_user": {
      "display_name": "Atomizer",
      "always_online": true
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "chat:write.customize",
        "channels:history",
        "channels:read",
        "channels:manage",
        "groups:history",
        "groups:read",
        "groups:write",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "users:read",
        "app_mentions:read",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "reaction_added",
        "reaction_removed",
        "member_joined_channel",
        "member_left_channel",
        "channel_rename",
        "pin_added",
        "pin_removed"
      ]
    }
  }
}

⚠️ Note the chat:write.customize scope — this is what allows the bot to post with different display names per agent (🎯 Manager, 📋 Secretary, etc.). This is how we get organic multi-agent identity from a single bot.

5. Click Create
6. Go to Socket Mode → toggle ON
7. Go to Basic Information → App-Level Tokens → Generate Token and Scopes:
   • Name: clawdbot-socket
   • Scope: connections:write
   • Click Generate
   • Copy the xapp-... token ← save this
8. Go to OAuth & Permissions → Install to Workspace → Allow
   • Copy the xoxb-... Bot Token ← save this

Step 4: Create Initial Channels (5 min)

In the Atomizer Engineering workspace:

Channel	Purpose
#hq	Company coordination — Manager's home
#secretary	Your private dashboard

Invite the bot to both: /invite @Atomizer

Step 5: Give Me the Tokens (2 min)

Send me in our private DM (not here):

• App Token (xapp-...)
• Bot Token (xoxb-...)
• Channel IDs for #hq and #secretary

To find channel IDs: right-click channel name → "View channel details" → scroll to bottom → copy the ID (starts with C).

🔒 Tokens go into Docker environment variables — never stored in plain text files.

---

What MARIO does (you don't need to do any of this)

Infrastructure

• Set up /opt/atomizer/ directory structure
• Write docker-compose.yml for Atomizer gateway
• Configure .env with API keys + Slack tokens
• Set up Syncthing folder for job queue

Agent Workspaces (Phase 0: 3 agents)

• Create Manager workspace + SOUL.md + AGENTS.md + MEMORY.md
• Create Secretary workspace + SOUL.md + AGENTS.md + MEMORY.md
• Create Technical Lead workspace + SOUL.md + AGENTS.md + MEMORY.md
• Write IDENTITY.md for each (name, emoji, personality)

Shared Skills

• Create atomizer-protocols skill from existing protocol docs
• Create atomizer-company skill (identity, values, agent directory)

Configuration

• Write clawdbot.json multi-agent config
• Set up Slack channel bindings (channel IDs → agents)
• Configure per-agent models

Testing

• Boot Docker container, verify gateway starts
• Test: message in #hq → Manager responds
• Test: message in #secretary → Secretary responds
• Test: Manager delegates to Technical Lead
• Test: agent identity shows correctly (name + emoji per message)
• Run a real engineering problem through 3 agents

---

Architecture at a Glance

┌────────────────────── T420 ──────────────────────┐
│                                                   │
│  Mario's Clawdbot          Atomizer (Docker)      │
│  (systemd, port 18789)     (Docker, port 18790)   │
│  Personal Slack ←→ you     Atomizer Slack ←→ you  │
│  Your assistant             Your FEA company      │
│                                                   │
│  Shared (read-only by Atomizer):                  │
│  • /home/papa/repos/Atomizer/                     │
│  • /home/papa/obsidian-vault/                     │
│                                                   │
│  Atomizer-only:                                   │
│  • /opt/atomizer/workspaces/ (agent files)        │
│  • /opt/atomizer/job-queue/  (↔ Windows)          │
└───────────────────────────────────────────────────┘
                      │
                Syncthing
                      │
┌─────────────── Windows (dalidou) ─────────────────┐
│  NX/Simcenter + Atomizer repo + job-queue         │
│  You run: python run_optimization.py              │
└───────────────────────────────────────────────────┘
                      │
┌─────────────── Slack (Atomizer Eng.) ─────────────┐
│  #hq  #secretary  #<client>-<project>  #rd-<topic>│
│  13 agents, each with own name + emoji            │
│  Single bot, organic multi-identity UX            │
└───────────────────────────────────────────────────┘

---

The 13 Agents

#	Agent	Emoji	Model	Phase	Role
1	Manager	🎯	Opus 4.6	0	Orchestrates, delegates, enforces protocols
2	Secretary	📋	Opus 4.6	0	Your interface — filters, summarizes, escalates
3	Technical Lead	🔧	Opus 4.6	0	Breaks down problems, leads R&D
4	Optimizer	⚡	Opus 4.6	1	Algorithm selection, strategy design
5	Study Builder	🏗️	GPT-5.3-Codex	1	Writes run_optimization.py
6	Auditor	🔍	Opus 4.6	1	Validates physics, challenges assumptions
7	NX Expert	🖥️	Sonnet 5	2	NX Nastran/NX Open deep knowledge
8	Post-Processor	📊	Sonnet 5	2	Data analysis, graphs, result validation
9	Reporter	📝	Sonnet 5	2	Professional Atomaste-branded PDF reports
10	Knowledge Base	🗄️	Sonnet 5	2	CAD docs, FEM knowledge, component library
11	Researcher	🔬	Gemini 3.0	3	Literature search, state-of-the-art
12	Developer	💻	Sonnet 5	3	Codes new tools, extends framework
13	IT Support	🛠️	Sonnet 5	3	Licenses, server health, infrastructure

---

How You'll Interact

Start a project: Create #starspec-wfe-opt → post requirements → Manager takes over

Give directives: Post in #hq (company-wide) or any project channel

R&D: Create #rd-vibration → Technical Lead drives exploration with you

Approve deliverables: Secretary escalates → you review → say "approved" or give feedback

@ any agent directly: Organic, natural — like messaging a coworker

---

Cost Estimates

Phase	Monthly API Cost
Phase 0 (3 agents)	~$50
Phase 1 (6 agents)	~$100-150
Phase 2 (10 agents)	~$200-250
Phase 3 (13 agents)	~$300-400
Per client job	~$25-40

---

Ready?

Your checklist is 5 steps. Total time: ~1-1.5 hours. Once you give me the tokens and channel IDs, I build the rest.

Let's build this. 🏭

---

Prepared by Mario — 2026-02-08