trading-assistant

Imported from luifertorres/trading-assistant (AGENTS.md). Install upstream with npx skills add luifertorres/trading-assistant. Copyright stays with the author.

Trading Assistant - Agent Instructions

Project Overview

Automated trading bot for Binance Futures (USDT Perpetual) built with .NET 10 and C# 13. Monitors the market in real-time, detects technical signals, and executes trades with integrated risk management.

Human documentation: docs/README.md.

Repository routing (read when ambiguous)

Default for new work: src/platform/TradingPlatform/ — modular monolith by bounded context; no references to legacy solutions. Start with src/platform/TradingPlatform/AGENTS.md and src/platform/TradingPlatform/README.md.

Legacy reference: src/legacy/TradingAssistant/ — frozen single-project live bot (maintenance only). Avoid growing it when the same capability belongs in TradingPlatform (see ai/context/refactor-ledger.md).

MVP tooling: src/mvp/Backtesting/ — isolated backtest CLI; src/mvp/WebSocketTrading/ — live WS kline + SMA short worker (Binance.Net 13.1.1); src/mvp/Portfolio/ — MAUI USDT line chart (ScottPlot).

Source tree index: src/README.md.

Routing protocol: infer intent and blast radius, not keywords. If the task is cross-cutting, multi-context, or unclear on OpenSpec vs direct implementation, read ai/context/routing-map.md first. For a short preflight only, use the chief-of-staff skill (ai/skills/chief-of-staff/SKILL.md).

Editor setup after clone: EDITOR-AGENTS.md — run ai/commands/ai-onboard.md (required; entire .cursor/ is local-only).

Task routing (read matching skill before coding)

Done checklist

Failing unit test first for behavior changes (strict TDD per ai/skills/tdd/SKILL.md), then green implementation, dotnet build, unit test csproj, integration csproj last when Infrastructure changed.

Modular context (by rate of change)

Architecture

TradingPlatform (greenfield)

Modular monolith with DDD bounded contexts — MarketData, Research, Analytics, Portfolio, Execution, Kernel, Host, Cli. See src/platform/TradingPlatform/AGENTS.md.

Legacy (reference)

Single Worker Service project under src/legacy/TradingAssistant/TradingAssistant/ — strategies, Binance integration, EF Core, and FASTER in one assembly. Not layered; not extended for new features.

MVP

Isolated tooling under src/mvp/:

• Backtesting — offline backtest CLI (Backtesting/README.md)
• WebSocketTrading — live Worker that streams klines and places orders via Binance WS API (WebSocketTrading/README.md); uses Binance.Net 13.1.1 (MVP-only pin)
• Portfolio — Windows MAUI chart MVP (Portfolio/README.md); ScottPlot.Maui; not Platform Portfolio context

Key Conventions (Platform)

• Rich Domain Model: Entities have behavior, not just data (no anemic models).
• Binance.Net as the Binance framework: For .NET code that talks to Binance (REST, WebSocket, USD-M models), use Binance.Net as the supported stack. Platform Domain and Application stay broker-agnostic in public types; Infrastructure adapters own Binance.Net. Legacy monolith and MVP may use Binance.Net directly. See Binance.Net framework below.
• MediatR: Used for in-process messaging in Platform Application and legacy monolith.
• Value Objects: Use record or readonly struct for immutability.
• High-performance types: Use struct for hot-path types like Candle.
• Naming: PascalCase for public members, _camelCase for private fields.
• Async/Await: Use CancellationToken in all async signatures.

Binance.Net framework (.NET)

Treat Binance.Net as the framework for Binance-facing .NET code: IBinanceRestClient / IBinanceSocketClient, USD-M APIs under UsdFuturesApi, and models as returned by the API. Prefer library types over re-modeling exchange payloads unless translating into Platform Domain or Application interfaces.

Where it applies: Platform Infrastructure (MarketData, Execution), legacy monolith (BinanceService), Backtesting MVP, and WebSocketTrading MVP (13.1.1 only in that solution).

Practices: Keep Binance.Net package versions aligned across Platform and legacy (12.11.x). WebSocketTrading MVP pins 13.1.1 independently. Legacy uses BinanceCredentials for API keys (Binance.Net 12.11+).

Cursor rule (after /ai-onboard): ai/templates/rules/binance-net.mdc → .cursor/rules/.

Solution Structure

See src/README.md for build/run commands. Buckets:

src/
├── platform/TradingPlatform/
│   ├── TradingPlatform.slnx         → Greenfield DDD modular monolith
│   └── src/                         → Bounded contexts, Kernel, Host, Cli
│
├── legacy/TradingAssistant/
│   ├── TradingAssistant.sln
│   └── TradingAssistant/            → Single-project live bot (see AGENTS.md)
│
└── mvp/
    ├── Backtesting/
    │   ├── Backtesting.sln
    │   └── …                        → See Backtesting/README.md
    ├── WebSocketTrading/
    │   ├── WebSocketTrading.slnx
    │   └── …                        → See WebSocketTrading/README.md
    └── Portfolio/
        ├── Portfolio.slnx
        └── …                        → See Portfolio/README.md

Technology Stack

Migrations Policy (legacy only)

Never edit migration files manually:

dotnet ef migrations add <Name> --project src/legacy/TradingAssistant/TradingAssistant
dotnet ef database update --project src/legacy/TradingAssistant/TradingAssistant

OpenSpec

This project uses OpenSpec for TradingPlatform spec-driven development. See openspec/README.md.

• Main specs: openspec/specs/trading-platform-*
• Changes: openspec/changes/<change-name>/ with artifacts: proposal, specs, design, tasks

Use /opsx:apply <change-name> to implement a change, or /opsx:new to start a new one. Setup and CLI-less fallback: openspec/SETUP.md.