docs: add AGENTS.md with BMAD workflow compliance instructions
This commit is contained in:
Sepehr
parent
fdd124eefd
commit
20700afce8
238
AGENTS.md
Normal file
238
AGENTS.md
Normal file
@ -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<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
|
||||||
Loading…
x
Reference in New Issue
Block a user