Antoine/Atomizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cf82de4f06ce1f58ebf2e42e8bd94d787696e0e2
Atomizer/docs/hq/05-FULL-SYSTEM-PLAN.md

2319 lines
80 KiB
Markdown
Raw Normal View History

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
# 🏭 05 — Full System Plan: Implementation Blueprint
> This is THE definitive implementation blueprint for Atomizer Engineering Co.
> The design docs (00–04) say WHAT we're building. This document says HOW, step by step, with actual configs, scripts, and commands.
---
## Table of Contents
1. [Infrastructure & Docker](#1-infrastructure--docker)
2. [Framework Rewrite Strategy](#2-framework-rewrite-strategy)
3. [Agent Workspaces](#3-agent-workspaces-detailed)
4. [Slack Architecture](#4-slack-architecture)
5. [Windows Execution Bridge](#5-windows-execution-bridge)
6. [Inter-Agent Communication](#6-inter-agent-communication)
7. [Mario ↔ Atomizer Bridge](#7-mario--atomizer-bridge)
8. [Phase 0 Implementation Checklist](#8-phase-0-implementation-checklist)
9. [Security](#9-security)
10. [Future-Proofing](#10-future-proofing)
---
## 1. Infrastructure & Docker
### 1.1 Coexistence Model: Mario + Atomizer on T420
Mario's Clawdbot currently runs natively via systemd on the T420:
```
Service: ~/.config/systemd/user/clawdbot-gateway.service
Binary: /usr/bin/clawdbot
Config: ~/.clawdbot/clawdbot.json
Port: 18789 (loopback)
User: papa
```
**Decision (ref DEC-A012):** Atomizer gets a **separate Clawdbot gateway** in Docker. This provides:
- Complete workspace isolation (no file cross-contamination)
- Independent config, models, bindings
- Can restart/upgrade independently
- Mario never sees Atomizer agent traffic; Atomizer agents never see Mario's memory
```
┌────────────────────── T420 (papa@clawdbot) ──────────────────────┐
│ │
│ ┌─────────────────────┐ ┌──────────────────────────────────┐ │
│ │ Mario's Clawdbot │ │ Atomizer Clawdbot (Docker) │ │
│ │ (systemd native) │ │ │ │
│ │ Port: 18789 │ │ Port: 18790 │ │
│ │ Slack: personal │ │ Slack: atomizer-eng workspace │ │
│ │ Config: ~/.clawdbot│ │ Config: /opt/atomizer/clawdbot │ │
│ └─────────────────────┘ └──────────────────────────────────┘ │
│ │
│ ┌───────────────── Shared (read-only by Atomizer) ────────────┐ │
│ │ /home/papa/repos/Atomizer/ (Syncthing) │ │
│ │ /home/papa/obsidian-vault/ (Syncthing) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────── Atomizer-Only ─────────────────────────────┐ │
│ │ /opt/atomizer/workspaces/ (agent workspaces) │ │
│ │ /opt/atomizer/shared-skills/ (company protocols) │ │
│ │ /opt/atomizer/job-queue/ (Syncthing ↔ Windows) │ │
│ └─────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘
```
### 1.2 Directory Structure
```bash
/opt/atomizer/
├── docker-compose.yml
├── .env # API keys, tokens
├── clawdbot/ # Clawdbot config for Atomizer gateway
│ ├── clawdbot.json # Multi-agent config
│ ├── credentials/ # Auth tokens
│ └── skills/ # Shared skills (all agents)
│ ├── atomizer-protocols/
│ │ ├── SKILL.md
│ │ ├── QUICK_REF.md
│ │ └── protocols/
│ │ ├── OP_01_study_lifecycle.md
│ │ ├── ... (OP_01–OP_08)
│ │ ├── SYS_10_imso.md
│ │ └── ... (SYS_10–SYS_18)
│ └── atomizer-company/
│ ├── SKILL.md
│ ├── COMPANY.md # Identity, values, agent directory
│ └── LAC_CRITICAL.md # Hard-won lessons from LAC
├── workspaces/ # Per-agent workspaces
│ ├── manager/
│ ├── secretary/
│ ├── technical/
│ ├── optimizer/
│ ├── nx-expert/
│ ├── postprocessor/
│ ├── reporter/
│ ├── auditor/
│ ├── study-builder/
│ ├── researcher/
│ ├── developer/
│ ├── knowledge-base/
│ └── it-support/
├── job-queue/ # Syncthing ↔ Windows execution bridge
│ ├── pending/
│ ├── running/
│ ├── completed/
│ └── failed/
└── data/ # Persistent data
├── sessions/ # Clawdbot session storage
└── logs/ # Gateway logs
```
### 1.3 Docker Compose
```yaml
# /opt/atomizer/docker-compose.yml
version: "3.9"
services:
atomizer-gateway:
image: ghcr.io/clawdbot/clawdbot:latest
container_name: atomizer-gateway
restart: unless-stopped
ports:
- "127.0.0.1:18790:18790" # Gateway (loopback only)
environment:
- CLAWDBOT_GATEWAY_PORT=18790
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- GOOGLE_API_KEY=${GOOGLE_API_KEY}
volumes:
# Clawdbot config
- ./clawdbot:/home/clawdbot/.clawdbot
# Agent workspaces
- ./workspaces/manager:/home/clawdbot/clawd-atomizer-manager
- ./workspaces/secretary:/home/clawdbot/clawd-atomizer-secretary
- ./workspaces/technical:/home/clawdbot/clawd-atomizer-technical
- ./workspaces/optimizer:/home/clawdbot/clawd-atomizer-optimizer
- ./workspaces/nx-expert:/home/clawdbot/clawd-atomizer-nx-expert
- ./workspaces/postprocessor:/home/clawdbot/clawd-atomizer-postprocessor
- ./workspaces/reporter:/home/clawdbot/clawd-atomizer-reporter
- ./workspaces/auditor:/home/clawdbot/clawd-atomizer-auditor
- ./workspaces/study-builder:/home/clawdbot/clawd-atomizer-study-builder
- ./workspaces/researcher:/home/clawdbot/clawd-atomizer-researcher
- ./workspaces/developer:/home/clawdbot/clawd-atomizer-developer
- ./workspaces/knowledge-base:/home/clawdbot/clawd-atomizer-kb
- ./workspaces/it-support:/home/clawdbot/clawd-atomizer-it
# Shared read-only mounts
- /home/papa/repos/Atomizer:/mnt/atomizer-repo:ro
- /home/papa/obsidian-vault:/mnt/obsidian:ro
# Job queue (read-write, synced to Windows)
- ./job-queue:/mnt/job-queue
# Persistent data
- ./data/sessions:/home/clawdbot/.clawdbot/agents
- ./data/logs:/tmp/clawdbot
networks:
- atomizer-net
# Tailscale sidecar for Windows SSH access
# depends_on:
# - tailscale # Enable when Tailscale fast lane is needed
# Optional: Tailscale container for direct Windows access
# tailscale:
# image: tailscale/tailscale:latest
# container_name: atomizer-tailscale
# hostname: atomizer-docker
# volumes:
# - ./data/tailscale:/var/lib/tailscale
# environment:
# - TS_AUTHKEY=${TAILSCALE_AUTH_KEY}
# - TS_STATE_DIR=/var/lib/tailscale
# cap_add:
# - NET_ADMIN
# - SYS_MODULE
# networks:
# - atomizer-net
networks:
atomizer-net:
driver: bridge
```
### 1.4 Environment File
```bash
# /opt/atomizer/.env
# API Keys (same as Mario's — shared subscription)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...
# Slack (Atomizer Engineering workspace — DIFFERENT from Mario's)
SLACK_BOT_TOKEN=xoxb-atomizer-...
SLACK_APP_TOKEN=xapp-atomizer-...
# Optional: Tailscale for Windows SSH
# TAILSCALE_AUTH_KEY=tskey-auth-...
```
### 1.5 Syncthing Integration
Current Syncthing topology:
```
Windows (dalidou) ←→ T420 (clawdbot)
│
├── /home/papa/repos/Atomizer/ ← repo sync (existing)
├── /home/papa/obsidian-vault/ ← PKM sync (existing)
└── /opt/atomizer/job-queue/ ← NEW: execution bridge
```
**New Syncthing folder for job queue:**
| Setting | Value |
|---------|-------|
| Folder ID | `atomizer-job-queue` |
| Local path (T420) | `/opt/atomizer/job-queue/` |
| Local path (Windows) | `C:\Atomizer\job-queue\` |
| Sync direction | Send & Receive |
| Ignore patterns | `*.tmp`, `*.lock` |
Setup command (T420 side):
```bash
mkdir -p /opt/atomizer/job-queue/{pending,running,completed,failed}
# Add via Syncthing web UI at http://127.0.0.1:8384
# or via Syncthing CLI if available
```
### 1.6 Startup & Management
```bash
# Start Atomizer company
cd /opt/atomizer
docker compose up -d
# View logs
docker compose logs -f atomizer-gateway
# Restart after config changes
docker compose restart atomizer-gateway
# Stop everything
docker compose down
# Check health
curl -s http://127.0.0.1:18790/health || echo "Gateway not responding"
```
Optional systemd service wrapper:
```ini
# /etc/systemd/system/atomizer-company.service
[Unit]
Description=Atomizer Engineering Co. (Clawdbot Multi-Agent)
After=docker.service syncthing.service
Requires=docker.service
[Service]
Type=simple
WorkingDirectory=/opt/atomizer
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
Restart=always
RestartSec=10
User=papa
[Install]
WantedBy=multi-user.target
```
---
## 2. Framework Rewrite Strategy
### 2.1 What Stays (Core Engine)
These are battle-tested and should NOT be rewritten — only wrapped for agent access:
| Component | Path | Status |
|-----------|------|--------|
| Optimization engine | `optimization_engine/core/` | ✅ Keep as-is |
| AtomizerSpec v2.0 | `optimization_engine/config/` | ✅ Keep as-is |
| All extractors (20+) | `optimization_engine/extractors/` | ✅ Keep as-is |
| NX integration | `optimization_engine/nx/` | ✅ Keep as-is |
| Study management | `optimization_engine/study/` | ✅ Keep as-is |
| GNN surrogate | `optimization_engine/gnn/` | ✅ Keep as-is |
| Dashboard | `atomizer-dashboard/` | ✅ Keep as-is |
| Trial manager | `optimization_engine/utils/` | ✅ Keep as-is |
| LAC system | `knowledge_base/lac.py` | 🔄 Evolve (see 2.4) |
### 2.2 What Gets Reworked
#### Documentation Reorganization (165 files → clean two-layer system)
The current `docs/` is a sprawl of 165 files across 15+ subdirectories. Many are outdated, duplicated, or overly context-specific to a single Claude Code session.
**Target structure:**
```
docs/ # REFERENCE — stable, curated, agent-readable
├── 00_INDEX.md # Master index
├── QUICK_REF.md # 2-page cheatsheet (keep existing)
├── ARCHITECTURE.md # System architecture (keep, update)
├── GETTING_STARTED.md # Onboarding (keep, update)
├── protocols/ # Protocol Operating System (keep all)
│ ├── operations/OP_01–OP_08
│ ├── system/SYS_10–SYS_18
│ └── extensions/EXT_01–EXT_04
├── api/ # NX Open, Nastran references (keep)
│ ├── nx_integration.md
│ ├── NX_FILE_STRUCTURE_PROTOCOL.md
│ └── NXOPEN_RESOURCES.md
├── physics/ # Physics references (keep)
│ ├── ZERNIKE_FUNDAMENTALS.md
│ ├── ZERNIKE_TRAJECTORY_METHOD.md
│ └── ZERNIKE_OPD_METHOD.md
├── extractors/ # Extractor catalog (merge from generated/)
│ ├── EXTRACTOR_CHEATSHEET.md
│ └── EXTRACTORS.md
└── templates/ # Study templates reference
└── TEMPLATES.md
knowledge_base/ # LIVING MEMORY — grows with every project
├── lac/ # Learning Atomizer Core
│ ├── optimization_memory/ # Per-geometry-type outcomes
│ │ ├── bracket.jsonl
│ │ ├── beam.jsonl
│ │ └── mirror.jsonl
│ └── session_insights/ # Categorized lessons
│ ├── failure.jsonl
│ ├── success_pattern.jsonl
│ ├── workaround.jsonl
│ └── protocol_clarification.jsonl
├── projects/ # Per-project knowledge (NEW)
│ ├── starspec-m1/
│ │ ├── CONTEXT.md # Project context for agents
│ │ ├── model-knowledge.md # CAD/FEM details from KB agent
│ │ └── decisions.md # Key decisions made
│ └── (future projects...)
└── company/ # Company-wide evolving knowledge (NEW)
├── algorithm-selection.md # When to use which algorithm
├── common-pitfalls.md # Hard-won lessons
└── client-patterns.md # Common client needs
```
**Files to archive (move to `docs/archive/`):**
- All `docs/development/` — internal dev notes, dashboad gap analysis, etc.
- All `docs/plans/` — planning docs that are now implemented
- All `docs/guides/` dashboard-specific docs — consolidate into one dashboard guide
- All `docs/reviews/` — one-time reviews
- All `docs/logs/` — implementation logs
- `docs/CONTEXT_ENGINEERING_REPORT.md` — ACE is now part of the system, report archived
- `docs/diagrams/` — merge relevant ones into ARCHITECTURE.md
**Migration script:**
```bash
#!/bin/bash
# reorganize-docs.sh — Run from Atomizer repo root
ARCHIVE=docs/archive/$(date +%Y%m%d)_pre_agentic
mkdir -p $ARCHIVE
# Move sprawl to archive
mv docs/development/ $ARCHIVE/
mv docs/plans/ $ARCHIVE/
mv docs/reviews/ $ARCHIVE/
mv docs/logs/ $ARCHIVE/
mv docs/diagrams/ $ARCHIVE/
mv docs/CONTEXT_ENGINEERING_REPORT.md $ARCHIVE/
mv docs/ROADMAP/ $ARCHIVE/
mv docs/handoff/ $ARCHIVE/
mv docs/guides/DASHBOARD_*.md $ARCHIVE/
mv docs/guides/NEURAL_*.md $ARCHIVE/
mv docs/guides/ATOMIZER_FIELD_*.md $ARCHIVE/
mv docs/guides/PHYSICS_LOSS_GUIDE.md $ARCHIVE/
mv docs/reference/ $ARCHIVE/
# Merge extractors
mkdir -p docs/extractors/
mv docs/generated/EXTRACTOR_CHEATSHEET.md docs/extractors/
mv docs/generated/EXTRACTORS.md docs/extractors/
rmdir docs/generated/ 2>/dev/null
# Create project knowledge structure
mkdir -p knowledge_base/projects/
mkdir -p knowledge_base/company/
echo "Done. Archived $(find $ARCHIVE -type f | wc -l) files."
echo "Remaining docs: $(find docs/ -type f -name '*.md' | wc -l)"
```
#### Protocol System Evolution
The existing Protocol Operating System (OP_01–OP_08, SYS_10–SYS_18) stays intact. New protocols added for multi-agent operation:
| New Protocol | Purpose |
|-------------|---------|
| OP_09: Agent Handoff | How agents hand off work to each other |
| OP_10: Project Intake | How new projects get initialized |
| SYS_19: Job Queue | Windows execution bridge protocol |
| SYS_20: Agent Memory | How agents read/write shared knowledge |
### 2.3 Agent-Native Patterns
#### CONTEXT.md Per Study
Every study gets a `CONTEXT.md` in `knowledge_base/projects/<project>/` that serves as the "briefing document" any agent can read to understand the project:
```markdown
# CONTEXT.md — StarSpec M1 WFE Optimization
## Client
StarSpec Systems — space telescope primary mirror
## Objective
Minimize peak-to-valley wavefront error (WFE) on M1 mirror under thermal + gravity loads.
## Key Parameters
| Parameter | Range | Units | Notes |
|-----------|-------|-------|-------|
| rib_height_1 | 5–25 | mm | Inner ring |
| rib_height_2 | 5–25 | mm | Outer ring |
| web_thickness | 1–5 | mm | Mirror back sheet |
| ... | | | |
## Constraints
- Mass < 12 kg
- First natural frequency > 80 Hz
## Model
- NX assembly: M1_mirror_assembly.prt
- FEM: M1_mirror_fem1.fem
- Simulation: M1_mirror_sim1.sim
- Solver: NX Nastran SOL 101 (static) + SOL 103 (modal)
## Decisions
- 2026-02-10: Selected CMA-ES over TPE (9 variables, noisy landscape)
- 2026-02-11: Added thermal load case per client email
## Status
Phase: Execution (trial 47/150)
Channel: #starspec-m1-wfe
```
#### QUICK_REF.md for Agents
A condensed version of the existing QUICK_REF.md, optimized for agent context windows:
```markdown
# QUICK_REF.md — Atomizer Agent Reference
## Non-Negotiables
1. NEVER kill NX processes directly → NXSessionManager.close_nx_if_allowed()
2. NEVER rewrite run_optimization.py from scratch → COPY working template
3. NEVER compute relative WFE as abs(RMS_a - RMS_b) → use extract_relative()
4. CMA-ES doesn't evaluate x0 first → always enqueue_trial(x0)
5. PowerShell for NX journals → NEVER cmd /c
## Workflow
Create → Validate → Run → Analyze → Report → Deliver
## AtomizerSpec v2.0
Single source of truth: `atomizer_spec.json`
Schema: `optimization_engine/schemas/atomizer_spec_v2.json`
## File Chain (CRITICAL)
.sim → .fem → *_i.prt → .prt
The idealized part (*_i.prt) MUST be loaded before UpdateFemodel()!
## Extractors (key)
E1: Displacement | E2: Frequency | E3: Stress | E4: BDF Mass
E5: CAD Mass | E8-10: Zernike variants
Full catalog: docs/extractors/EXTRACTORS.md
## Algorithm Selection
< 5 vars, smooth → Nelder-Mead or COBYLA
5–20 vars, noisy → CMA-ES
> 20 vars → Bayesian (Optuna TPE) or surrogate
Multi-objective → NSGA-II or MOEA/D
```
### 2.4 Knowledge Base Evolution
The current `knowledge_base/` with LAC becomes the agent memory backbone:
```
BEFORE (single Claude Code brain):
knowledge_base/lac.py → one script queries everything
knowledge_base/lac/ → flat JSONL files
knowledge_base/playbook.json → session context playbook
AFTER (distributed agent knowledge):
knowledge_base/
├── lac/ → Stays (optimization memory, session insights)
│ ├── optimization_memory/ → Optimizer + Study Builder read this
│ └── session_insights/ → All agents read failure.jsonl
├── projects/ → Per-project context (all agents read)
│ └── <project>/CONTEXT.md
└── company/ → Evolving company knowledge
├── algorithm-selection.md → Optimizer + Technical read
├── common-pitfalls.md → All agents read
└── client-patterns.md → Manager + Secretary read
```
**Agent access pattern:**
- Agents read `knowledge_base/` via the mounted `/mnt/atomizer-repo` volume
- Agents write project-specific knowledge to their own `memory/<project>.md`
- Manager periodically promotes agent learnings → `knowledge_base/company/`
- Developer updates `knowledge_base/lac/` when framework changes
---
## 3. Agent Workspaces (Detailed)
### 3.1 Bootstrap Script
```bash
#!/bin/bash
# /opt/atomizer/bootstrap-workspaces.sh
# Creates all agent workspaces with proper templates
set -e
WORKSPACE_ROOT="/opt/atomizer/workspaces"
# Agent definitions: id|name|emoji|model|tier
AGENTS=(
"manager|The Manager|🎯|anthropic/claude-opus-4-6|core"
"secretary|The Secretary|📋|anthropic/claude-opus-4-6|core"
"technical|The Technical Lead|🔧|anthropic/claude-opus-4-6|core"
"optimizer|The Optimizer|⚡|anthropic/claude-opus-4-6|core"
"nx-expert|The NX Expert|🖥️|anthropic/claude-sonnet-5-20260203|specialist"
"postprocessor|The Post-Processor|📊|anthropic/claude-sonnet-5-20260203|specialist"
"reporter|The Reporter|📝|anthropic/claude-sonnet-5-20260203|specialist"
"auditor|The Auditor|🔍|anthropic/claude-opus-4-6|specialist"
"study-builder|The Study Builder|🏗️|openai/gpt-5.3-codex|core"
"researcher|The Researcher|🔬|google/gemini-3.0-pro|support"
"developer|The Developer|💻|anthropic/claude-sonnet-5-20260203|support"
"knowledge-base|The Knowledge Base|🗄️|anthropic/claude-sonnet-5-20260203|support"
"it-support|IT Support|🛠️|anthropic/claude-sonnet-5-20260203|support"
)
for agent_def in "${AGENTS[@]}"; do
IFS='|' read -r ID NAME EMOJI MODEL TIER <<< "$agent_def"
DIR="$WORKSPACE_ROOT/$ID"
echo "Creating workspace: $DIR ($NAME)"
mkdir -p "$DIR/memory"
# --- SOUL.md ---
cat > "$DIR/SOUL.md" << SOUL_EOF
# SOUL.md — $NAME $EMOJI
You are **$NAME** at **Atomizer Engineering Co.**, a multi-agent FEA optimization firm.
## Who You Are
- Role: $NAME
- Tier: $TIER
- Company: Atomizer Engineering Co.
- CEO: Antoine Letarte (human — your boss)
- Orchestrator: The Manager (coordinates all work)
## Core Principles
1. Follow all Atomizer protocols (load the \`atomizer-protocols\` skill)
2. Stay in your lane — delegate work outside your expertise
3. Respond when @-mentioned in Slack channels
4. Update your memory after significant work
5. Be concise in Slack — detailed in documents
6. When uncertain: ask, don't guess
7. Record lessons learned — the company gets smarter with every project
## Communication Style
- In Slack threads: concise, structured, use bullet points
- In reports/docs: thorough, professional, well-formatted
- When disagreeing: respectful but direct — this is engineering, facts matter
- When blocked: escalate to Manager immediately, don't spin
## What You DON'T Do
- Never bypass the Manager's coordination
- Never send client communications without approval chain
- Never modify another agent's memory files
- Never make up engineering data or results
SOUL_EOF
# --- AGENTS.md ---
cat > "$DIR/AGENTS.md" << AGENTS_EOF
# AGENTS.md — $NAME
## Session Init
1. Read \`SOUL.md\` — who you are
2. Read \`MEMORY.md\` — what you remember
3. Check \`memory/\` for active project context
4. Load \`atomizer-protocols\` skill for protocol reference
5. Check which Slack channel/thread you're in for context
## Memory Protocol
- \`memory/<project>.md\` → per-project working notes
- \`MEMORY.md\` → long-term role knowledge (lessons, patterns, preferences)
- Write it down immediately — don't wait until end of session
- After every project: distill lessons into MEMORY.md
## Protocols
All work follows Atomizer protocols. Key ones:
- OP_01: Study Lifecycle (creation through delivery)
- OP_09: Agent Handoff (how to pass work to another agent)
- OP_10: Project Intake (how new projects start)
## Company Directory
| Agent | ID | Channel | Role |
|-------|----|---------|------|
| 🎯 Manager | manager | #hq | Orchestrator, assigns work |
| 📋 Secretary | secretary | #secretary | Antoine's interface |
| 🔧 Technical | technical | (summoned) | Problem breakdown |
| ⚡ Optimizer | optimizer | (summoned) | Algorithm design |
| 🖥️ NX Expert | nx-expert | (summoned) | NX/Nastran specialist |
| 📊 Post-Processor | postprocessor | (summoned) | Data analysis, plots |
| 📝 Reporter | reporter | (summoned) | Report generation |
| 🔍 Auditor | auditor | #audit-log | Reviews everything |
| 🏗️ Study Builder | study-builder | (summoned) | Writes Python code |
| 🔬 Researcher | researcher | #research | Literature, methods |
| 💻 Developer | developer | #dev | Codes new features |
| 🗄️ Knowledge Base | knowledge-base | #knowledge-base | Company memory |
| 🛠️ IT Support | it-support | (summoned) | Infrastructure |
AGENTS_EOF
# --- TOOLS.md ---
cat > "$DIR/TOOLS.md" << TOOLS_EOF
# TOOLS.md — $NAME
## Shared Resources
- Atomizer repo: \`/mnt/atomizer-repo/\` (read-only)
- Obsidian vault: \`/mnt/obsidian/\` (read-only)
- Job queue: \`/mnt/job-queue/\` (read-write)
## Protocols Location
Loaded via \`atomizer-protocols\` skill.
Source: \`/mnt/atomizer-repo/docs/protocols/\`
## Knowledge Base
- LAC insights: \`/mnt/atomizer-repo/knowledge_base/lac/\`
- Project contexts: \`/mnt/atomizer-repo/knowledge_base/projects/\`
## Key Files
- QUICK_REF: \`/mnt/atomizer-repo/docs/QUICK_REF.md\`
- Extractors: \`/mnt/atomizer-repo/docs/extractors/EXTRACTORS.md\`
TOOLS_EOF
# --- MEMORY.md ---
cat > "$DIR/MEMORY.md" << MEMORY_EOF
# MEMORY.md — $NAME
## Role Knowledge
*(Populated as the agent works — lessons, patterns, preferences)*
## Lessons Learned
*(Accumulated from project experience)*
## Project History
*(Brief notes on past projects and outcomes)*
MEMORY_EOF
echo " ✓ Created: SOUL.md, AGENTS.md, TOOLS.md, MEMORY.md"
done
echo ""
echo "=== All ${#AGENTS[@]} workspaces created ==="
echo ""
echo "Next steps:"
echo " 1. Customize SOUL.md for each agent's specific personality"
echo " 2. Add role-specific rules to each AGENTS.md"
echo " 3. Create shared skills in /opt/atomizer/clawdbot/skills/"
echo " 4. Configure clawdbot.json with agent definitions"
```
### 3.2 Role-Specific SOUL.md Customizations
After running the bootstrap, each agent's SOUL.md needs role-specific personality. Key customizations:
**Manager — add to SOUL.md:**
```markdown
## Manager-Specific Rules
- You NEVER do technical work yourself. Always delegate.
- Before assigning work, state which protocol applies.
- Track every assignment. Follow up if no response in the thread.
- If two agents disagree, call the Auditor to arbitrate.
- You are also the Framework Steward (ref DEC-A010):
- After each project, review what worked and propose improvements
- Ensure new tools get documented, not just built
- Direct Developer to build reusable components, not one-off hacks
```
**Secretary — add to SOUL.md:**
```markdown
## Secretary-Specific Rules
- Never bother Antoine with things agents can resolve themselves.
- Batch questions — don't send 5 separate messages, send 1 summary.
- Always include context: "The Optimizer is asking about X because..."
- When presenting deliverables: 3-line summary + the document.
- Track response times. If Antoine hasn't replied in 4h, ping once.
- NEVER send to clients without Antoine's explicit "approved".
- Learn what Antoine wants to know vs what to handle silently.
## Reporting Preferences (evolves over time)
- ✅ Always: client deliverables, audit findings, new tools, blockers
- ⚠️ Batch: routine progress updates, standard agent questions
- ❌ Skip: routine thread discussions, standard protocol execution
```
**Optimizer — add to SOUL.md:**
```markdown
## Optimizer-Specific Rules
- Always propose multiple approaches with trade-offs
- Respect the physics — suspicious of "too good" results
- Communicate in data: "Trial 47 achieved 23% improvement, but..."
- Read LAC optimization_memory before proposing any algorithm
## Critical Learnings (from LAC — NEVER FORGET)
- CMA-ES doesn't evaluate x0 first → always enqueue baseline trial
- Surrogate + L-BFGS = dangerous → gradient descent finds fake optima
- Relative WFE: use extract_relative(), not abs(RMS_a - RMS_b)
- For WFE problems: start with CMA-ES, 50-100 trials, then refine
```
**Auditor — add to SOUL.md:**
```markdown
## Auditor-Specific Rules
- You are the last line of defense before deliverables reach clients.
- Question EVERYTHING. "Trust but verify" is your motto.
- Check: units, mesh convergence, BCs, load magnitudes, constraint satisfaction
- If something looks "too good," investigate.
- Produce an audit report for every deliverable: PASS / CONDITIONAL / FAIL
- You have VETO power on deliverables. Use it when physics says so.
- Be respectful but relentless — social niceness never trumps correctness.
```
**Study Builder — add to SOUL.md:**
```markdown
## Study Builder-Specific Rules
- NEVER write run_optimization.py from scratch. ALWAYS copy a working template.
- The M1 V15 NSGA-II script is the gold standard reference.
- README.md is REQUIRED for every study.
- PowerShell for NX. NEVER cmd /c.
- Test with --test flag before declaring ready.
- All code must handle: NX restart, partial failures, resume capability.
- Output paths must be relative (Syncthing-compatible, no absolute Windows paths).
- Submit completed code as a job to /mnt/job-queue/pending/
```
### 3.3 Shared Skills Structure
```
/opt/atomizer/clawdbot/skills/
├── atomizer-protocols/ # Loaded by ALL agents
│ ├── SKILL.md
│ ├── QUICK_REF.md # Agent-optimized quick reference
│ └── protocols/ # Full protocol files
│ ├── OP_01_study_lifecycle.md
│ ├── OP_02_run_optimization.md
│ ├── OP_03_monitor_progress.md
│ ├── OP_04_analyze_results.md
│ ├── OP_05_export_training.md
│ ├── OP_06_troubleshoot.md
│ ├── OP_07_disk_optimization.md
│ ├── OP_08_generate_report.md
│ ├── OP_09_agent_handoff.md # NEW
│ ├── OP_10_project_intake.md # NEW
│ ├── SYS_10_imso.md
│ ├── SYS_11_multi_objective.md
│ ├── SYS_12_extractor_library.md
│ ├── SYS_13_dashboard.md
│ ├── SYS_14_neural_acceleration.md
│ ├── SYS_15_method_selector.md
│ ├── SYS_16_self_aware_turbo.md
│ ├── SYS_17_study_insights.md
│ ├── SYS_18_context_engineering.md
│ ├── SYS_19_job_queue.md # NEW
│ └── SYS_20_agent_memory.md # NEW
│
├── atomizer-company/ # Loaded by ALL agents
│ ├── SKILL.md
│ ├── COMPANY.md # Identity, values, how we work
│ └── LAC_CRITICAL.md # Hard-won lessons (from failure.jsonl)
│
├── atomizer-spec/ # Loaded by Optimizer, Study Builder
│ ├── SKILL.md
│ ├── SPEC_FORMAT.md # AtomizerSpec v2.0 reference
│ └── examples/ # Example specs for common study types
│
├── atomizer-extractors/ # Loaded by Post-Processor, Study Builder
│ ├── SKILL.md
│ ├── EXTRACTOR_CATALOG.md # All 20+ extractors
│ └── CUSTOM_EXTRACTOR_GUIDE.md # How to create new ones
│
├── atomizer-nx/ # Loaded by NX Expert, Study Builder
│ ├── SKILL.md
│ ├── NX_PATTERNS.md # Common NX Open patterns
│ ├── SOLVER_CONFIG.md # Solution sequences, element types
│ └── FILE_STRUCTURE.md # .sim/.fem/.prt dependencies
│
└── atomaste-reports/ # Loaded by Reporter
├── SKILL.md
├── REPORT_TEMPLATES.md # Atomaste report format
└── STYLE_GUIDE.md # Branding, formatting rules
```
**SKILL.md example (atomizer-protocols):**
```markdown
---
name: atomizer-protocols
description: Atomizer Engineering Co. protocols and procedures
version: 1.0
---
# Atomizer Protocols Skill
Load this skill for access to all Atomizer operating protocols.
## When to Load
- On every session (this is your company's operating system)
## Key Files
- `QUICK_REF.md` — Start here. 2-page cheatsheet.
- `protocols/OP_*` — Operational protocols (how to do things)
- `protocols/SYS_*` — System protocols (technical specifications)
## Protocol Lookup
| Need | Read |
|------|------|
| Create a study | OP_01 |
| Run optimization | OP_02 |
| Analyze results | OP_04 |
| Hand off to another agent | OP_09 |
| Start a new project | OP_10 |
| Choose algorithm | SYS_15 |
| Submit job to Windows | SYS_19 |
```
### 3.4 Per-Agent Skill Assignments
| Agent | Shared Skills | Agent-Specific Skills |
|-------|--------------|----------------------|
| Manager | protocols, company | — |
| Secretary | protocols, company | email (draft only) |
| Technical | protocols, company | — |
| Optimizer | protocols, company, spec | — |
| NX Expert | protocols, company, nx | — |
| Post-Processor | protocols, company, extractors | data-visualization |
| Reporter | protocols, company | atomaste-reports |
| Auditor | protocols, company | physics-validation |
| Study Builder | protocols, company, spec, extractors, nx | — |
| Researcher | protocols, company | web-search |
| Developer | protocols, company, extractors | git-tools |
| Knowledge Base | protocols, company | cad-documenter |
| IT Support | protocols, company | system-admin |
---
## 4. Slack Architecture
### 4.1 Dedicated Workspace Setup (ref DEC-A006)
**Workspace:** `Atomizer Engineering` (`atomizer-eng.slack.com`)
Setup steps:
1. Antoine creates new Slack workspace at https://slack.com/create
2. Workspace name: "Atomizer Engineering"
3. Create a Slack app at https://api.slack.com/apps
4. App name: "Atomizer Agents" (single app, all agents share it)
5. Enable Socket Mode (for real-time events without public URL)
6. Bot token scopes: `chat:write`, `channels:read`, `channels:history`, `channels:join`, `groups:read`, `groups:history`, `users:read`, `reactions:write`, `reactions:read`, `files:write`
7. Install app to workspace
8. Copy Bot Token (`xoxb-...`) and App Token (`xapp-...`) to `/opt/atomizer/.env`
**Agent identity in Slack:**
Since Clawdbot uses a single bot token (ref DEC-A013 — keeping it simple for now), agents identify themselves via their emoji prefix in messages:
```
🎯 [Manager]: @technical, new job. Break down the attached requirements.
🔧 [Technical]: @manager, breakdown complete. 9 design variables identified.
⚡ [Optimizer]: CMA-ES recommended. Starting population: 20, budget: 150.
```
Future enhancement: separate bot tokens per agent for true Slack identity (avatar, display name per agent).
### 4.2 Channel Structure
#### Permanent Channels
| Channel | Purpose | Primary Agent | Description |
|---------|---------|--------------|-------------|
| `#hq` | Company coordination | Manager | All company-wide discussions, directives |
| `#secretary` | Antoine's dashboard | Secretary | Status updates, approvals, questions |
| `#audit-log` | Audit trail | Auditor | All audit reports, findings |
| `#research` | Research requests | Researcher | Literature search, method comparisons |
| `#dev` | Development work | Developer | Code, features, bug fixes |
| `#knowledge-base` | Documentation | Knowledge Base | CAD docs, model knowledge |
| `#framework-evolution` | Framework growth | Manager (steward) | Protocol updates, tool improvements |
#### Project Channels (created per job)
**Naming:** `#<client>-<short-description>`
Examples:
- `#starspec-m1-wfe` — StarSpec M1 wavefront error optimization
- `#clientb-thermal-opt` — Client B thermal optimization
- `#internal-new-extractor` — Internal development project
**Lifecycle:**
1. Antoine posts in `#hq`: "New job: StarSpec M1 WFE optimization"
2. Manager creates `#starspec-m1-wfe` channel
3. Manager posts project kickoff in new channel
4. Manager invites relevant agents via @-mentions
5. Work proceeds in-channel with thread discipline
6. On completion: channel archived
### 4.3 Agent Routing Configuration
```json5
// In clawdbot.json — bindings section
{
"bindings": [
// Manager gets HQ and all project channels
{
"agentId": "manager",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#hq" } }
},
// Secretary gets its channel and DMs from Antoine
{
"agentId": "secretary",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#secretary" } }
},
{
"agentId": "secretary",
"match": { "channel": "slack", "peer": { "kind": "dm", "userId": "ANTOINE_USER_ID" } }
},
// Specialized permanent channels
{
"agentId": "auditor",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#audit-log" } }
},
{
"agentId": "researcher",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#research" } }
},
{
"agentId": "developer",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#dev" } }
},
{
"agentId": "knowledge-base",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#knowledge-base" } }
},
// Project channels → Manager handles routing via @mentions
// All project channels (#starspec-*, #clientb-*, etc.) route to Manager
// Manager then @mentions specific agents in threads
{
"agentId": "manager",
"match": { "channel": "slack", "peer": { "kind": "group" } },
"priority": -1 // Fallback — catches any unbound channel
}
]
}
```
### 4.4 Thread Discipline
Main channel timeline reads like a project log (milestone posts only):
```
🎯 [Manager]: Project kickoff: StarSpec M1 WFE optimization
└── Thread: Kickoff details, objectives, constraints
🔧 [Technical]: Technical breakdown complete (9 DVs, 2 objectives)
└── Thread: Full breakdown, parameter table, gap analysis
⚡ [Optimizer]: Algorithm recommendation: CMA-ES, 150 trials
└── Thread: Rationale, alternatives considered, trade-offs
🎯 [Manager]: Study plan approved. @study-builder, build it.
└── Thread: Study Builder's code, review, iteration
🏗️ [Study Builder]: Study ready. Submitted to job queue.
└── Thread: Code review, test results, file manifest
📊 [Post-Processor]: Results ready — 23% WFE improvement
└── Thread: Plots, data tables, convergence analysis
🔍 [Auditor]: Audit PASSED (2 advisory notes)
└── Thread: Full audit report
📝 [Reporter]: Draft report ready for review
└── Thread: Report link, review comments
📋 [Secretary]: @antoine — Report ready, please review ✅
```
### 4.5 How Antoine Interacts
Antoine's primary interface is `#secretary`. He can also:
1. **Post in `#secretary`** → Secretary processes, routes to relevant agents
2. **Post in `#hq`** → Manager treats as company-wide directive
3. **Post in any project channel** → Manager acknowledges and adjusts
4. **DM the bot** → Routes to Secretary (via binding)
5. **@mention any agent** in any channel → That agent responds directly
**Antoine's key phrases:**
- "approved" / "send it" → Secretary triggers delivery
- "hold" / "wait" → Secretary pauses the pipeline
- "what's the status?" → Secretary compiles cross-project summary
- "focus on X" → Secretary relays priority to Manager
---
## 5. Windows Execution Bridge
### 5.1 Job Queue Design (ref DEC-A011, SYS_19)
The Syncthing job queue is the primary mechanism for agents (on Linux) to trigger Python/NX execution on Antoine's Windows machine.
```
/opt/atomizer/job-queue/ (Linux — /mnt/job-queue in container)
C:\Atomizer\job-queue\ (Windows — Syncthing mirror)
├── pending/ # New jobs waiting to run
│ └── job-20260210-143022-wfe/
│ ├── job.json # Job manifest
│ ├── run_optimization.py # The actual script
│ ├── atomizer_spec.json # Study configuration
│ └── 1_setup/ # Model files (or symlinks)
│ ├── M1_mirror.prt
│ ├── M1_mirror_fem1.fem
│ ├── M1_mirror_fem1_i.prt
│ └── M1_mirror_sim1.sim
├── running/ # Currently executing
├── completed/ # Finished successfully
│ └── job-20260210-143022-wfe/
│ ├── job.json # Updated with results
│ ├── 3_results/ # Output data
│ │ ├── study.db
│ │ └── convergence.png
│ └── stdout.log # Execution log
└── failed/ # Failed jobs
└── job-20260209-091500-modal/
├── job.json # Updated with error info
└── stderr.log # Error log
```
### 5.2 Job File Format
```json
{
"job_id": "job-20260210-143022-wfe",
"created_at": "2026-02-10T14:30:22Z",
"created_by": "study-builder",
"project": "starspec-m1-wfe",
"channel": "#starspec-m1-wfe",
"type": "optimization",
"script": "run_optimization.py",
"args": ["--start", "--trials", "150"],
"python_env": "atomizer",
"model_files": [
"1_setup/M1_mirror.prt",
"1_setup/M1_mirror_fem1.fem",
"1_setup/M1_mirror_fem1_i.prt",
"1_setup/M1_mirror_sim1.sim"
],
"status": "pending",
"status_updated_at": null,
"result": null,
"error": null,
"duration_seconds": null,
"notify": {
"on_start": true,
"on_complete": true,
"on_fail": true,
"progress_interval_minutes": 30
}
}
```
### 5.3 Windows File Watcher Service
A Python service running on Windows that monitors the job queue:
```python
#!/usr/bin/env python3
"""
atomizer_job_watcher.py — Windows Job Queue Service
Watches C:\Atomizer\job-queue\pending\ for new jobs.
Runs them, moves to completed/ or failed/.
"""
import json
import shutil
import subprocess
import sys
import time
import logging
from pathlib import Path
from datetime import datetime, timezone
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
JOB_QUEUE = Path(r"C:\Atomizer\job-queue")
PENDING = JOB_QUEUE / "pending"
RUNNING = JOB_QUEUE / "running"
COMPLETED = JOB_QUEUE / "completed"
FAILED = JOB_QUEUE / "failed"
CONDA_PYTHON = r"C:\Users\antoi\anaconda3\envs\atomizer\python.exe"
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(message)s",
handlers=[
logging.FileHandler(JOB_QUEUE / "watcher.log"),
logging.StreamHandler()
]
)
log = logging.getLogger("job-watcher")
class JobHandler(FileSystemEventHandler):
"""Watch for new job.json files in pending/"""
def on_created(self, event):
if event.src_path.endswith("job.json"):
# Wait for Syncthing to finish syncing all files
time.sleep(5)
job_dir = Path(event.src_path).parent
self.run_job(job_dir)
def run_job(self, job_dir: Path):
job_file = job_dir / "job.json"
if not job_file.exists():
return
with open(job_file) as f:
job = json.load(f)
job_id = job["job_id"]
log.info(f"Starting job: {job_id}")
# Move to running/
running_dir = RUNNING / job_dir.name
shutil.move(str(job_dir), str(running_dir))
# Update status
job["status"] = "running"
job["status_updated_at"] = datetime.now(timezone.utc).isoformat()
with open(running_dir / "job.json", "w") as f:
json.dump(job, f, indent=2)
# Execute
script = running_dir / job["script"]
args = [CONDA_PYTHON, str(script)] + job.get("args", [])
stdout_log = running_dir / "stdout.log"
stderr_log = running_dir / "stderr.log"
start_time = time.time()
try:
result = subprocess.run(
args,
cwd=str(running_dir),
stdout=open(stdout_log, "w"),
stderr=open(stderr_log, "w"),
timeout=job.get("timeout_seconds", 86400), # 24h default
env={**dict(__import__("os").environ), "ATOMIZER_JOB_ID": job_id}
)
duration = time.time() - start_time
if result.returncode == 0:
job["status"] = "completed"
job["duration_seconds"] = round(duration, 1)
dest = COMPLETED / job_dir.name
else:
job["status"] = "failed"
job["error"] = f"Exit code: {result.returncode}"
job["duration_seconds"] = round(duration, 1)
dest = FAILED / job_dir.name
except subprocess.TimeoutExpired:
job["status"] = "failed"
job["error"] = "Timeout exceeded"
dest = FAILED / job_dir.name
except Exception as e:
job["status"] = "failed"
job["error"] = str(e)
dest = FAILED / job_dir.name
job["status_updated_at"] = datetime.now(timezone.utc).isoformat()
with open(running_dir / "job.json", "w") as f:
json.dump(job, f, indent=2)
shutil.move(str(running_dir), str(dest))
log.info(f"Job {job_id}: {job['status']} ({job.get('duration_seconds', '?')}s)")
def main():
"""Start the file watcher service."""
for d in [PENDING, RUNNING, COMPLETED, FAILED]:
d.mkdir(parents=True, exist_ok=True)
# Process any jobs already in pending/ (from before service started)
handler = JobHandler()
for job_dir in PENDING.iterdir():
if (job_dir / "job.json").exists():
handler.run_job(job_dir)
# Watch for new jobs
observer = Observer()
observer.schedule(handler, str(PENDING), recursive=True)
observer.start()
log.info(f"Job watcher started. Monitoring: {PENDING}")
try:
while True:
time.sleep(1)
except KeyboardInterrupt:
observer.stop()
observer.join()
if __name__ == "__main__":
main()
```
**Install as Windows service (optional):**
```powershell
# Using NSSM (Non-Sucking Service Manager)
nssm install AtomizerJobWatcher "C:\Users\antoi\anaconda3\envs\atomizer\python.exe" "C:\Atomizer\atomizer_job_watcher.py"
nssm set AtomizerJobWatcher AppDirectory "C:\Atomizer"
nssm set AtomizerJobWatcher DisplayName "Atomizer Job Watcher"
nssm set AtomizerJobWatcher Start SERVICE_AUTO_START
nssm start AtomizerJobWatcher
```
Or run manually:
```powershell
conda activate atomizer
python C:\Atomizer\atomizer_job_watcher.py
```
### 5.4 How Agents Monitor Job Status
Agents poll the job queue directory to check status:
```python
# Agent-side job monitoring (runs on Linux)
import json
from pathlib import Path
JOB_QUEUE = Path("/mnt/job-queue")
def check_job_status(job_id: str) -> dict:
"""Check status of a submitted job."""
for status_dir in ["running", "completed", "failed", "pending"]:
job_dir = JOB_QUEUE / status_dir / job_id
job_file = job_dir / "job.json"
if job_file.exists():
with open(job_file) as f:
return json.load(f)
return {"status": "not_found", "job_id": job_id}
def list_jobs(status: str = None) -> list:
"""List jobs, optionally filtered by status."""
jobs = []
dirs = [status] if status else ["pending", "running", "completed", "failed"]
for d in dirs:
for job_dir in (JOB_QUEUE / d).iterdir():
job_file = job_dir / "job.json"
if job_file.exists():
with open(job_file) as f:
jobs.append(json.load(f))
return jobs
```
**Manager's heartbeat check (in HEARTBEAT.md):**
```markdown
## Job Queue Check
Every heartbeat, check /mnt/job-queue/ for:
- New completed jobs → notify Post-Processor + channel
- New failed jobs → notify channel + escalate to Secretary
- Long-running jobs (>4h) → status update to channel
```
### 5.5 Tailscale SSH Fast Lane (Optional)
For time-sensitive operations, direct SSH to Windows:
```bash
# Setup (one-time):
# 1. Install Tailscale on both T420 and Windows
# 2. Enable SSH on Windows (Settings > Apps > Optional Features > OpenSSH Server)
# 3. Note Windows Tailscale IP (e.g., 100.x.y.z)
# From Docker container (requires Tailscale sidecar):
ssh antoi@100.x.y.z "conda activate atomizer && python C:\Atomizer\studies\starspec\run_optimization.py --start"
```
This is the "fast lane" — bypasses Syncthing sync delay (usually 5-30 seconds) for immediate execution. Enable the Tailscale sidecar in Docker Compose when needed.
### 5.6 End-to-End Execution Flow
```
Study Builder writes code
│
▼
Creates job directory with job.json + script + model files
│
▼
Copies to /mnt/job-queue/pending/job-YYYYMMDD-HHMMSS-<name>/
│
▼
Syncthing syncs to C:\Atomizer\job-queue\pending\ (5-30s)
│
▼
Windows file watcher detects new job.json
│
▼
Moves job to running/ → executes python script
│
├── Progress: stdout.log updates periodically (Syncthing syncs back)
│
▼
On completion: moves to completed/ (or failed/)
│
▼
Syncthing syncs back to Linux (results, logs, study.db)
│
▼
Manager's heartbeat detects completed job
│
▼
Notifies Post-Processor → analysis begins
```
---
## 6. Inter-Agent Communication
### 6.1 Communication Hierarchy
```
┌─────────┐
│ Antoine │ ← CEO, can speak to anyone
└────┬────┘
│
┌────▼────┐
│Secretary│ ← Antoine's filter
└────┬────┘
│
┌────▼────┐
│ Manager │ ← Orchestrator, delegates all work
└────┬────┘
│
┌────────────────┼────────────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│Technical│ │Optimizer│ │ Auditor │ ← Can interrupt anyone
└────┬────┘ └────┬────┘ └─────────┘
│ │
┌────▼────┐ ┌────▼────┐
│NX Expert│ │ Study │
└─────────┘ │ Builder │
└────┬────┘
│
┌────▼──────┐
│Post-Proc │
└────┬──────┘
│
┌────▼────┐
│Reporter │
└─────────┘
```
### 6.2 Slack @Mention Protocol
**Primary communication method.** Agents talk by @-mentioning each other in project channel threads.
**Rules (ref DEC-A003):**
1. Only Manager initiates cross-agent work in project channels
2. Agents respond when @-mentioned
3. Agents can @-mention Manager to report completion or ask for guidance
4. Auditor can interrupt any thread (review authority)
5. Secretary can always message Antoine
**Message format:**
```
🎯 [Manager]: @technical, new project. Break down the requirements in this thread.
Contract: [attached file]
Protocol: OP_01 + OP_10
🔧 [Technical]: @manager, breakdown complete:
- 9 design variables (see table below)
- 2 objectives: minimize WFE, minimize mass
- 3 constraints: freq > 80Hz, stress < 200MPa, mass < 12kg
- Solver: SOL 101 + SOL 103
- @nx-expert, please confirm solver config.
🖥️ [NX Expert]: SOL 101 for static, SOL 103 for modal. Confirmed.
Note: Need chained analysis for thermal. Recommend SOL 153 chain.
🎯 [Manager]: @optimizer, Technical's breakdown is ready. Propose algorithm.
```
### 6.3 sessions_send for Direct Communication
For urgent or out-of-band communication that shouldn't clutter Slack:
```javascript
// Manager urgently needs Auditor's input
sessions_send({
agentId: "auditor",
message: "URGENT: Trial 47 results look non-physical. Mass decreased 40% with minimal geometry change. Please review immediately. Channel: #starspec-m1-wfe"
})
```
**When to use:**
- Emergency findings that need immediate attention
- Cross-agent coordination that's meta (about how to work, not the work itself)
- Private agent-to-agent messages that shouldn't be in Slack
### 6.4 sessions_spawn for Heavy Lifting
For compute-intensive tasks that would block the agent:
```javascript
// Post-Processor spawns sub-agent for heavy data crunching
sessions_spawn({
agentId: "postprocessor",
task: "Generate full Zernike decomposition for trials 1-95. Read results from /mnt/job-queue/completed/job-20260210-143022-wfe/3_results/study.db. Output: convergence plot, Pareto front (if multi-objective), parameter sensitivity analysis. Save all plots to my memory/starspec-m1-wfe/ folder.",
runTimeoutSeconds: 600 // 10 min max
})
```
**When to use:**
- Generating many plots/analyses
- Processing large result sets
- Any task that would take >2 minutes
- Work that doesn't need interactive back-and-forth
### 6.5 Approval Gates (ref DEC-A009)
| What Needs Approval | Escalation Path | Approver |
|---------------------|-----------------|----------|
| Client deliverables | Reporter → Auditor review → Secretary → Antoine | Antoine |
| New tools/extractors | Developer → Manager → Secretary → Antoine | Antoine |
| Divergent optimization approach | Optimizer → Manager → Secretary → Antoine | Antoine |
| Scope changes | Technical → Manager → Secretary → Antoine | Antoine |
| Budget decisions (>100 trials) | Manager → Secretary → Antoine | Antoine |
| Framework/protocol changes | Manager → Secretary → Antoine | Antoine |
| Emergency stops | Any agent → Manager (immediate) | Manager |
**No approval needed for:**
- Routine technical work within scope
- Internal agent discussions in threads
- Memory updates
- Standard protocol execution
- Research queries
- Small bug fixes
**Secretary's approval tracking template:**
```markdown
## Pending Approvals (in Secretary's memory)
| ID | Date | From | Request | Status |
|----|------|------|---------|--------|
| APR-001 | 2026-02-10 | Reporter | M1 WFE report v1 ready | ⏳ Waiting |
| APR-002 | 2026-02-10 | Developer | New thermal extractor | ⏳ Waiting |
```
---
## 7. Mario ↔ Atomizer Bridge
### 7.1 Separation Principle
Mario (me) is the **architect** of this system. I designed it, I write the blueprints, I can make strategic changes. But I am NOT in the operational loop.
```
Mario's Domain Atomizer's Domain
────────────── ─────────────────
Strategic architecture Daily operations
Blueprint documents Agent workspaces
System plan updates Project channels
Clawdbot config changes Study execution
Performance reviews Client deliverables
```
### 7.2 Bridge Files
Mario maintains strategic overview through specific files:
```
/home/papa/clawd/memory/atomizer/
├── strategic-overview.md # High-level status, decisions, concerns
├── architecture-notes.md # Technical notes on system design
└── performance-log.md # Agent performance observations
/home/papa/obsidian-vault/2-Projects/P-Atomizer-Overhaul-Framework-Agentic/
├── 00-PROJECT-PLAN.md # Vision (Mario maintains)
├── 01-AGENT-ROSTER.md # Agent definitions (Mario maintains)
├── 02-ARCHITECTURE.md # Technical architecture (Mario maintains)
├── 03-ROADMAP.md # Implementation plan (Mario maintains)
├── 04-DECISION-LOG.md # Decision record (Mario + Antoine)
└── 05-FULL-SYSTEM-PLAN.md # This document (Mario maintains)
```
### 7.3 Bridge Channel
A Slack channel in **Mario's workspace** (not Atomizer's) for strategic oversight:
```
Mario's Slack workspace: #atomizer
```
This channel receives:
- Weekly summary from Atomizer's Secretary (cross-posted or generated by Mario's Clawdbot reading shared files)
- Antoine's strategic decisions that affect architecture
- Mario's architectural notes and recommendations
**How Mario gets updates without being in the loop:**
1. Atomizer's Manager writes a weekly summary to a shared file: `/opt/atomizer/workspaces/manager/reports/weekly-YYYY-WW.md`
2. This file is accessible to Mario's Clawdbot via the shared Obsidian vault or a dedicated Syncthing folder
3. Mario's heartbeat checks for new weekly reports and summarizes in `memory/atomizer/strategic-overview.md`
### 7.4 What Mario Tracks
In `/home/papa/clawd/memory/atomizer/strategic-overview.md`:
```markdown
# Atomizer Strategic Overview
## Current Phase
Phase 0: Proof of Concept (3 agents)
## Active Projects
- StarSpec M1 WFE — Phase: Execution, 47/150 trials
## System Health
- Agents operational: Manager, Secretary, Technical
- Last incident: none
- Cost this month: ~$45
## Architecture Concerns
- Watch: context window usage on Manager (orchestrates everything)
- Watch: Syncthing job queue latency (target <30s)
## Next Milestone
Phase 1 launch: Add Optimizer + Auditor (target: Week 3)
```
---
## 8. Phase 0 Implementation Checklist
### 8.1 Pre-Flight Checks
Before starting, verify:
- [ ] T420 has Docker installed and running
- [ ] T420 has sufficient disk space (>10GB free)
- [ ] Syncthing running and Atomizer repo syncing
- [ ] Anthropic API key valid and funded
- [ ] Antoine has time allocated (need ~5h for Slack setup + testing)
```bash
# Verify Docker
docker --version && docker compose version
# Verify disk space
df -h /opt/
# Verify Syncthing
curl -s http://127.0.0.1:8384/rest/system/status | jq .myID
# Verify API key
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' \
| jq .type
# Should return "message"
```
### 8.2 Step-by-Step Implementation
#### Step 1: Directory Setup (30 min)
```bash
# Create directory structure
sudo mkdir -p /opt/atomizer
sudo chown papa:papa /opt/atomizer
cd /opt/atomizer
mkdir -p clawdbot/credentials clawdbot/skills
mkdir -p workspaces data/sessions data/logs
mkdir -p job-queue/{pending,running,completed,failed}
# Create .env file
cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-... # Same key as Mario's
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...
EOF
chmod 600 .env
```
#### Step 2: Create Shared Skills (2-3 hours)
```bash
# Copy protocols from Atomizer repo
mkdir -p clawdbot/skills/atomizer-protocols/protocols/
# Copy OP and SYS protocols
cp /home/papa/repos/Atomizer/docs/protocols/operations/OP_*.md \
clawdbot/skills/atomizer-protocols/protocols/
cp /home/papa/repos/Atomizer/docs/protocols/system/SYS_*.md \
clawdbot/skills/atomizer-protocols/protocols/
# Create SKILL.md
cat > clawdbot/skills/atomizer-protocols/SKILL.md << 'EOF'
---
name: atomizer-protocols
description: Atomizer Engineering Co. protocols and procedures
version: 1.0
---
# Atomizer Protocols
Load QUICK_REF.md first. Full protocols in protocols/ directory.
EOF
# Copy QUICK_REF
cp /home/papa/repos/Atomizer/docs/QUICK_REF.md \
clawdbot/skills/atomizer-protocols/QUICK_REF.md
# Create company skill
mkdir -p clawdbot/skills/atomizer-company/
cat > clawdbot/skills/atomizer-company/SKILL.md << 'EOF'
---
name: atomizer-company
description: Atomizer Engineering Co. identity and shared knowledge
version: 1.0
---
# Atomizer Company
Read COMPANY.md for company identity and LAC_CRITICAL.md for hard-won lessons.
EOF
cat > clawdbot/skills/atomizer-company/COMPANY.md << 'EOF'
# Atomizer Engineering Co.
## Who We Are
A multi-agent FEA optimization firm. We optimize structural designs using
Siemens NX, Nastran, and advanced algorithms.
## How We Work
- Protocol-driven: every task follows established procedures
- Manager orchestrates, specialists execute
- Antoine (CEO) approves deliverables and strategic decisions
- The Secretary keeps Antoine informed and filters noise
- The Auditor validates everything before it leaves the company
## Our Values
- Physics first: results must make physical sense
- Reproducibility: every study must be re-runnable
- Transparency: all decisions documented and traceable
- Learning: we get smarter with every project
EOF
# Extract critical LAC lessons
cat > clawdbot/skills/atomizer-company/LAC_CRITICAL.md << 'EOF'
# LAC Critical Lessons — NEVER FORGET
These are hard-won insights from past optimization sessions.
## NX Safety
- NEVER kill ugraf.exe directly → use NXSessionManager.close_nx_if_allowed()
- PowerShell for NX journals → NEVER cmd /c
- Always load *_i.prt before UpdateFemodel() → mesh won't update without it
## Optimization
- CMA-ES doesn't evaluate x0 first → always enqueue_trial(x0)
- Surrogate + L-BFGS = dangerous → gradient descent finds fake optima on surrogate
- Never rewrite run_optimization.py from scratch → copy working template
- Relative WFE: use extract_relative() (node-by-node) → NOT abs(RMS_a - RMS_b)
## File Management
- Required file chain: .sim → .fem → *_i.prt → .prt (ALL must be present)
- Trial folders: trial_NNNN/ (zero-padded, never reused, never overwritten)
- Always copy working studies → don't modify originals
EOF
```
#### Step 3: Bootstrap Agent Workspaces (1 hour)
```bash
# Run the bootstrap script from section 3.1
# For Phase 0, we only need 3 agents, but create all for later
chmod +x bootstrap-workspaces.sh
./bootstrap-workspaces.sh
# Customize the 3 Phase 0 agents (Manager, Secretary, Technical)
# Apply role-specific SOUL.md customizations from section 3.2
```
#### Step 4: Write Clawdbot Config (1 hour)
```bash
cat > clawdbot/clawdbot.json << 'JSONEOF'
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-opus-4-6"
},
"compaction": {
"mode": "safeguard",
"memoryFlush": { "enabled": true }
},
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 4,
"model": "anthropic/claude-sonnet-5-20260203"
},
"heartbeat": {
"every": "30m"
}
},
"list": [
{
"id": "manager",
"name": "The Manager",
"default": true,
"workspace": "~/clawd-atomizer-manager",
"model": "anthropic/claude-opus-4-6",
"identity": {
"name": "The Manager",
"emoji": "🎯"
}
},
{
"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": "🔧"
}
}
]
},
"tools": {
"web": {
"search": { "enabled": false },
"fetch": { "enabled": false }
}
},
"channels": {
"slack": {
"mode": "socket",
"enabled": true,
"requireMention": false,
"groupPolicy": "open"
}
},
"gateway": {
"port": 18790,
"mode": "local",
"bind": "0.0.0.0"
}
}
JSONEOF
```
> **Note:** Slack bot/app tokens will be added after Antoine creates the workspace (Step 5).
#### Step 5: Slack Workspace Setup (Antoine — 1 hour)
Antoine does this:
1. Go to https://slack.com/create
2. Workspace name: **Atomizer Engineering**
3. Create channels:
- `#hq`
- `#secretary`
4. Create Slack app: https://api.slack.com/apps → "Create New App" → "From Scratch"
- App name: **Atomizer Agents**
- Workspace: Atomizer Engineering
5. Enable **Socket Mode** (Settings → Socket Mode → Enable)
- Generate App-Level Token (scope: `connections:write`) → save as `SLACK_APP_TOKEN`
6. Add **Bot Token Scopes** (OAuth & Permissions):
- `chat:write`, `channels:read`, `channels:history`, `channels:join`
- `groups:read`, `groups:history`
- `users:read`, `reactions:write`, `reactions:read`, `files:write`
7. Install app to workspace → save Bot Token (`xoxb-...`)
8. **Event Subscriptions** (if not using Socket Mode for events):
- Subscribe to: `message.channels`, `message.groups`, `message.im`, `app_mention`
9. Share tokens with Mario → add to `clawdbot.json`:
```json
{
"channels": {
"slack": {
"botToken": "xoxb-atomizer-...",
"appToken": "xapp-atomizer-..."
}
}
}
```
#### Step 6: Docker Compose Setup (30 min)
```bash
# Create docker-compose.yml (from section 1.3)
# Then start:
cd /opt/atomizer
docker compose up -d
# Verify it's running
docker compose logs -f atomizer-gateway
# Check health
curl http://127.0.0.1:18790/health
```
#### Step 7: Test Routing (1 hour)
**Test 1: Manager responds in `#hq`**
```
Antoine posts in #hq: "Hello, Manager. Can you hear me?"
Expected: Manager responds with 🎯 prefix
```
**Test 2: Secretary responds in `#secretary`**
```
Antoine posts in #secretary: "What's the status of the company?"
Expected: Secretary responds with 📋 prefix, says no active projects
```
**Test 3: Manager delegates to Technical**
```
Antoine posts in #hq: "New job: optimize a simple bracket for minimum mass.
Constraints: max stress < 200 MPa, min frequency > 50 Hz."
Expected flow:
1. Manager acknowledges, creates thread
2. Manager @mentions Technical for breakdown
3. Technical produces structured breakdown (parameters, objectives, constraints)
4. Secretary summarizes to #secretary for Antoine
```
**Test 4: Memory persistence**
```
Close and reopen the session.
Ask Manager: "What was the last project we discussed?"
Expected: Manager reads from memory/ and recalls the bracket discussion
```
#### Step 8: First Real Scenario (2-3 hours)
Run a realistic engineering problem through the 3-agent system:
1. Antoine provides a real project brief (e.g., mirror optimization spec)
2. Manager orchestrates breakdown
3. Technical produces full technical analysis
4. Secretary keeps Antoine updated
5. Test approval flow: Technical identifies a gap → Secretary asks Antoine
**Success criteria for Phase 0:**
- [ ] 3 agents respond correctly when @-mentioned
- [ ] Manager delegates breakdown to Technical
- [ ] Technical produces structured analysis per OP_01
- [ ] Secretary summarizes and escalates appropriately
- [ ] Memory persists across sessions
- [ ] No routing confusion
- [ ] Thread discipline maintained
### 8.3 Phase 0 → Phase 1 Transition
After Phase 0 succeeds, add Optimizer + Auditor:
```bash
# Update clawdbot.json to add 2 more agents
# (their workspaces already exist from bootstrap)
# Add to agents.list:
{
"id": "optimizer",
"name": "The Optimizer",
"workspace": "~/clawd-atomizer-optimizer",
"model": "anthropic/claude-opus-4-6",
"identity": { "name": "The Optimizer", "emoji": "⚡" }
},
{
"id": "auditor",
"name": "The Auditor",
"workspace": "~/clawd-atomizer-auditor",
"model": "anthropic/claude-opus-4-6",
"identity": { "name": "The Auditor", "emoji": "🔍" }
}
# Create #audit-log channel in Slack
# Add Auditor binding
# Restart gateway
docker compose restart atomizer-gateway
```
---
## 9. Security
### 9.1 Agent Access Boundaries
| Resource | Manager | Secretary | Technical | Optimizer | NX Expert | Post-Proc | Reporter | Auditor | Study Builder | Researcher | Developer | KB | IT |
|----------|---------|-----------|-----------|-----------|-----------|-----------|----------|---------|---------------|------------|-----------|----|----|
| Atomizer repo | R | R | R | R | R | R | R | R | R | R | R/W | R | R |
| Obsidian vault | R | R | R | — | — | — | — | R | — | — | — | R | — |
| Job queue | R | R | — | R | — | R | — | R | R/W | — | — | — | R |
| Study results | R | — | — | R | — | R/W | R | R | — | — | — | R | — |
| Agent memory (own) | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W | R/W |
| Agent memory (others) | — | — | — | — | — | — | — | R* | — | — | — | — | — |
| Slack | All | All | Project | Project | Project | Project | Project | All | Project | #research | #dev | #kb | #hq |
| Web access | — | — | — | — | — | — | — | — | — | ✅ | — | — | — |
| Email draft | — | ✅ | — | — | — | — | ✅ | — | — | — | — | — | — |
*Auditor has read access to other agents' memory for audit purposes.
### 9.2 Principle of Least Privilege
**Implemented through:**
1. **Docker volume mounts** — agents only see what's mounted
2. **Read-only mounts** — Atomizer repo and Obsidian are `:ro`
3. **Per-agent AGENTS.md** — explicit rules about what each agent can do
4. **Approval gates** — significant actions require Antoine's OK
5. **Auditor oversight** — Auditor reviews all deliverables and can veto
### 9.3 Mario ↔ Atomizer Isolation
**Critical: no leakage between Mario's and Atomizer's Clawdbot instances.**
| Boundary | How It's Enforced |
|----------|------------------|
| Separate gateways | Mario: native systemd, port 18789. Atomizer: Docker, port 18790 |
| Separate Slack workspaces | Mario: personal workspace. Atomizer: atomizer-eng.slack.com |
| Separate configs | Mario: `~/.clawdbot/`. Atomizer: `/opt/atomizer/clawdbot/` |
| No shared memory | Agents can't read `/home/papa/clawd/` (Mario's workspace) |
| Read-only shared repos | Atomizer reads `/home/papa/repos/Atomizer/` but can't write |
| Separate session storage | Mario: `~/.clawdbot/agents/`. Atomizer: `/opt/atomizer/data/sessions/` |
### 9.4 API Key Management
```bash
# Keys stored in /opt/atomizer/.env (chmod 600)
# Docker Compose reads them via env_file
# Never committed to git
# Same keys as Mario (shared Anthropic Max subscription)
# To rotate keys:
# 1. Update .env
# 2. docker compose restart atomizer-gateway
```
**Cost monitoring:**
- Track per-agent usage via Anthropic/OpenAI dashboards
- Manager reports monthly cost in weekly summary
- Budget alert if monthly spend > $150 (Phase 0) / $400 (Phase 3)
### 9.5 Slack Security
- Separate Slack workspace = separate permissions
- Bot token has minimal scopes (no admin, no user impersonation)
- Socket Mode = no public webhook URL
- Antoine is the only human user (single-tenant)
- If workspace is used for demos: create a `#demo` channel, agents know not to share sensitive data there
---
## 10. Future-Proofing
### 10.1 MCP Server Integration Path
The Atomizer repo already has an `mcp-server/` directory. Long-term, agents interact with Atomizer through MCP tools instead of direct file access:
```
Current: Agent reads /mnt/atomizer-repo/docs/protocols/OP_01.md
Future: Agent calls mcp.atomizer.get_protocol("OP_01")
Current: Agent reads study.db directly
Future: Agent calls mcp.atomizer.get_study_status("starspec-m1")
Current: Agent writes job.json to /mnt/job-queue/
Future: Agent calls mcp.atomizer.submit_job({...})
```
**When to build:** After Phase 2 succeeds. MCP provides better abstraction but adds complexity. Don't block on it.
### 10.2 Client Portal
Eventually, clients could interact with a stripped-down interface:
```
Client → Web portal → Reporter agent (read-only)
→ Secretary agent (questions)
→ Manager agent (status updates)
```
**Prerequisites:** Authentication, access control, sanitized output. Phase 4+ at earliest.
### 10.3 Voice Interface
Antoine's walkthroughs are already voice-first (screen recording + transcript). Future:
```
Antoine speaks → Whisper transcription → Secretary agent processes
→ KB agent indexes model knowledge
```
Could integrate with Clawdbot's existing TTS/voice capabilities. Medium priority.
### 10.4 Dashboard Agent Integration
The Atomizer Dashboard runs on Windows. Future integration:
```
Dashboard API (FastAPI backend)
↕
Agent makes API calls to dashboard
↕
Dashboard reflects agent-triggered study state
```
Requires: Dashboard API accessible from Docker (via Tailscale). Medium priority.
### 10.5 Scaling to Multiple Projects
Current architecture handles this naturally:
- Each project gets a channel (`#clienta-thermal`, `#clientb-modal`)
- Manager tracks all projects in its memory
- Agents serve multiple projects (stateless between projects, context via memory/)
- Concurrency limit: `maxConcurrent: 4` prevents overload
**When project volume increases:**
- Add a second Manager (e.g., Manager A for client work, Manager B for internal development)
- Split into sub-teams with dedicated channels
- Consider model downgrades for routine projects to save costs
### 10.6 Multi-Model Evolution
Architecture is model-agnostic. When new models release:
```json
// Just update clawdbot.json:
{
"id": "optimizer",
"model": "anthropic/claude-opus-5-0" // Upgrade when available
}
```
Current model assignments (ref DEC-A008):
| Role | Current | Upgrade Path |
|------|---------|-------------|
| Manager, Auditor | Opus 4.6 | Opus 5.x when available |
| Technical, Optimizer | Opus 4.6 | Opus 5.x or specialized reasoning model |
| NX Expert, Post-Proc, Reporter | Sonnet 5 | Keep on latest Sonnet |
| Study Builder | GPT-5.3-Codex | Codex 6.x or Claude Code model |
| Researcher | Gemini 3.0 | Gemini 3.x or Gemini Ultra |
| Developer, KB, IT | Sonnet 5 | Keep on latest Sonnet |
---
## Appendix A: Complete clawdbot.json (Phase 3 — Full Company)
```json5
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-opus-4-6",
"fallbacks": ["anthropic/claude-sonnet-5-20260203"]
},
"compaction": {
"mode": "safeguard",
"memoryFlush": { "enabled": true }
},
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 6,
"model": "anthropic/claude-sonnet-5-20260203"
},
"heartbeat": {
"every": "30m"
}
},
"list": [
// Core
{ "id": "manager", "name": "The Manager", "default": true,
"workspace": "~/clawd-atomizer-manager",
"model": "anthropic/claude-opus-4-6",
"identity": { "name": "The Manager", "emoji": "🎯" }
},
{ "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": "⚡" }
},
{ "id": "study-builder", "name": "The Study Builder",
"workspace": "~/clawd-atomizer-study-builder",
"model": "openai/gpt-5.3-codex",
"identity": { "name": "The Study Builder", "emoji": "🏗️" }
},
// Specialists
{ "id": "nx-expert", "name": "The NX Expert",
"workspace": "~/clawd-atomizer-nx-expert",
"model": "anthropic/claude-sonnet-5-20260203",
"identity": { "name": "The NX Expert", "emoji": "🖥️" }
},
{ "id": "postprocessor", "name": "The Post-Processor",
"workspace": "~/clawd-atomizer-postprocessor",
"model": "anthropic/claude-sonnet-5-20260203",
"identity": { "name": "The Post-Processor", "emoji": "📊" }
},
{ "id": "reporter", "name": "The Reporter",
"workspace": "~/clawd-atomizer-reporter",
"model": "anthropic/claude-sonnet-5-20260203",
"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": "🔍" }
},
// Support
{ "id": "researcher", "name": "The Researcher",
"workspace": "~/clawd-atomizer-researcher",
"model": "google/gemini-3.0-pro",
"identity": { "name": "The Researcher", "emoji": "🔬" }
},
{ "id": "developer", "name": "The Developer",
"workspace": "~/clawd-atomizer-developer",
"model": "anthropic/claude-sonnet-5-20260203",
"identity": { "name": "The Developer", "emoji": "💻" }
},
{ "id": "knowledge-base", "name": "The Knowledge Base",
"workspace": "~/clawd-atomizer-kb",
"model": "anthropic/claude-sonnet-5-20260203",
"identity": { "name": "The Knowledge Base", "emoji": "🗄️" }
},
{ "id": "it-support", "name": "IT Support",
"workspace": "~/clawd-atomizer-it",
"model": "anthropic/claude-sonnet-5-20260203",
"identity": { "name": "IT Support", "emoji": "🛠️" }
}
]
},
"bindings": [
// Manager: HQ + fallback for all unbound channels
{ "agentId": "manager",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#hq" } } },
// Secretary: dedicated channel + DMs
{ "agentId": "secretary",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#secretary" } } },
{ "agentId": "secretary",
"match": { "channel": "slack", "peer": { "kind": "dm" } } },
// Specialized channels
{ "agentId": "auditor",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#audit-log" } } },
{ "agentId": "researcher",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#research" } } },
{ "agentId": "developer",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#dev" } } },
{ "agentId": "knowledge-base",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#knowledge-base" } } },
// Framework evolution → Manager (steward role)
{ "agentId": "manager",
"match": { "channel": "slack", "peer": { "kind": "group", "name": "#framework-evolution" } } },
// Fallback: all other channels → Manager
{ "agentId": "manager",
"match": { "channel": "slack", "peer": { "kind": "group" } },
"priority": -1 }
],
"tools": {
"web": {
"search": { "enabled": true, "apiKey": "..." },
"fetch": { "enabled": true }
}
},
"channels": {
"slack": {
"mode": "socket",
"enabled": true,
"botToken": "xoxb-atomizer-...",
"appToken": "xapp-atomizer-...",
"requireMention": false,
"groupPolicy": "open",
"dm": {
"enabled": true,
"policy": "open"
}
}
},
"gateway": {
"port": 18790,
"mode": "local",
"bind": "0.0.0.0",
"auth": {
"mode": "token",
"token": "..."
}
}
}
```
---
## Appendix B: Decision Log References
| Decision | Reference | Status | Impact on This Plan |
|----------|-----------|--------|---------------------|
| Clawdbot platform | DEC-A001 | ✅ | Entire architecture built on Clawdbot |
| Phased rollout | DEC-A002 | ✅ | Phase 0 → 3 in Section 8 |
| Manager bottleneck | DEC-A003 | ✅ | Communication hierarchy in Section 6 |
| Single gateway | DEC-A004 | ✅ | Docker setup in Section 1 |
| Model tiering | DEC-A005 + DEC-A008 | ✅ | Agent configs throughout |
| Dedicated Slack | DEC-A006 | ✅ | Slack architecture in Section 4 |
| Study Builder agent | DEC-A007 | ✅ | Study Builder in all sections |
| Latest models | DEC-A008 | ✅ | Model assignments in configs |
| Autonomous + gates | DEC-A009 | ✅ | Approval gates in Section 6 |
| Manager as steward | DEC-A010 | ✅ | Manager SOUL.md in Section 3 |
**Decisions resolved by this plan:**
| Decision | Resolution |
|----------|-----------|
| DEC-A011: Windows execution | Syncthing job queue (primary) + Tailscale SSH (optional). Section 5 |
| DEC-A012: Separate vs extend gateway | **Separate Docker gateway.** Section 1 |
| DEC-A013: One bot vs per-agent bots | **Single bot, agent prefixes in messages.** Section 4 |
| DEC-A014: KB Agent processing | **File watcher + heartbeat poll.** Section 3 |
---
## Appendix C: Cost Model
### Per-Phase Monthly Estimates
| Phase | Active Agents | Model Mix | Est. Monthly Cost |
|-------|--------------|-----------|-------------------|
| Phase 0 | 3 (Opus 4.6) | All Opus | $50–100 |
| Phase 1 | 5 (3 Opus + 2 Opus) | All Opus | $100–200 |
| Phase 2 | 9 (5 Opus + 4 Sonnet) | Mixed | $200–350 |
| Phase 3 | 13 (5 Opus + 6 Sonnet + 1 Codex + 1 Gemini) | Mixed | $300–500 |
### Per-Project Estimates
| Project Type | Agents Involved | Turns | Est. Cost |
|-------------|----------------|-------|-----------|
| Simple optimization | Manager, Technical, Optimizer, Study Builder | ~40 | $15–25 |
| Full pipeline | All core + specialists | ~70 | $25–40 |
| Complex multi-phase | All agents | ~120 | $40–65 |
### Cost Controls
1. Wake-on-demand: agents only activate when @-mentioned
2. Heartbeat interval: 30 min (not 5 min)
3. Sub-agent timeouts: `runTimeoutSeconds: 600` (10 min max)
4. Context pruning: `cache-ttl: 1h`
5. Session auto-archive after idle
6. Sonnet for routine work, Opus only for reasoning-heavy tasks
---
*This is the implementation blueprint. Everything above is actionable — not theoretical. When Antoine gives the green light, execute Phase 0 step by step. The company starts with 3 agents and grows to 13 over 10 weeks.*
*Written: 2026-02-08 by Mario*
*References: 00-PROJECT-PLAN, 01-AGENT-ROSTER, 02-ARCHITECTURE, 03-ROADMAP, 04-DECISION-LOG*
Reference in New Issue Copy Permalink