MAEA/AGENTS.md

# MAEA Development Guidelines

## Build and Test Commands

### Compilation
- Use MetaEditor (MT5 built-in editor) to compile the EA
- Press F7 or click Compile button in MetaEditor
- Check "Errors" tab in Toolbox for compilation issues
- All MQL5 files must compile with 0 errors before testing

### Testing
- Use MT5 Strategy Tester (Ctrl+T or View → Strategy Tester)
- Select "MAEA" from Expert Advisor dropdown
- Set testing parameters:
  - Symbol: Desired currency pair
  - Model: "Every tick" for accurate testing
  - Period: H1 (recommended timeframe)
  - Spread: Use current or specify fixed value
- Run single test: Click Start button in Strategy Tester
- Run optimization: Enable Genetic Algorithm or slow complete algorithm
- Optimization criteria: Balance, Profit Factor, Drawdown, or Sharpe Ratio

### Key Testing Scenarios
- Test EMA calculations accuracy by comparing with manual calculations
- Test breakthrough signals on historical data
- Test pullback detection on ranging markets
- Test all filters individually (enable one at a time)
- Test risk management (TP, SL, breakeven, trailing stop)
- Test max drawdown protection with aggressive parameters

## Code Style Guidelines

### File Naming and Organization
- EA file: `MAEA.mq5` (root directory)
- Use #include for external functions if needed
- Keep single file structure preferred for portability

### Naming Conventions
- **Input parameters**: PascalCase (e.g., `EMAPeriod`, `LotSizeNormal`, `TakeProfitUSD`)
- **Global variables**: g_PascalCase (e.g., `g_EMAHighBuffer`, `g_PullbackBuyDetected`)
- **Local variables**: camelCase (e.g., `currentClose`, `signalDetected`)
- **Functions**: PascalCase (e.g., `CalculateEMA()`, `CheckFilters()`, `OpenOrder()`)
- **Constants**: UPPER_CASE with underscore prefix (e.g., `_MAX_ORDERS`, `_DEFAULT_TP`)

### Imports and Includes
- MQL5 standard headers:
  ```mql5
  #include <Trade\Trade.mqh>
  #include <Indicators\Indicators.mqh>
  #include <Arrays\ArrayDouble.mqh>
  ```
  (Required for MT5 position management and indicator handling)
- Use MT5 standard functions and objects:
  - CTrade class for position operations
  - Indicator handles via iMA()
  - Position operations: PositionSelect(), PositionGetSymbol()
- Use <Trade\Trade.mqh> as it's essential for MT5 trading operations

### Code Formatting
- Indentation: 4 spaces (no tabs)
- Braces: K&R style (opening brace on same line)
- Line length: Max 120 characters
- Blank line between functions
- Comment section headers like `// === INDICATOR CALCULATIONS ===`

### Variable Types
- Use explicit types, not auto
- Integer counts: `int`
- Prices and averages: `double`
- Boolean flags: `bool`
- Time values: `datetime`
- Array buffers: `double[]`
- String values: `string`

### Error Handling
- Always check return values for:
  - CTrade.OrderOpen() - check return value
  - CTrade.PositionModify() - check return value
  - CTrade.PositionClose() - check return value
  - Indicator handle creation - check if handle != INVALID_HANDLE
  - ObjectCreate() - check return value
- Use GetLastError() after failed operations
- Log errors using Print() or Alert() for critical issues
- Example:
  ```mql5
  CTrade trade;
  trade.SetExpertMagicNumber(MagicNumber);
  if(!trade.Buy(lotSize, Symbol(), price, sl, tp)) {
    int err = GetLastError();
    Print("OrderOpen failed. Error: ", err, " - ", ErrorDescription(err));
    return;
  }
  ```

### Input Parameters Structure
- Group related parameters together
- Use clear, descriptive comments
- Example format:
  ```mql5
  // === EMA SETTINGS ===
  input int      EMAPeriod = 30;           // EMA period for all indicator lines

  // === RISK MANAGEMENT ===
  input double   TakeProfitUSD = 5.0;      // Take profit target in USD
  input int      BreakevenPoints = 100;    // Points to trigger breakeven

  // === FILTERS ===
  input bool     UseMTFFilter = true;      // Enable MTF filter
  input int      MaxSpread = 30;           // Maximum spread in points
  ```

### Function Design
- Keep functions focused and under 40 lines if possible
- Use descriptive parameter names
- Return meaningful values (bool for success/failure when applicable)
- Document complex logic with inline comments
- Separate calculation logic from trading logic

### Timezone Handling
- All time-based logic uses Thailand timezone (UTC+7)
- Use TimeGMT() + 25200 seconds for Thailand time
- Convert server time to Thailand time for news filter checks
- Document timezone conversions explicitly in code

### Testing Best Practices
- Use MT5 Strategy Tester with "Every tick" model
- Test on multiple currency pairs (EURUSD, GBPUSD, XAUUSD)
- Test on different timeframes (M15, H1, H4)
- Verify indicators by visual inspection in tester
- Check both profitable and losing scenarios
- Validate filter logic by comparing tester results with expected behavior
- Paper trade on demo account before live trading

### Safety Constraints
- Never change code to bypass risk management
- Test all parameter changes in Strategy Tester first
- Ensure only one position can be open at a time (MT5 uses positions, not orders)
- Drawdown protection must be always active
- Stop Loss must always be set when opening positions
- Verify position count using PositionsTotal() and filter by MagicNumber

### Code Comments
- Comment complex calculations (especially EMA and Border Line formulas)
- Document edge cases and special conditions
- Include formula explanations: `// Border Line = EMA High + (EMA Medium - EMA Low)`
- No excessive comments for obvious code

### Trading Logic Organization
- Typical entry points: OnTick() (per tick) or OnNewBar() (on new candle)
- Structure: Indicators → Filters → Signals → Orders → Risk Management
- Use state variables to track:
  - Pullback detection (buy and sell separately)
  - Current drawdown
  - Last bar time for new bar detection
  - Order tracking for management

### Git Practices
- Commit after implementing each phase from the implementation plan
- Commit message format: "Phase X: Title - Brief description"
- Verify compilation before committing
- Test major features before committing
- Pull latest changes before starting new work