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.

```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  #<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*