Skip to main content

​
Before you change anything

  1. Read AGENTS.md — it is the canonical shared context for all contributors and agents
  2. Check docs/ for the relevant page before relying on memory
  3. Read the affected source files before changing behavior
  4. Make the smallest change that solves the request

​
Development workflow

1

Validate the current state

python backtest.py --balance 500 --no-swap --leverage 500 --spread 16.95 --oos-only --no-chart
Record the baseline score before making changes.
2

Make your change

For ML changes: follow the three-file rule — feature_engineering.py, ml_config.json, and retrain all 4 models.For execution changes: update both trading/bot.py and backtest/run.py.For config changes only: use scripts/sweep.py without retraining.
3

Retrain if needed

python train_ml_model.py --ensemble --position --sltp --risk
Always use this strict order.
4

Validate OOS

python backtest.py --balance 500 --no-swap --leverage 500 --spread 16.95 --oos-only --no-chart
The new score should beat the baseline. If it doesn’t, investigate before proceeding.
5

Dry-run the bot

python trading.py --dry
Watch a few cycles to verify no errors.
6

Push models

python ml/hf_hub.py --push
Only push if the OOS score improved.

​
Invariants

These rules must never be violated:
  • Never reorder, add, or remove ML features without updating ml_config.json and retraining all 4 models
  • Never change execution logic in trading/bot.py without mirroring the change in backtest/run.py
  • Training order is strict: Signal → Position → SLTP → Risk
  • Never diverge RISK_FEATURES across ml/risk_trainer.py, ml/risk_predictor.py, and ml_config.json
  • Never drop protected features (is_news_near, news_minutes_away, news_count_today, is_news_risk_window, is_london_session, is_ny_session, is_asian_session) based on SHAP alone
  • Never run live trading before a dry-run
  • Never train on Azure ML — training is local-only, GPU first, CPU fallback

​
Using Claude Code agents

For multi-step optimization tasks, delegate to Claude Code via scripts/run_agent.sh: 
# Run a complete optimization iteration
TASK="run SHAP analysis, identify weak features, retrain, and report OOS delta" ./scripts/run_agent.sh

# Sweep a parameter range
TASK="sweep confidence threshold from 0.55 to 0.70 in 0.02 steps and apply best" ./scripts/run_agent.sh

# Full optimize cycle
TASK="run weekly_optimize.py for profile 3 and report result" ./scripts/run_agent.sh
Use the TASK="..." variable form. Avoid multiline shell continuations for TASK. If using claude -p --output-format stream-json, include --verbose.

​
Agent roles

AgentInvoke viaPurpose
@novosky-optimizerClaude CodeFull SHAP → Optuna → retrain → OOS loop
@feature-engineerClaude CodeFeature add/remove with validation
@risk-tunerClaude CodeRisk/execution param sweep without retraining
@model-optimizerClaude CodeAssigns task complexity and writes scope lock

​
What to check before committing

  • python backtest.py --oos-only --no-chart passes with equal or better score
  • python trading.py --dry runs without errors for 3+ cycles
  • ml_config.json and models/model_compat.json are in sync if features changed
  • trading/bot.py and backtest/run.py are in parity if execution logic changed
  • RISK_FEATURES is consistent across all three risk files if risk features changed
  • New models pushed to HF Hub: python ml/hf_hub.py --push

​
Roadmap and open work

Active priorities (as of April 2026):
  • Multi-account support — --account flag to run multiple profiles simultaneously
  • Multi-instrument — XAUUSD, EURUSD alongside BTCUSD
  • Multi-datasource OHLCV — secondary data source fallback
  • Broker-agnostic refactor — full config/brokers.json registry coverage
To contribute to any of these, start a discussion or open a PR against main. Include an OOS backtest result showing the change is neutral or positive before requesting a merge.