# 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