Atomizer/docs/hq/AGENT_WORKFLOWS.md

# Agent Workflows

**Version**: 1.0  
**Created**: February 2026  
**Reference**: OP_09 Communication Protocols

---

## Project Lifecycle Overview

Every Atomizer-HQ project follows a structured workflow with clear phases and agent handoffs. Understanding who does what, when, and how ensures smooth project execution and quality deliverables.

### Six-Phase Project Lifecycle

```
Intake → Breakdown → Introspection → Study → Results → Deliverables
  ↓         ↓            ↓          ↓       ↓           ↓
Secretary  Manager  Technical Lead  Optimizer  Post-Processor  Reporter
```

---

## Phase 1: Intake (Secretary)

**Responsibility**: Client interface, requirement capture, project initiation  
**Duration**: 1-2 days  
**Deliverable**: Project intake document

### Secretary Tasks
1. **Client Communication**
   - Receive and clarify project requirements
   - Identify scope, timeline, budget constraints
   - Gather technical specifications and constraints
   - Establish client communication preferences

2. **Initial Assessment**
   - Assess project complexity and feasibility
   - Estimate required resources and timeline
   - Identify potential technical challenges
   - Flag any special requirements or risks

3. **Project Initiation**
   - Create initial project folder structure
   - Document client requirements in structured format
   - Create `project_metadata.json` with basic info
   - Schedule handoff meeting with Manager

### Secretary Deliverables
- **Client Requirements Document** — Structured requirements capture
- **Project Metadata** — `project_metadata.json` with client info
- **Initial Risk Assessment** — Potential challenges identified
- **Resource Estimate** — Preliminary timeline and effort estimate

### Handoff to Manager
**Communication**: Direct message with project summary  
**Artifacts**: Requirements document, metadata file, risk assessment  
**Meeting**: Handoff discussion to clarify any ambiguities

---

## Phase 2: Breakdown (Manager) 

**Responsibility**: Project structuring, team coordination, workflow planning  
**Duration**: 1-2 days  
**Deliverable**: Complete project structure and execution plan

### Manager Tasks
1. **Project Structure Setup**
   - Complete directory structure per `PROJECT_STRUCTURE.md`
   - Initialize Knowledge Base framework
   - Set up study planning structure
   - Establish project documentation standards

2. **Team Coordination**
   - Assign Technical Lead and other team members
   - Define agent responsibilities and interfaces
   - Establish communication channels and schedules
   - Plan handoff points and review gates

3. **Execution Planning**
   - Break down project into specific technical tasks
   - Estimate timeline for each phase
   - Identify dependencies and critical path
   - Plan quality gates and review checkpoints

4. **Risk Management**
   - Review and refine initial risk assessment
   - Plan mitigation strategies
   - Identify decision points and escalation paths
   - Establish contingency plans

### Manager Deliverables
- **Complete Project Structure** — Full directory hierarchy
- **Execution Plan** — Timeline, milestones, dependencies
- **Team Assignments** — Agent roles and responsibilities
- **Communication Plan** — Channels, schedules, reporting structure

### Handoff to Technical Lead
**Communication**: Project kickoff meeting with full team  
**Artifacts**: Complete project structure, execution plan, team assignments  
**Review**: Executive summary of client requirements and constraints

---

## Phase 3: Introspection (Technical Lead)

**Responsibility**: Technical analysis, model setup, optimization planning  
**Duration**: 2-5 days  
**Deliverable**: Technical foundation and study plan

### Technical Lead Tasks
1. **Technical Requirements Analysis**
   - Review client requirements from engineering perspective
   - Identify technical constraints and design criteria
   - Establish performance metrics and success criteria
   - Define technical scope and boundaries

2. **Model Setup and Validation**
   - Set up reference CAD and FEA models
   - Validate baseline model performance
   - Establish modeling conventions and assumptions
   - Create model documentation and KB entries

3. **Optimization Strategy Development**
   - Define design variables and constraints
   - Select optimization objectives and metrics
   - Plan study sequence and progression
   - Estimate computational requirements

4. **Knowledge Base Initialization**
   - Create initial component knowledge files
   - Document material properties and constraints
   - Establish FEA conventions and assumptions
   - Initialize lessons learned framework

### Technical Lead Deliverables
- **Technical Requirements** — Engineering interpretation of client needs
- **Reference Models** — Validated baseline CAD and FEA models  
- **Study Plan** — Optimization strategy and study sequence
- **Initial KB** — Component, material, and FEA knowledge foundation

### Handoff to Optimizer
**Communication**: Technical handoff meeting  
**Artifacts**: Study plan, reference models, technical requirements  
**Training**: Model setup, conventions, and optimization strategy

---

## Phase 4: Study Execution (Optimizer)

**Responsibility**: FEA optimization execution, results generation  
**Duration**: 3-10 days (depends on complexity)  
**Deliverable**: Optimization results and raw data

### Optimizer Tasks  
1. **Study Setup**
   - Create study directories per `STUDY_CONVENTIONS.md`
   - Copy reference models to study workspace
   - Configure optimization parameters and settings
   - Validate model functionality and convergence

2. **Optimization Execution**
   - Execute optimization studies per study plan
   - Monitor progress and convergence
   - Troubleshoot any model or solver issues
   - Adjust parameters as needed for convergence

3. **Results Collection**
   - Extract optimization results and performance data
   - Document any issues or unexpected behaviors
   - Create result summaries and best trial identification
   - Archive study data and intermediate results

4. **Knowledge Contribution**
   - Document optimization insights and findings
   - Update component behavior knowledge
   - Note any modeling issues or improvements
   - Record algorithmic performance observations

### Optimizer Deliverables
- **Study Results** — Complete optimization output data
- **Best Designs** — Optimized model files and parameters
- **Execution Log** — Study progression and issue documentation
- **KB Contributions** — Optimization insights and lessons learned

### Handoff to Post-Processor
**Communication**: Results review meeting  
**Artifacts**: Study results, best designs, execution documentation  
**Context**: Any issues encountered, unexpected behaviors, recommendations

---

## Phase 5: Results Analysis (Post-Processor)

**Responsibility**: Results analysis, validation, insight generation  
**Duration**: 2-4 days  
**Deliverable**: Analyzed results and engineering insights

### Post-Processor Tasks
1. **Results Validation** 
   - Verify optimization results for engineering reasonableness
   - Validate best designs against technical requirements
   - Check constraint satisfaction and safety margins
   - Perform sensitivity analysis on key parameters

2. **Performance Analysis**
   - Quantify performance improvements achieved
   - Analyze trade-offs between competing objectives
   - Identify design trends and behavioral patterns
   - Compare results to baseline and requirements

3. **Insight Generation**
   - Extract engineering insights and design principles
   - Identify key parameters and sensitivities
   - Document unexpected findings and behaviors
   - Generate recommendations for future work

4. **Visualization and Documentation**
   - Create plots, charts, and visual summaries
   - Generate technical analysis documentation
   - Prepare result summaries for stakeholder review
   - Update Knowledge Base with analysis insights

### Post-Processor Deliverables
- **Results Analysis** — Comprehensive technical analysis
- **Performance Summary** — Quantified improvements and metrics
- **Engineering Insights** — Design principles and recommendations
- **Visual Documentation** — Plots, charts, and graphical summaries

### Handoff to Reporter  
**Communication**: Analysis review meeting  
**Artifacts**: Analysis results, performance summary, visual documentation  
**Focus**: Key findings, recommendations, and client-relevant insights

---

## Phase 6: Deliverables (Reporter)

**Responsibility**: Client-facing documentation, final report generation  
**Duration**: 2-3 days  
**Deliverable**: Complete client deliverable package

### Reporter Tasks
1. **Technical Report Generation**
   - Synthesize all project work into cohesive technical report
   - Translate engineering insights into client-relevant language
   - Structure report for client technical and management audiences
   - Include methodology, results, and recommendations

2. **Deliverable Package Assembly**
   - Organize optimized models and supporting data
   - Create executive summary for management audience
   - Prepare technical appendices and detailed data
   - Package files for client delivery

3. **Quality Review and Finalization**
   - Review all deliverables for completeness and quality
   - Ensure consistency across all documentation
   - Validate technical accuracy and clarity
   - Prepare final delivery package

4. **Client Communication Support**
   - Prepare presentation materials if requested
   - Support client Q&A and follow-up discussions
   - Document any post-delivery support requirements
   - Plan potential follow-on work identification

### Reporter Deliverables
- **Technical Report** — Comprehensive project documentation
- **Executive Summary** — Management-focused summary
- **Optimized Models** — Final design files and supporting data
- **Delivery Package** — Complete client deliverable set

### Final Handoff to CEO
**Communication**: Project completion review  
**Artifacts**: Complete deliverable package, project summary  
**Review**: Quality gate before CEO approval and client delivery

---

## Communication Protocols

### Standard Communication Channels

**Primary Coordination**: `#hq` channel  
**Agent-to-Agent**: Direct messages via `sessions_send`  
**Complex Tasks**: `sessions_spawn` for sub-agent delegation  
**CEO Interface**: Secretary handles all CEO coordination

### OP_09 Communication Standards

All agent communications follow OP_09 protocols for clarity and traceability.

**Message Format**:
```
TO: [Agent Name]
FROM: [Agent Name]  
RE: [Project Name] - [Phase] - [Specific Topic]
PRIORITY: [High/Medium/Low]

CONTEXT:
[Brief context of the communication]

REQUEST/INFORMATION:
[Specific request or information being communicated]

DELIVERABLES:
[Expected deliverables and timeline]

HANDOFF ARTIFACTS:
[Specific files, data, or documentation being transferred]
```

### Handoff Protocols

**Every Phase Transition**:
1. **Handoff Meeting** — Direct agent-to-agent discussion
2. **Artifact Transfer** — All relevant files and documentation  
3. **Context Summary** — Key points, issues, decisions made
4. **Success Criteria** — Clear definition of phase completion
5. **Next Phase Kickoff** — Introduction and orientation for receiving agent

---

## Decision Logging

### Project Decision Log
Every project maintains a decision log tracking key decisions, rationale, and implications.

**Decision Entry Format**:
```markdown
## Decision [ID]: [Title] ([Date])
**Phase**: [Project Phase]  
**Decision Maker**: [Agent Name]  
**Participants**: [Other agents involved]

### Context
[Situation requiring decision]

### Options Considered  
[Alternative approaches evaluated]

### Decision
[What was decided]

### Rationale
[Why this decision was made]

### Implications
[Impact on project timeline, scope, approach]

### Approval
[Who approved this decision]
```

### Decision Categories
- **Technical Approach** — Modeling, analysis methods
- **Scope Changes** — Requirement modifications
- **Resource Allocation** — Timeline, effort adjustments
- **Quality Standards** — Acceptance criteria, review gates
- **Client Interface** — Communication, expectation management

---

## Quality Gates and Reviews

### Phase Review Gates
Each phase includes a quality gate before handoff to the next agent.

**Standard Review Criteria**:
1. **Deliverable Completeness** — All required outputs produced
2. **Quality Standards** — Meet technical and documentation standards
3. **Success Criteria** — Phase objectives achieved
4. **Knowledge Capture** — Insights documented in KB
5. **Handoff Readiness** — Clear artifacts and communication for next phase

### CEO Approval Gates
Certain milestones require CEO (Antoine) approval before proceeding:

**Required CEO Approvals**:
- Project scope changes exceeding 20% effort increase
- Technical approach changes affecting timeline or deliverables
- Client communication regarding scope, timeline, or budget
- Final deliverable package before client delivery
- Project closure and lessons learned summary

---

## Agent Coordination Patterns

### Daily Standups (When Active)
**Format**: Brief status in `#hq` channel  
**Frequency**: Daily during active project phases  
**Content**: Yesterday's progress, today's plan, any blockers

### Weekly Coordination
**Format**: Project status meeting  
**Participants**: Active project agents + Manager  
**Agenda**: Progress review, issue resolution, next week planning

### Cross-Project Learning
**Format**: Lessons learned sharing  
**Frequency**: Project completion + monthly review  
**Purpose**: Share insights across projects, improve processes

---

## Escalation Procedures

### Technical Issues
1. **Agent-to-Agent** — Direct problem-solving collaboration
2. **Technical Lead** — Complex technical decisions
3. **Manager** — Resource or timeline impacts
4. **CEO** — Client impact or scope changes

### Process Issues  
1. **Manager** — Workflow or coordination problems
2. **Team Discussion** — Process improvement needs
3. **CEO** — Systematic issues requiring policy changes

### Client Issues
1. **Secretary** — All client communication coordination
2. **Manager** — Scope or expectation management
3. **CEO** — Contract or relationship issues

---

## Continuous Improvement

### Process Refinement
- Document lessons learned in project KB
- Identify workflow bottlenecks and inefficiencies
- Propose process improvements based on experience
- Update workflows based on successful patterns

### Knowledge Sharing
- Cross-pollinate insights between projects
- Share successful techniques and approaches
- Document common problems and solutions
- Build institutional memory through KB accumulation

### Team Development
- Identify skill development opportunities
- Share expertise across agents
- Improve collaboration effectiveness
- Enhance communication protocols

---

Last updated: February 2026