nt8-sdk/.kilocode/rules/project_context.md

Project Context

You are working on the NT8 SDK - an institutional-grade trading SDK for NinjaTrader 8.

Project Purpose

This is production trading software used for automated futures trading (ES, NQ, MES, MNQ, CL, GC). Code quality is critical because:

• Bugs can cause real financial losses
• System runs 24/5 during market hours
• Performance requirements are strict (<200ms latency)
• This is institutional-grade, not hobbyist code

Current Phase: Phase 1 - Core Trading Loop

You are implementing the OMS (Order Management System) component.

OMS Responsibilities

• Manage complete order lifecycle (Pending → Working → Filled/Cancelled)
• Thread-safe order tracking
• State machine enforcement
• Integration with NT8 platform
• Position flattening capability

What OMS Does NOT Do (Other Components Handle)

• Risk validation (IRiskManager handles this)
• Position sizing (IPositionSizer handles this)
• Strategy logic (IStrategy handles this)
• Direct NT8 calls (NT8Adapter handles this)

Architecture Overview

Strategy Layer (IStrategy)
        ↓ generates StrategyIntent
Risk Layer (IRiskManager)
        ↓ validates and produces RiskDecision
Sizing Layer (IPositionSizer)
        ↓ calculates contracts and produces SizingResult
OMS Layer (IOrderManager) ← YOU ARE HERE
        ↓ manages order lifecycle
NT8 Adapter Layer (INT8OrderAdapter)
        ↓ bridges to NinjaTrader 8
NinjaTrader 8 Platform

Your Current Task

Implement the Basic OMS with these deliverables:

Phase 1 Deliverables

1. ✅ OrderModels.cs - Order request/status models and enums
2. ✅ IOrderManager.cs - Core interface definition
3. ✅ INT8OrderAdapter.cs - Adapter interface
4. ✅ BasicOrderManager.cs - Implementation with state machine
5. ✅ MockNT8OrderAdapter.cs - Mock for testing
6. ✅ Unit tests - Comprehensive test coverage (>80%)

Out of Scope (Future Phases)

• ❌ Partial fill aggregation (Phase 2)
• ❌ Retry logic (Phase 2)
• ❌ Position reconciliation (Phase 2)
• ❌ Advanced order types (Phase 3)
• ❌ Smart order routing (Phase 3)

Key Design Principles

1. Risk-First Architecture

ALL trading operations flow through IRiskManager before OMS. The pattern is: Strategy → Risk → Sizing → OMS → NT8 NEVER bypass risk checks.

2. State Machine Discipline

Order states follow strict transitions:

Pending → Working → PartiallyFilled → Filled
              ↓           ↓
          Cancelled   Cancelled
              ↓
          Rejected

Invalid transitions MUST be rejected and logged.

3. Thread Safety

This system will run with:

• Multiple NT8 callbacks firing simultaneously
• UI queries happening while orders process
• State changes from external events

ALL shared state MUST be protected with locks.

4. Performance Targets

• Order submission: <5ms (excluding NT8 adapter)
• State transition: <1ms
• Query operations: <1ms
• Overall tick-to-trade: <200ms

5. Determinism

Order processing must be deterministic for:

• Backtesting accuracy
• Replay debugging
• Audit trails

Technology Constraints

Language & Framework

• C# 5.0 syntax ONLY (no C# 6+)
• .NET Framework 4.8 (not .NET Core/5+/6+)
• Target: Windows desktop environment

Libraries

• ✅ Newtonsoft.Json (for serialization)
• ✅ Microsoft.Extensions.Logging (for logging)
• ✅ Microsoft.Extensions.DependencyInjection (for DI)
• ❌ System.Text.Json (not available)
• ❌ Any .NET Core/5+/6+ libraries

Testing

• xUnit for test framework
• FluentAssertions for assertions
• Bogus for test data generation (if needed)
• Mock adapters for isolation

Reference Documents

You have access to these design documents:

• OMS_Design_Specification.md - Complete technical design
• Kilocode_Implementation_Guide.md - Step-by-step tasks
• OMS_Test_Scenarios.md - Comprehensive test cases

When uncertain about design decisions, reference these documents.

Success Criteria

Your implementation is complete when:

• All 6 deliverables created
• verify-build.bat passes
• >80% test coverage
• All tests passing
• No C# 6+ syntax
• State machine validated
• Thread safety verified
• Performance targets met
• Integration points tested
• Documentation complete

Communication

When you need clarification:

1. Check OMS_Design_Specification.md first
2. Check existing code patterns in src/NT8.Core/Risk/ or src/NT8.Core/Sizing/
3. If still uncertain, ask before implementing

Remember: This is production trading code. When in doubt, ask rather than guess.