Entropyk/AGENTS.md

# 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<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**
   ```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 `<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":

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

## Component Integration Process - CRITICAL RULE

When adding a new thermodynamic component, it **MUST** be fully integrated across all supported target interfaces natively. Follow this protocol:

### 1. Core Rust & Solver Representation (`crates/components`)
- **Implement Trait**: Implement `entropyk::Component` (`compute_residuals`, `jacobian_entries`, `n_equations`, `get_ports`, `signature`, `energy_transfers`).
- **Jacobian Accuracy**: The Jacobian **MUST** be exact. Do not use numerical differentiation unless explicitly requested. Verify with tests.
- **Type-State APIs**: Use `Disconnected` -> `Connected` typestate pattern for port connections (`new()` returns disconnected, `connect()` returns connected).
- **Facade Export**: Export in `crates/components/src/lib.rs` AND re-export in `crates/entropyk/src/lib.rs`.
- **Solver Constraints API**: If the component has control variables (e.g., fan speed, opening, frequency), ensure these fields can be manipulated and registered via the `embedding` / `Bounded` / `Constraint` API for inverse calibration/Eurovent rating.

### 2. CLI Integration (`crates/cli`)
- **Config Parsing**: Add a new match arm in `crates/cli/src/run.rs` inside `create_component`.
- **Parameter Extraction**: Extract required and optional parameters from JSON. Provide safe default values (e.g. `unwrap_or()`).
- **Port Resolution**: Instantiate the component using `make_connected_port` for boundaries, or the standard `Port::new(...)` -> `.connect()` pattern for N-port components. 

### 3. Python Bindings (`crates/bindings/python` via PyO3)
- **PyClass Wrapper**: Define a `#[pyclass]` structural wrapper mapping Python primitives to Rust's strong types.
- **State & Properties**: Expose getters (`#[getter]`) and setters (`#[setter]`) for variables.
- **Registration**: Register the wrapper in the PyModule definition.

### 4. WebAssembly Integration (`crates/bindings/wasm`)
- **Wasm Wrapper**: Create a `#[wasm_bindgen]` wrapper.
- **Methods**: Expose state mutation methods to JS using `#[wasm_bindgen]`, mapping complex types to strings/f64s.