docs: Archive stale docs and create Atomizer-HQ agent documentation
Archive Management: - Moved RALPH_LOOP, CANVAS, and dashboard implementation plans to archive/review/ for CEO review - Moved completed restructuring plan and protocol v1 to archive/historical/ - Moved old session summaries to archive/review/ New HQ Documentation (docs/hq/): - README.md: Overview of Atomizer-HQ multi-agent optimization team - PROJECT_STRUCTURE.md: Standard KB-integrated project layout with Hydrotech reference - KB_CONVENTIONS.md: Knowledge Base accumulation principles with generation tracking - AGENT_WORKFLOWS.md: Project lifecycle phases and agent handoffs (OP_09 integration) - STUDY_CONVENTIONS.md: Technical study execution standards and atomizer_spec.json format Index Update: - Reorganized docs/00_INDEX.md with HQ docs prominent - Updated structure to reflect new agent-focused organization - Maintained core documentation access for engineers No files deleted, only moved to appropriate archive locations.
This commit is contained in:
450
docs/hq/AGENT_WORKFLOWS.md
Normal file
450
docs/hq/AGENT_WORKFLOWS.md
Normal file
@@ -0,0 +1,450 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user