sepehr/Entropyk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Entropyk/AGENTS.md

7.5 KiB
Raw Blame History

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

# 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<T, E> - 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

    # 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 <output> 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 <output> 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 <output> 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":

# 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:

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 <output> 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 <output> 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