Atomizer/docs/hq/README.md

# Atomizer-HQ Agent Documentation

**Version**: 1.0  
**Created**: February 2026  
**Target Audience**: AI Agents (Manager, Secretary, Technical Lead, etc.)

---

## What is Atomizer-HQ?

Atomizer-HQ is a multi-agent optimization team that runs FEA optimization projects for clients. Built on top of the Atomizer optimization framework, it provides a structured workflow from client intake through project delivery.

**The Team**:
- 📋 **Secretary** — CEO interface, admin, client intake
- 🏗️ **Manager** — Project coordination, workflow orchestration  
- 🔧 **Technical Lead** — FEA expertise, R&D leadership
- ⚡ **Optimizer** — Study execution, optimization runs
- 🔍 **Auditor** — Quality assurance, deliverable review
- 📊 **Post-Processor** — Results analysis, visualization
- 📝 **Reporter** — Technical documentation, client reports

---

## How to Use These Docs

This documentation provides agent-specific guidance for:

1. **Project Structure** — How projects are organized
2. **Knowledge Base Usage** — Accumulating and sharing domain knowledge
3. **Agent Workflows** — Who does what, when, and how
4. **Study Conventions** — Technical study execution standards

### Essential Reading for All Agents

| Document | Purpose |
|----------|---------|
| **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** | Standard project layout and conventions |
| **[KB_CONVENTIONS.md](KB_CONVENTIONS.md)** | Knowledge base usage and accumulation |
| **[AGENT_WORKFLOWS.md](AGENT_WORKFLOWS.md)** | Project lifecycle and agent handoffs |

### Role-Specific Guides

| Document | Target Agents |
|----------|---------------|
| **[STUDY_CONVENTIONS.md](STUDY_CONVENTIONS.md)** | Technical Lead, Optimizer, Study Builder |

---

## Quick Reference

### Project Phases
1. **Intake** → Secretary handles client requirements
2. **Breakdown** → Manager coordinates project setup  
3. **Introspection** → Technical Lead analyzes requirements
4. **Study** → Optimizer executes FEA optimization
5. **Results** → Post-Processor analyzes outcomes
6. **Deliverables** → Reporter generates client materials

### Key Principles
- **KB Accumulation**: Add knowledge, never replace
- **Single Source of Truth**: Projects have one authoritative structure
- **Quality Gates**: No deliverable goes to CEO without review
- **Clear Handoffs**: Use OP_09 communication protocols

### Living Examples
- **Reference Project**: `projects/hydrotech-beam/` — Complete project structure
- **Active Studies**: `studies/` — Study execution examples
- **Knowledge Base**: `knowledge_base/` — Accumulated domain expertise

---

## Getting Started

### New Agent Onboarding
1. Read your role in `context-docs/01-AGENT-ROSTER.md`
2. Review the project structure in `PROJECT_STRUCTURE.md`
3. Understand KB conventions in `KB_CONVENTIONS.md`
4. Check active projects in `projects/` for context

### Starting a New Project
1. Secretary creates project intake
2. Manager sets up project structure (see `PROJECT_STRUCTURE.md`)
3. Technical Lead performs introspection
4. Follow workflows in `AGENT_WORKFLOWS.md`

### Contributing to Documentation
- These docs evolve based on agent experience
- Update conventions when patterns emerge
- Flag inconsistencies or missing guidance
- CEO (Antoine) approves major changes

---

## Integration with Core Atomizer

Atomizer-HQ builds on the core optimization framework:

**Core Framework** (engineers + Claude Code):
- `protocols/` — Operational and system protocols
- `api/` — NX integration and technical APIs
- `optimization_engine/` — Core FEA optimization algorithms

**HQ Layer** (multi-agent team):
- `projects/` — Client project workspaces
- `knowledge_base/` — Accumulated domain expertise
- Agent-specific workflows and conventions

---

## Support and Evolution

- **Questions**: Ask in #hq channel or direct agent messages  
- **Issues**: Flag problems in daily coordination
- **Updates**: Documentation evolves with team experience
- **Approval**: CEO (Antoine) reviews major changes

Last updated: February 2026