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.
2026-02-09 02:48:35 +00:00
parent 9541958eae
commit 8d9d55356c
34 changed files with 3651 additions and 69 deletions
--- a/docs/hq/PROJECT_STRUCTURE.md
+++ b/docs/hq/PROJECT_STRUCTURE.md
@@ -0,0 +1,377 @@
+# Standard Project Structure
+
+**Version**: 1.0  
+**Created**: February 2026  
+**Reference Implementation**: `projects/hydrotech-beam/`
+
+---
+
+## Overview
+
+All Atomizer-HQ projects follow a standardized Knowledge Base-integrated structure. This ensures consistent organization, efficient handoffs between agents, and proper accumulation of domain knowledge.
+
+**Key Principles**:
+- **Single Source of Truth** — Each project has one authoritative structure
+- **KB Integration** — Knowledge accumulates in structured format
+- **Study-Project Separation** — Studies are execution units, projects are business units
+- **Reference → Copy Flow** — Models flow from reference to study-specific copies
+
+---
+
+## Full Project Directory Structure
+
+```
+projects/[project-name]/
+│
+├── README.md                          # Project overview, status, contacts
+├── project_metadata.json              # Structured project info
+│
+├── deliverables/                      # Client-facing outputs
+│   ├── reports/                       # Technical reports, presentations
+│   ├── models/                        # Final optimized models
+│   └── data/                          # Results datasets, exports
+│
+├── images/                            # Visual assets (organized by type)
+│   ├── components/                    # Part/assembly images
+│   ├── studies/                       # Study result visualizations
+│   ├── analysis/                      # Analysis plots, graphs
+│   └── deliverables/                  # Client presentation images
+│
+├── kb/                                # Knowledge Base (THE CORE)
+│   ├── README.md                      # KB navigation and conventions
+│   ├── components/                    # Component-specific knowledge
+│   │   ├── [component-name].md        # Per-component accumulation
+│   │   └── manufacturing-constraints.md
+│   ├── materials/                     # Material property knowledge
+│   │   ├── steel-properties.md
+│   │   └── material-selection-criteria.md
+│   ├── fea/                          # FEA-specific knowledge
+│   │   ├── models/                    # Model setup knowledge
+│   │   │   ├── meshing-conventions.md
+│   │   │   ├── boundary-conditions.md
+│   │   │   └── modeling-assumptions.md
+│   │   ├── load-cases/                # Load case documentation
+│   │   │   ├── operational-loads.md
+│   │   │   └── safety-factors.md
+│   │   └── results/                   # Results interpretation
+│   │       ├── stress-criteria.md
+│   │       └── failure-modes.md
+│   ├── dev/                          # Development knowledge
+│   │   ├── lessons-learned.md         # Project-specific lessons
+│   │   ├── optimization-insights.md   # What worked, what didn't
+│   │   └── process-improvements.md    # Workflow refinements
+│   └── client/                       # Client-specific knowledge (optional)
+│       ├── requirements.md            # Client requirements evolution
+│       └── preferences.md             # Client preferences and constraints
+│
+├── models/                           # Reference models (READ-ONLY for studies)
+│   ├── reference/                    # Original/baseline models
+│   │   ├── [component].prt           # CAD models
+│   │   ├── [component].sim           # NX simulation setups
+│   │   └── [component].fem           # FEM files
+│   ├── variations/                   # Design variations
+│   └── optimized/                    # Final optimized models
+│
+└── studies/                          # Links to actual studies directory
+    ├── 01_baseline_validation/       # → ../../../studies/project_01_baseline/
+    ├── 02_stress_optimization/       # → ../../../studies/project_02_stress/
+    └── README.md                     # Study execution log
+```
+
+---
+
+## Directory Responsibilities
+
+### Core Directories
+
+| Directory | Owner | Purpose | Frequency |
+|-----------|-------|---------|-----------|
+| `README.md` | Manager | Project status, contacts | Updated weekly |
+| `project_metadata.json` | Secretary | Structured project data | Updated on changes |
+| `deliverables/` | Reporter | Client-facing outputs | End of phases |
+| `kb/` | **Everyone** | Accumulated knowledge | **Continuous** |
+| `models/reference/` | Technical Lead | Baseline models | Setup phase |
+| `studies/` | Optimizer | Study execution links | Per study |
+
+### KB Subdirectories
+
+| KB Directory | Primary Owner | Content |
+|--------------|---------------|---------|
+| `components/` | Technical Lead | Component behavior, constraints |
+| `materials/` | Technical Lead | Material properties, selection |
+| `fea/models/` | Technical Lead | Modeling conventions, assumptions |
+| `fea/load-cases/` | Technical Lead | Load cases, boundary conditions |
+| `fea/results/` | Post-Processor | Results interpretation, criteria |
+| `dev/` | All Agents | Process lessons, optimization insights |
+
+---
+
+## File Naming Conventions
+
+### General Rules
+- **Lowercase with hyphens**: `component-analysis.md`, not `Component_Analysis.md`
+- **Descriptive names**: `steel-yield-strength.md`, not `steel.md`
+- **No spaces**: Use hyphens, not spaces
+- **Consistent extensions**: `.md` for documentation, `.json` for data
+
+### Specific Conventions
+
+**Components**: `[component-type]-[specific-name].md`
+```
+beam-support-bracket.md
+hydraulic-cylinder-mount.md
+```
+
+**Materials**: `[material-type]-[property].md`
+```
+steel-properties.md
+aluminum-6061-characteristics.md
+```
+
+**Studies**: `[number]_[descriptive-name]`
+```
+01_baseline_validation
+02_stress_minimization
+03_mass_reduction_study
+```
+
+---
+
+## Model Flow Conventions
+
+### Reference → Study Copy Pattern
+
+1. **Reference Models** (`models/reference/`)
+   - Original/baseline models
+   - **READ-ONLY** for studies
+   - Version controlled
+   - Maintained by Technical Lead
+
+2. **Study Copies** (`studies/[study-name]/model/`)
+   - **Copied from reference** at study creation
+   - Modified during optimization
+   - Study-specific versions
+   - Managed by Optimizer
+
+3. **Optimized Models** (`models/optimized/`)
+   - Best results from studies
+   - **Copied from study results**
+   - Final deliverable candidates
+   - Curated by Technical Lead
+
+### Model Versioning
+```
+models/reference/bracket-v1.0.prt          # Initial design
+models/reference/bracket-v1.1.prt          # Design revision
+studies/stress-opt/model/bracket.prt       # Study working copy
+models/optimized/bracket-optimized-v2.0.prt # Final optimized
+```
+
+---
+
+## Project Creation Workflow
+
+### 1. Secretary: Project Intake
+```bash
+# Create project directory
+mkdir -p projects/[project-name]/{deliverables,images,kb,models,studies}
+
+# Create metadata
+# (See project_metadata.json template)
+```
+
+### 2. Manager: Structure Setup
+```bash
+# Copy template structure
+cp -r templates/project-template/* projects/[project-name]/
+
+# Create README from template
+# Update with project specifics
+```
+
+### 3. Technical Lead: KB Initialization
+```bash
+# Create component files
+touch projects/[project-name]/kb/components/[component].md
+
+# Initialize FEA knowledge structure
+mkdir -p projects/[project-name]/kb/fea/{models,load-cases,results}
+
+# Create reference models directory
+mkdir -p projects/[project-name]/models/reference
+```
+
+---
+
+## Study Integration
+
+### Study-Project Relationship
+- **Projects** = Business/client organizing unit
+- **Studies** = Technical execution unit
+- Studies reference project KB and models
+- Results flow back to project KB
+
+### Creating Project Studies
+```bash
+# Create study linked to project
+mkdir studies/project_01_baseline
+ln -s ../../../projects/[project]/studies studies/project_01_baseline/project_link
+
+# Copy reference models to study
+cp projects/[project]/models/reference/* studies/project_01_baseline/model/
+
+# Study inherits project KB context
+```
+
+### Results Flow Back
+1. **Study completes** → Results in `studies/[study]/results/`
+2. **Post-Processor analyzes** → Insights documented
+3. **KB accumulation** → Knowledge flows to `projects/[project]/kb/`
+4. **Model archival** → Best models to `projects/[project]/models/optimized/`
+
+---
+
+## KB Accumulation Principles
+
+### The Golden Rule: Add, Never Replace
+- **DO**: Append new insights, learnings, results
+- **DO NOT**: Overwrite existing knowledge
+- **Timestamp entries**: Generation tracking for all additions
+- **Version knowledge**: Track what was learned when
+
+### Component Knowledge Evolution
+```markdown
+# beam-support-analysis.md
+
+## Generation 1: Initial Analysis (2026-02-01)
+- Material: Steel A36
+- Critical stress location: Root of bracket
+- Baseline performance: 180 MPa max stress
+
+## Generation 2: First Optimization (2026-02-05) 
+- Discovered: Fillet radius critical to stress concentration
+- Optimized radius from 5mm → 8mm reduced stress by 15%
+- New critical location: Mounting bolt interface
+
+## Generation 3: Load Case Refinement (2026-02-08)
+- Added dynamic loading consideration
+- Peak stress now 220 MPa under dynamic conditions
+- Recommendation: Consider fatigue analysis
+```
+
+---
+
+## Templates
+
+### project_metadata.json Template
+```json
+{
+  "project_name": "project-name",
+  "client": "Client Name",
+  "project_manager": "agent-name",
+  "technical_lead": "agent-name",
+  "created": "2026-02-01",
+  "status": "active",
+  "phase": "introspection",
+  "description": "Brief project description",
+  "components": ["component1", "component2"],
+  "objectives": ["minimize stress", "reduce mass"],
+  "constraints": ["manufacturing feasibility"],
+  "studies": [
+    {
+      "name": "01_baseline_validation",
+      "status": "completed",
+      "study_link": "../../../studies/project_01_baseline"
+    }
+  ],
+  "deliverables": {
+    "interim_report": "deliverables/reports/interim-report.pdf",
+    "final_report": "deliverables/reports/final-report.pdf",
+    "optimized_models": "models/optimized/"
+  }
+}
+```
+
+### Project README Template
+```markdown
+# [Project Name]
+
+**Client**: [Client Name]  
+**Status**: [Active/Completed/On Hold]  
+**Phase**: [Intake/Breakdown/Introspection/Study/Results/Deliverables]  
+**Manager**: [Agent Name]  
+**Technical Lead**: [Agent Name]  
+
+## Objective
+[Brief description of what we're optimizing]
+
+## Components
+- [Component 1] — [Brief description]
+- [Component 2] — [Brief description]
+
+## Current Status
+[What's happening now, next steps]
+
+## Studies
+- [Study 1] — [Status] — [Brief outcome]
+- [Study 2] — [Status] — [Brief outcome]
+
+## Key Findings
+[Major insights, recommendations]
+
+## Deliverables
+- [X] Baseline analysis
+- [ ] Optimization study
+- [ ] Final report
+```
+
+---
+
+## Best Practices
+
+### Project Organization
+1. **One project per client deliverable**
+2. **Clear phase progression** (don't skip phases)
+3. **Regular KB updates** (not just at end)
+4. **Study naming consistency** (01_, 02_, etc.)
+
+### Knowledge Base Maintenance
+1. **Write as you work** — Don't accumulate at the end
+2. **Be specific** — "Fillet radius affects stress concentration" not "Design matters"
+3. **Include context** — Why was this learned? What led to this insight?
+4. **Link studies** — Reference which study generated the knowledge
+
+### Model Management
+1. **Protect reference models** — No direct modification
+2. **Study isolation** — Each study gets its own model copies
+3. **Version final models** — Clear naming for optimized versions
+4. **Archive intermediate** — Keep best intermediate results
+
+---
+
+## Living Example: Hydrotech Beam Project
+
+**Reference**: `projects/hydrotech-beam/`
+
+This project demonstrates the full structure in practice:
+- Complete KB with component, material, and FEA knowledge
+- Multiple studies linked and executed
+- Results flowing back to project KB
+- Deliverables organized for client handoff
+
+**Key Learnings from Hydrotech**:
+- KB accumulation prevented re-discovering constraints
+- Study-project linking maintained context
+- Reference model protection avoided corruption
+- Generation tracking showed knowledge evolution
+
+---
+
+## Questions and Updates
+
+- **Structure Questions**: Ask Manager or Technical Lead
+- **KB Conventions**: See `KB_CONVENTIONS.md`
+- **Study Execution**: See `STUDY_CONVENTIONS.md`
+- **Process Issues**: Document in project `kb/dev/lessons-learned.md`
+
+Last updated: February 2026