# 📖 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. ```bash # 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: ```bash 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): ```json { "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 #- #rd-│ │ 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*