Atomizer/docs/hq/03-ROADMAP.md

# 🗺️ Roadmap — Atomizer Overhaul: Framework Agentic

> Phased implementation plan. Start small, prove the pattern, scale systematically.

---

## Timeline Overview

```
Phase 0: Proof of Concept     [Week 1-2]     3 agents, basic routing, dedicated Slack
Phase 1: Core Team             [Week 3-4]     6 agents, full planning + study build cycle  
Phase 2: Specialists           [Week 5-7]     10 agents, full pipeline
Phase 3: Full Company          [Week 8-10]    13 agents, all capabilities
Phase 4: Optimization          [Ongoing]      Polish, performance, learning
```

---

## Phase 0: Proof of Concept (Week 1-2)

**Goal:** Prove multi-agent orchestration works in Clawdbot + Slack.

### Tasks

| # | Task | Owner | Est. Time | Status |
|---|------|-------|-----------|--------|
| 0.1 | Create **dedicated Slack workspace** "Atomizer Engineering" | Antoine | 30 min | ⏳ Waiting |
| 0.1b | Create channels: `#hq`, `#secretary` | Antoine | 15 min | ⏳ Waiting |
| 0.1c | Create Slack app + get tokens (see README-ANTOINE) | Antoine | 20 min | ⏳ Waiting |
| 0.1d | Install Docker on T420 | Antoine | 10 min | ⏳ Waiting |
| 0.2 | Set up 3 agent workspaces: Manager, Secretary, Technical Lead | Mario | 2-3 hours | ✅ Done (2026-02-08) |
| 0.3 | Write SOUL.md + AGENTS.md + IDENTITY.md + USER.md + TOOLS.md for each | Mario | 2-3 hours | ✅ Done (2026-02-08) |
| 0.4 | Create `atomizer-protocols` shared skill (with real protocols) | Mario | 2-3 hours | ✅ Done (2026-02-08) |
| 0.4b | Create `atomizer-company` shared skill (identity + LAC_CRITICAL) | Mario | 1 hour | ✅ Done (2026-02-08) |
| 0.4c | Write new protocols: OP_09, OP_10, SYS_19, SYS_20 | Mario | 1 hour | ✅ Done (2026-02-08) |
| 0.5 | Write docker-compose.yml + clawdbot.json config | Mario | 1-2 hours | ✅ Done (2026-02-08) |
| 0.5b | Write .env.template + Windows job watcher script | Mario | 30 min | ✅ Done (2026-02-08) |
| 0.6 | Plug in tokens, boot Docker, test routing | Mario + Antoine | 1 hour | ⏳ Blocked on 0.1 |
| 0.7 | Test: Manager delegates to Technical | Both | 1 hour | ⏳ Blocked on 0.6 |
| 0.8 | Test: Secretary summarizes for Antoine | Both | 1 hour | ⏳ Blocked on 0.6 |
| 0.9 | Run one real engineering problem through the system | Both | 2-3 hours | ⏳ Blocked on 0.7 |
| 0.10 | Retrospective: what worked, what didn't | Both | 1 hour | ⏳ Blocked on 0.9 |

### Implementation Progress
**Mario's work: 100% complete** (2026-02-08)
- All at `/home/papa/atomizer/`
- 35+ files: workspaces, skills, config, docker-compose, protocols, scripts

**Blocked on Antoine:**
1. Install Docker on T420 (`sudo apt install docker.io docker-compose-v2 -y`)
2. Create Slack workspace + app (manifest in README-ANTOINE)
3. Provide tokens (xoxb + xapp + channel IDs)

### Success Criteria
- [ ] 3 agents respond correctly when @-mentioned in Slack
- [ ] Manager successfully delegates a breakdown task to Technical
- [ ] Secretary correctly summarizes and relays to Antoine
- [ ] Memory persists across agent sessions
- [ ] No routing confusion (messages go to right agent)

### Key Decisions — ALL RESOLVED ✅
- ✅ Project channels → Manager (fallback binding catches all unbound channels)
- ✅ Single bot token, per-agent identity via `chat:write.customize` (DEC-A013)
- ✅ Shared skills for company DNA, per-agent SOUL/AGENTS/MEMORY for specialization

---

## Phase 1: Core Team (Week 3-4)

**Goal:** Full planning cycle — intake through study build and optimization launch.

### New Agents
- ⚡ Optimizer
- 🏗️ Study Builder
- 🔍 Auditor

### Tasks

| # | Task | Owner | Est. Time | Dependencies |
|---|------|-------|-----------|--------------|
| 1.1 | Set up Optimizer + Study Builder + Auditor workspaces | Mario | 3 hours | Phase 0 |
| 1.2 | Write SOUL.md + AGENTS.md with LAC critical lessons | Mario | 4-5 hours | 1.1 |
| 1.3 | Create `atomizer-spec` skill for Optimizer + Study Builder | Mario | 2 hours | — |
| 1.4 | Migrate LAC critical lessons to Optimizer's + Study Builder's MEMORY.md | Mario | 1 hour | 1.2 |
| 1.5 | Create Auditor's review checklist protocol | Mario | 2 hours | — |
| 1.6 | Seed Study Builder with V15 run_optimization.py as gold template | Mario | 1 hour | 1.1 |
| 1.7 | Test full planning cycle: problem → breakdown → algorithm → study code | Both | 3-4 hours | 1.1-1.6 |
| 1.8 | Test Auditor review of optimization plan + study code | Both | 1-2 hours | 1.7 |
| 1.9 | Run a real optimization job through the system (code → Windows → results) | Both | 4-8 hours | 1.7 |
| 1.10 | Retrospective | Both | 1 hour | 1.9 |

### Success Criteria
- [ ] Technical Lead → Optimizer → Study Builder handoff works smoothly
- [ ] Study Builder produces valid run_optimization.py from Optimizer's design
- [ ] Optimizer produces valid AtomizerSpec from Technical's breakdown
- [ ] Auditor catches at least one issue in the plan or code
- [ ] < 30 minutes from problem statement to approved optimization plan
- [ ] Study code syncs to Windows and runs successfully
- [ ] All agents stay in character and follow protocols

---

## Phase 2: Specialists (Week 5-7)

**Goal:** Full pipeline from intake to client-ready deliverable. R&D channels operational.

### New Agents
- 🖥️ NX Expert
- 📊 Post-Processor
- 📝 Reporter
- 🗄️ Knowledge Base

### New Channels
- `#audit-log`, `#knowledge-base`
- First R&D channel: `#rd-<topic>` (Antoine picks)

### Tasks

| # | Task | Owner | Est. Time | Dependencies |
|---|------|-------|-----------|--------------|
| 2.1 | Set up 4 specialist workspaces | Mario | 3 hours | Phase 1 |
| 2.2 | Write specialized SOUL.md + AGENTS.md | Mario | 4-6 hours | 2.1 |
| 2.3 | Create NX reference skill from existing docs | Mario | 3-4 hours | — |
| 2.4 | Create post-processing skill (extractors, Zernike) | Mario | 3-4 hours | — |
| 2.5 | Integrate atomaste-reports skill for Reporter | Mario | 1 hour | — |
| 2.6 | Integrate cad-documenter skill for KB Agent | Mario | 1 hour | — |
| 2.7 | Test full pipeline: intake → report | Both | 6-8 hours | 2.1-2.6 |
| 2.8 | Test KB Agent processing CAD Documenter output | Both | 2-3 hours | 2.6 |
| 2.9 | Test Reporter generating Atomaste PDF | Both | 2-3 hours | 2.5 |
| 2.10 | Run 2-3 real projects through full pipeline | Both | Multi-day | 2.7 |
| 2.11 | Retrospective | Both | 1 hour | 2.10 |

### Success Criteria
- [ ] NX Expert provides solver config that Optimizer can use
- [ ] Post-Processor generates visualizations from real results
- [ ] Reporter produces client-ready PDF report
- [ ] KB Agent successfully indexes a CAD Documenter walkthrough
- [ ] End-to-end: client problem → approved report in < 1 day (FEA time excluded)

---

## Phase 3: Full Company (Week 8-10)

**Goal:** Complete ecosystem with all support roles.

### New Agents
- 🔬 Researcher
- 💻 Developer
- 🛠️ IT Support

### Tasks

| # | Task | Owner | Est. Time | Dependencies |
|---|------|-------|-----------|--------------|
| 3.1 | Set up remaining 3 workspaces | Mario | 2 hours | Phase 2 |
| 3.2 | Write specialized SOUL.md + AGENTS.md | Mario | 3-4 hours | 3.1 |
| 3.3 | Configure Researcher with web_search + Gemini | Mario | 1-2 hours | 3.1 |
| 3.4 | Configure Developer with Git access | Mario | 1-2 hours | 3.1 |
| 3.5 | Test Researcher literature search workflow | Both | 2 hours | 3.3 |
| 3.6 | Test Developer coding + PR workflow | Both | 2 hours | 3.4 |
| 3.7 | Full company stress test: complex multi-phase project | Both | Multi-day | All |
| 3.8 | Cost analysis and optimization | Mario | 2 hours | 3.7 |
| 3.9 | Retrospective + full documentation | Both | 2-3 hours | 3.8 |

### Success Criteria
- [ ] All 13 agents operational and in-character
- [ ] Researcher provides useful literature for optimization method selection
- [ ] Developer successfully codes and tests a new extractor
- [ ] System handles a complex project with multiple specialists involved
- [ ] Per-project cost within acceptable range ($20-40)
- [ ] Antoine's time per project < 20% (rest is agents)

---

## Phase 4: Optimization (Ongoing)

**Goal:** Continuous improvement of the company.

### Continuous Tasks

| Task | Frequency | Owner |
|------|-----------|-------|
| Review and update agent MEMORY.md files | After each project | Each agent |
| Update protocols based on lessons learned | Monthly | Manager + Antoine |
| Review token usage and optimize context sizes | Bi-weekly | Mario |
| Improve agent SOUL.md based on behavior | As needed | Mario + Antoine |
| Add new skills as capabilities expand | As needed | Developer + Mario |
| Cross-train agents (share insights between roles) | Monthly | Manager |

### Future Enhancements (Not Blocked On)

| Enhancement | Priority | Effort | Notes |
|-------------|----------|--------|-------|
| MCP server integration | Medium | High | Agents access Atomizer via MCP tools |
| Voice interface (Whisper live) | Low | Medium | Antoine talks, agents listen |
| Dashboard integration | Medium | High | Agents control dashboard directly |
| Automated project channel creation | Medium | Low | Manager creates channels via API |
| Client portal | Low | High | Clients interact directly with system |
| Agent performance metrics | Medium | Medium | Track quality, speed, token usage per agent |

---

## Resource Requirements

### Hardware
- **Current Clawdbot server** — should handle 13 agents (they're not all active simultaneously)
- **Disk:** ~500MB for agent workspaces + session storage
- **RAM:** Monitor after Phase 1; may need increase for concurrent agents

### API Budget
- **Phase 0:** ~$50/month (3 agents, testing)
- **Phase 1:** ~$100-150/month (6 agents, real projects)
- **Phase 2:** ~$200-250/month (10 agents, full pipeline)
- **Phase 3:** ~$300-400/month (13 agents, full operations)
- **Steady state:** Depends on project volume; ~$25-40 per client job

### Time Investment
- **Phase 0:** ~15-20 hours (Mario: ~12h, Antoine: ~5h)
- **Phase 1:** ~20-25 hours (Mario: ~15h, Antoine: ~8h)
- **Phase 2:** ~30-40 hours (Mario: ~25h, Antoine: ~12h)
- **Phase 3:** ~20-25 hours (Mario: ~15h, Antoine: ~8h)
- **Total:** ~85-110 hours over 10 weeks

---

## Immediate Next Steps

### ✅ COMPLETED (Mario — 2026-02-08)
- [x] Set up Phase 0 agent workspaces (Manager, Secretary, Technical Lead)
- [x] Write SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md, MEMORY.md for each
- [x] Create `atomizer-protocols` shared skill with all 17 real protocols + 4 new ones
- [x] Create `atomizer-company` shared skill with identity + LAC_CRITICAL.md
- [x] Write `docker-compose.yml` and `clawdbot.json` multi-agent config
- [x] Write `.env.template` for token management
- [x] Write Windows job watcher script (`atomizer_job_watcher.py`)
- [x] Create job queue directory structure
- [x] Write README-ANTOINE with full step-by-step setup guide

**All files at:** `/home/papa/atomizer/`

### ✅ COMPLETED (Antoine — 2026-02-08)
- [x] Created Slack workspace: **Atomizer HQ** (`atomizer-hq.slack.com`)
- [x] Created Slack app with manifest
- [x] Created channels: `#all-atomizer-hq`, `#secretary`
- [x] Provided tokens to Mario

### ✅ COMPLETED (Mario — 2026-02-08, afternoon)
- [x] Pivoted from Docker to native second gateway (no Docker image available)
- [x] Gateway running on port 18790 with state dir `~/.clawdbot-atomizer/`
- [x] Slack Socket Mode connected to Atomizer HQ workspace
- [x] Channel bindings configured: Manager → `#all-atomizer-hq`, Secretary → `#secretary`
- [x] Auth profiles shared (same Anthropic OAuth)
- [x] Shared skills symlinked into state dir

### 🟢 Phase 0 LIVE — Current Status (2026-02-08 18:00 UTC)
- **Gateway:** Running natively at port 18790
- **Agents active:** Manager (🎯), Secretary (📋), Technical Lead (🔧)
- **Slack connected:** Atomizer HQ workspace
- **Tools:** All standard Clawdbot tools (read, write, exec, web_search, etc.)
- **Skills:** atomizer-protocols (21 protocols), atomizer-company

### ⏳ NEXT: Phase 0 Validation
1. Test Manager orchestration in `#all-atomizer-hq`
2. Test Secretary reporting in `#secretary`
3. Run a real engineering problem through 3-agent system
4. Validate memory persistence across sessions
5. Retrospective → tune SOUL.md and protocols

### 🔜 Phase 1 Prep (after Phase 0 validated)
1. Add 3 new agents: Optimizer, Study Builder, Auditor
2. Create workspaces + SOUL/AGENTS files
3. Update gateway config with new agent entries + bindings
4. Seed Study Builder with V15 gold template
5. Migrate LAC lessons to agent memories

---

*Created: 2026-02-07 by Mario*
*Updated: 2026-02-08 — Phase 0 LIVE, gateway running, 3 agents operational*