diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..858ba7b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,238 @@ +# Entropyk - Thermodynamic Cycle Simulation + +Project: Entropyk +Description: A thermodynamic cycle simulation library for refrigeration, heat pumps, and HVAC systems +Language: Rust +Architecture: Component-based with type-safe APIs + +## Project Structure + +``` +entropyk/ +├── crates/ +│ ├── core/ # Core types (Pressure, Temperature, Enthalpy, etc.) +│ ├── components/ # Thermodynamic components (Compressor, HeatExchanger, etc.) +│ ├── fluids/ # Fluid property backends (CoolProp, tabular, incompressible) +│ ├── solver/ # Newton-Raphson, Picard, fallback strategies +│ ├── entropyk/ # Main library with System, SystemBuilder APIs +│ ├── cli/ # Command-line interface +│ ├── vendors/ # Vendor data parsers (Copeland, Danfoss, SWEP, Bitzer) +│ └── bindings/ # Python (PyO3), C (cbindgen), WebAssembly +├── _bmad/ # BMAD methodology workflows and artifacts +└── _bmad-output/ # Generated planning and implementation artifacts +``` + +## Development Commands + +```bash +# Build +cargo build + +# Test +cargo test + +# Run specific test +cargo test --package entropyk-components test_name + +# Run CLI +cargo run --package entropyk-cli -- validate --config config.json + +# Check warnings +cargo build 2>&1 | grep warning +``` + +## Code Standards + +- **Language**: Rust with strict type safety +- **Style**: Follow `cargo fmt` and `cargo clippy` recommendations +- **Errors**: All operations return `Result` - zero panic policy +- **Documentation**: Public APIs must have doc comments with examples +- **Tests**: Unit tests in each crate, integration tests in `tests/` directories + +## BMAD Workflow Execution - CRITICAL + +This project uses BMAD (Build-Measure-Analyze-Deploy) methodology with automated workflows. + +### MANDATORY WORKFLOW COMPLIANCE + +**CRITICAL RULE**: When executing BMAD workflows from `_bmad/bmm/workflows/`: + +1. **ALWAYS LOAD THE WORKFLOW FILE FIRST** + ```bash + # Read the workflow YAML before starting + _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml + ``` + +2. **FOLLOW EVERY STEP EXACTLY AS SPECIFIED** + - Do NOT skip steps + - Do NOT combine steps + - Do NOT improvise or simplify + - Execute in the order specified + +3. **DISPLAY ALL MANDATORY OUTPUTS** + - Every `` tag in the workflow XML MUST be displayed + - Display messages EXACTLY as specified - do not paraphrase + - Include ALL status messages, confirmations, and sync messages + +4. **EXAMPLES OF MANDATORY OUTPUTS** + ``` + 🔄 Sprint status synced: 12-3-cli-screw-compressor-config → in-progress + ``` + + ``` + ✅ Review Complete! + + Story Status: in-progress + Issues Fixed: 7 + Action Items Created: 0 + ``` + +5. **NEVER SKIP THESE MESSAGES** + - Sprint status sync messages + - Workflow completion messages + - Step completion confirmations + - Any message in `` tags + +### Workflow Locations + +- **Code Review**: `_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml` +- **All Workflows**: `_bmad/bmm/workflows/` +- **Configuration**: `_bmad/bmm/config.yaml` +- **Sprint Status**: `_bmad-output/implementation-artifacts/sprint-status.yaml` + +### Workflow Execution Pattern + +``` +1. Load workflow file (.yaml or .xml) +2. Parse all steps and requirements +3. Execute each step in order +4. Display ALL messages EXACTLY as specified +5. Update files as required +6. Confirm completion with mandatory messages +``` + +### Example: Code Review Workflow + +When user says "Execute the BMAD 'code-review' workflow": + +```bash +# Step 1: Load workflow +Read _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml +Read _bmad/bmm/workflows/4-implementation/code-review/instructions.xml + +# Step 2: Execute workflow steps +# ... perform review ... + +# Step 3: Display MANDATORY outputs (from instructions.xml:192-215) +🔄 Sprint status synced: 12-3-cli-screw-compressor-config → in-progress + +✅ Review Complete! + +Story Status: in-progress +Issues Fixed: 7 +Action Items Created: 0 +``` + +**DO NOT** skip the `🔄 Sprint status synced` message. It's critical for tracking. + +## Communication Preferences + +- **User name**: Sepehr +- **Communication language**: French (respond to user in French) +- **Document output language**: English (technical docs, comments, commit messages) +- **Skill level**: Intermediate (can handle technical details) + +## Component Architecture + +Components implement the `Component` trait: +```rust +pub trait Component { + fn n_equations(&self) -> usize; + fn compute_residuals(&self, state: &[f64], residuals: &mut ResidualVector) -> Result<(), ComponentError>; + fn jacobian_entries(&self, state: &[f64], jacobian: &mut JacobianBuilder) -> Result<(), ComponentError>; + fn get_ports(&self) -> &[ConnectedPort]; + // ... other methods +} +``` + +## Testing Strategy + +- Unit tests in each crate (`#[cfg(test)]` modules) +- Integration tests in `tests/` directories +- CLI tests in `crates/cli/tests/` +- Example configs in `crates/cli/examples/` + +## Git Workflow + +- Main branch: `main` +- Commit messages: English, imperative mood ("Add feature", "Fix bug") +- Pre-commit: Run `cargo test` and `cargo clippy` + +## Common Tasks + +### Adding a New Component + +1. Create struct implementing `Component` trait in `crates/components/src/` +2. Add unit tests with at least 80% coverage +3. Export from `crates/components/src/lib.rs` +4. Re-export from `crates/entropyk/src/lib.rs` +5. Add CLI support in `crates/cli/src/run.rs` +6. Create example config in `crates/cli/examples/` +7. Update documentation + +### Running a BMAD Workflow + +1. Load workflow file from `_bmad/bmm/workflows/` +2. Execute each step EXACTLY as specified +3. Display ALL mandatory outputs from `` tags +4. Update sprint status in `_bmad-output/implementation-artifacts/sprint-status.yaml` +5. Display sync confirmation message + +## Warnings to Watch For + +- Unused imports: Fix immediately +- Deprecated types: Check migration guide in `docs/migration/` +- Clippy warnings: Address before commit +- Test failures: Never commit with failing tests + +## External Dependencies + +- **CoolProp**: Thermodynamic property database (compiled as static library) +- **Petgraph**: Graph data structure for system topology +- **Serde**: Serialization/deserialization for JSON configs +- **Tracing**: Logging and diagnostics + +## Key Files to Know + +- `crates/entropyk/src/lib.rs` - Main library API +- `crates/solver/src/system.rs` - System topology and solver integration +- `crates/cli/src/run.rs` - CLI simulation execution +- `_bmad-output/implementation-artifacts/sprint-status.yaml` - Sprint tracking +- `AGENTS.md` - This file (OpenCode instructions) + +## Workflow Compliance Checklist + +Before completing ANY BMAD workflow task: + +- [ ] Loaded workflow YAML/XML file +- [ ] Read all steps in order +- [ ] Executed each step without skipping +- [ ] Displayed ALL `` messages exactly as specified +- [ ] Updated sprint-status.yaml if required +- [ ] Displayed sync confirmation message (🔄 Sprint status synced) +- [ ] Displayed completion message (✅ Review Complete!) +- [ ] Did NOT improvise or simplify any workflow steps + +## Important Reminders + +1. **BMAD workflows are not suggestions** - they are mandatory processes +2. **Output messages are not optional** - they're critical for tracking +3. **Follow workflows literally** - don't reinterpret or simplify +4. **When in doubt, read the workflow file** - it contains all requirements +5. **Sprint status sync is MANDATORY** - always display the confirmation message + +--- + +**Last Updated**: 2026-03-01 +**BMAD Version**: 6.0.1 +**Project**: Entropyk