chore: Add project configuration and documentation
Some checks failed
Build and Test / build (push) Has been cancelled
Some checks failed
Build and Test / build (push) Has been cancelled
- Kilocode AI agent rules and guidelines - Setup and implementation guides - Architecture documentation - Build and verification references
This commit is contained in:
272
.kilocode/rules/coding_patterns.md
Normal file
272
.kilocode/rules/coding_patterns.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Mandatory Coding Patterns
|
||||
|
||||
These patterns MUST be followed in all code you write for the NT8 SDK.
|
||||
|
||||
## Thread Safety - Dictionary Access
|
||||
|
||||
ALL access to shared dictionaries MUST use locks.
|
||||
|
||||
### ❌ WRONG - No Lock
|
||||
```csharp
|
||||
_activeOrders[orderId] = orderStatus; // DANGEROUS!
|
||||
```
|
||||
|
||||
### ✅ CORRECT - With Lock
|
||||
```csharp
|
||||
lock (_lock)
|
||||
{
|
||||
_activeOrders[orderId] = orderStatus;
|
||||
}
|
||||
```
|
||||
|
||||
### Rule
|
||||
Every class with shared state MUST have:
|
||||
```csharp
|
||||
private readonly object _lock = new object();
|
||||
```
|
||||
|
||||
Every access to shared collections MUST be inside:
|
||||
```csharp
|
||||
lock (_lock)
|
||||
{
|
||||
// Dictionary/List operations here
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling - Try-Catch Required
|
||||
|
||||
ALL public methods MUST have try-catch blocks.
|
||||
|
||||
### ❌ WRONG - No Error Handling
|
||||
```csharp
|
||||
public async Task<string> SubmitOrder(OrderRequest request)
|
||||
{
|
||||
var orderId = GenerateOrderId();
|
||||
await _nt8Adapter.SubmitToNT8(orderStatus);
|
||||
return orderId;
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ CORRECT - With Error Handling
|
||||
```csharp
|
||||
public async Task<string> SubmitOrder(OrderRequest request)
|
||||
{
|
||||
if (request == null)
|
||||
throw new ArgumentNullException("request");
|
||||
|
||||
try
|
||||
{
|
||||
request.Validate();
|
||||
}
|
||||
catch (ArgumentException ex)
|
||||
{
|
||||
_logger.LogError("Order validation failed: {0}", ex.Message);
|
||||
throw;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
var orderId = GenerateOrderId();
|
||||
await _nt8Adapter.SubmitToNT8(orderStatus);
|
||||
return orderId;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogError("Order submission failed: {0}", ex.Message);
|
||||
throw;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern Template
|
||||
```csharp
|
||||
public ReturnType MethodName(Type parameter)
|
||||
{
|
||||
// 1. Validate parameters (throw ArgumentNullException/ArgumentException)
|
||||
if (parameter == null)
|
||||
throw new ArgumentNullException("parameter");
|
||||
|
||||
// 2. Try-catch for operation-specific errors
|
||||
try
|
||||
{
|
||||
// Main logic
|
||||
}
|
||||
catch (SpecificException ex)
|
||||
{
|
||||
_logger.LogError("Specific error: {0}", ex.Message);
|
||||
// Handle or re-throw
|
||||
throw;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogError("Unexpected error: {0}", ex.Message);
|
||||
throw;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Logging - Structured and Consistent
|
||||
|
||||
Use structured logging with string.Format (NOT string interpolation).
|
||||
|
||||
### Log Levels
|
||||
|
||||
#### LogTrace - Detailed Flow
|
||||
```csharp
|
||||
_logger.LogTrace("Entering method {0} with parameter {1}", methodName, param);
|
||||
```
|
||||
|
||||
#### LogDebug - Normal Operations
|
||||
```csharp
|
||||
_logger.LogDebug("Order {0} state is {1}", orderId, state);
|
||||
```
|
||||
|
||||
#### LogInformation - Important Events
|
||||
```csharp
|
||||
_logger.LogInformation("Order {0} submitted successfully at {1}", orderId, timestamp);
|
||||
_logger.LogInformation("Order {0} filled: {1} contracts @ {2:F2}", orderId, qty, price);
|
||||
```
|
||||
|
||||
#### LogWarning - Recoverable Issues
|
||||
```csharp
|
||||
_logger.LogWarning("Order validation failed: {0}", validationError);
|
||||
_logger.LogWarning("Maximum active orders reached: {0}", maxOrders);
|
||||
```
|
||||
|
||||
#### LogError - Failures
|
||||
```csharp
|
||||
_logger.LogError("Failed to submit order {0} to NT8: {1}", orderId, ex.Message);
|
||||
_logger.LogError("Invalid state transition: {0} -> {1}", fromState, toState);
|
||||
```
|
||||
|
||||
#### LogCritical - System Integrity Issues
|
||||
```csharp
|
||||
_logger.LogCritical("Emergency flatten failed for {0}: {1}", symbol, ex.Message);
|
||||
```
|
||||
|
||||
### ❌ WRONG - String Interpolation
|
||||
```csharp
|
||||
_logger.LogInformation($"Order {orderId} submitted"); // C# 6+ feature!
|
||||
```
|
||||
|
||||
### ✅ CORRECT - string.Format
|
||||
```csharp
|
||||
_logger.LogInformation("Order {0} submitted", orderId);
|
||||
```
|
||||
|
||||
## XML Documentation - Required
|
||||
|
||||
ALL public and protected members MUST have XML documentation.
|
||||
|
||||
### ❌ WRONG - No Documentation
|
||||
```csharp
|
||||
public interface IOrderManager
|
||||
{
|
||||
Task<string> SubmitOrder(OrderRequest request);
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ CORRECT - With Documentation
|
||||
```csharp
|
||||
/// <summary>
|
||||
/// Order management interface - manages complete order lifecycle
|
||||
/// </summary>
|
||||
public interface IOrderManager
|
||||
{
|
||||
/// <summary>
|
||||
/// Submit new order for execution
|
||||
/// </summary>
|
||||
/// <param name="request">Order request with all parameters</param>
|
||||
/// <returns>Unique order ID for tracking</returns>
|
||||
/// <exception cref="ArgumentNullException">Request is null</exception>
|
||||
/// <exception cref="ArgumentException">Request validation fails</exception>
|
||||
Task<string> SubmitOrder(OrderRequest request);
|
||||
}
|
||||
```
|
||||
|
||||
### Template
|
||||
```csharp
|
||||
/// <summary>
|
||||
/// Brief description of what this does (one line)
|
||||
/// </summary>
|
||||
/// <param name="paramName">What this parameter represents</param>
|
||||
/// <returns>What this method returns</returns>
|
||||
/// <exception cref="ExceptionType">When this exception is thrown</exception>
|
||||
public ReturnType MethodName(Type paramName)
|
||||
{
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Constructor Pattern
|
||||
|
||||
### ❌ WRONG - No Validation
|
||||
```csharp
|
||||
public BasicOrderManager(ILogger logger, INT8OrderAdapter adapter)
|
||||
{
|
||||
_logger = logger;
|
||||
_adapter = adapter;
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ CORRECT - Validate Dependencies
|
||||
```csharp
|
||||
public BasicOrderManager(ILogger<BasicOrderManager> logger, INT8OrderAdapter adapter)
|
||||
{
|
||||
if (logger == null)
|
||||
throw new ArgumentNullException("logger");
|
||||
if (adapter == null)
|
||||
throw new ArgumentNullException("adapter");
|
||||
|
||||
_logger = logger;
|
||||
_adapter = adapter;
|
||||
|
||||
_activeOrders = new Dictionary<string, OrderStatus>();
|
||||
_completedOrders = new Dictionary<string, OrderStatus>();
|
||||
|
||||
// Register callbacks
|
||||
_adapter.RegisterOrderCallback(OnNT8OrderUpdate);
|
||||
|
||||
_logger.LogInformation("BasicOrderManager initialized");
|
||||
}
|
||||
```
|
||||
|
||||
## Event Raising Pattern
|
||||
|
||||
NEVER raise events inside locks (prevents deadlocks).
|
||||
|
||||
### ❌ WRONG - Event Inside Lock
|
||||
```csharp
|
||||
lock (_lock)
|
||||
{
|
||||
order.State = newState;
|
||||
OrderStateChanged?.Invoke(this, eventArgs); // DEADLOCK RISK!
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ CORRECT - Event Outside Lock
|
||||
```csharp
|
||||
OrderState previousState;
|
||||
OrderState newState;
|
||||
|
||||
lock (_lock)
|
||||
{
|
||||
previousState = order.State;
|
||||
order.State = newState;
|
||||
// Update state inside lock
|
||||
}
|
||||
|
||||
// Raise event OUTSIDE lock
|
||||
RaiseOrderStateChanged(orderId, previousState, newState, reason);
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before completing ANY method, verify:
|
||||
- [ ] Parameter validation (ArgumentNullException/ArgumentException)
|
||||
- [ ] Try-catch on operation
|
||||
- [ ] Logging at appropriate level
|
||||
- [ ] Lock around shared state access
|
||||
- [ ] Events raised outside locks
|
||||
- [ ] XML documentation on public members
|
||||
- [ ] C# 5.0 syntax only (no $, ?., =>, etc.)
|
||||
88
.kilocode/rules/csharp_50_syntax.md
Normal file
88
.kilocode/rules/csharp_50_syntax.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# C# 5.0 Syntax Requirements
|
||||
|
||||
You are working on a .NET Framework 4.8 project that MUST use C# 5.0 syntax only.
|
||||
|
||||
## Forbidden C# 6+ Features
|
||||
|
||||
### String Interpolation (C# 6)
|
||||
❌ NEVER use: `$"Order {orderId} at {price}"`
|
||||
✅ ALWAYS use: `string.Format("Order {0} at {1}", orderId, price)`
|
||||
|
||||
### Null-Conditional Operators (C# 6)
|
||||
❌ NEVER use: `var name = order?.Name`
|
||||
❌ NEVER use: `var value = dict?[key]`
|
||||
✅ ALWAYS use explicit null checks:
|
||||
```csharp
|
||||
var name = order != null ? order.Name : null;
|
||||
if (dict != null && dict.ContainsKey(key)) { }
|
||||
```
|
||||
|
||||
### Null-Coalescing Assignment (C# 8)
|
||||
❌ NEVER use: `value ??= defaultValue;`
|
||||
✅ ALWAYS use: `if (value == null) value = defaultValue;`
|
||||
|
||||
### Expression-Bodied Members (C# 6)
|
||||
❌ NEVER use: `public int Property => value;`
|
||||
❌ NEVER use: `public void Method() => DoSomething();`
|
||||
✅ ALWAYS use full syntax:
|
||||
```csharp
|
||||
public int Property
|
||||
{
|
||||
get { return value; }
|
||||
}
|
||||
|
||||
public void Method()
|
||||
{
|
||||
DoSomething();
|
||||
}
|
||||
```
|
||||
|
||||
### nameof Operator (C# 6)
|
||||
❌ NEVER use: `throw new ArgumentNullException(nameof(param));`
|
||||
✅ ALWAYS use: `throw new ArgumentNullException("param");`
|
||||
|
||||
### Auto-Property Initializers (C# 6)
|
||||
❌ NEVER use: `public int Property { get; set; } = 10;`
|
||||
✅ ALWAYS use constructor initialization:
|
||||
```csharp
|
||||
public int Property { get; set; }
|
||||
|
||||
public ClassName()
|
||||
{
|
||||
Property = 10;
|
||||
}
|
||||
```
|
||||
|
||||
### Using Static (C# 6)
|
||||
❌ NEVER use: `using static System.Math;`
|
||||
✅ ALWAYS use: `System.Math.Floor(...)`
|
||||
|
||||
### Tuple Syntax (C# 7)
|
||||
❌ NEVER use: `var tuple = (name: "test", value: 1);`
|
||||
✅ ALWAYS use: `Tuple<string, int>` or custom classes
|
||||
|
||||
### Pattern Matching (C# 7+)
|
||||
❌ NEVER use: `if (obj is string str)`
|
||||
✅ ALWAYS use: `if (obj is string) { var str = (string)obj; }`
|
||||
|
||||
### Local Functions (C# 7)
|
||||
❌ NEVER use functions inside methods
|
||||
✅ ALWAYS use private methods
|
||||
|
||||
### Out Variables (C# 7)
|
||||
❌ NEVER use: `if (dict.TryGetValue(key, out var value))`
|
||||
✅ ALWAYS use:
|
||||
```csharp
|
||||
OrderStatus value;
|
||||
if (dict.TryGetValue(key, out value))
|
||||
{
|
||||
// Use value
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
After writing ANY code, verify C# 5.0 compliance:
|
||||
- No `$` signs except in string literals
|
||||
- No `?.` or `?[` operators
|
||||
- No `=>` except in lambda expressions
|
||||
- No inline variable declarations in out parameters
|
||||
63
.kilocode/rules/file_boundaries.md
Normal file
63
.kilocode/rules/file_boundaries.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# File Modification Boundaries
|
||||
|
||||
You are implementing the OMS (Order Management System) for the NT8 SDK project.
|
||||
|
||||
## Allowed Modifications
|
||||
|
||||
You MAY create and modify files in these directories ONLY:
|
||||
|
||||
### Core OMS Implementation
|
||||
- `src/NT8.Core/OMS/*.cs` - All OMS implementation files
|
||||
- `src/NT8.Core/OMS/**/*.cs` - Any subdirectories under OMS
|
||||
|
||||
### Testing
|
||||
- `tests/NT8.Core.Tests/OMS/*.cs` - OMS unit tests
|
||||
- `tests/NT8.Core.Tests/OMS/**/*.cs` - OMS test subdirectories
|
||||
- `tests/NT8.Core.Tests/Mocks/*.cs` - Mock implementations (MockNT8OrderAdapter)
|
||||
|
||||
## Strictly Forbidden Modifications
|
||||
|
||||
You MUST NOT modify any existing files in these locations:
|
||||
|
||||
### Core Interfaces and Models
|
||||
- `src/NT8.Core/Common/**` - Existing interfaces and base models
|
||||
- `src/NT8.Core/Risk/**` - Risk management system (completed)
|
||||
- `src/NT8.Core/Sizing/**` - Position sizing system (completed)
|
||||
- `src/NT8.Core/Logging/**` - Logging infrastructure
|
||||
|
||||
### Build Configuration
|
||||
- `Directory.Build.props` - Global build properties
|
||||
- `*.csproj` files - Project files (unless adding new files to OMS project)
|
||||
- `.gitignore`
|
||||
|
||||
### Documentation (Read-Only)
|
||||
- `nt8_phasing_plan.md`
|
||||
- `nt8_dev_spec.md`
|
||||
- `NT8_Integration_Guidelines_for_AI_Agents.md`
|
||||
- `AI_Agent_Workflow_and_Code_Templates.md`
|
||||
|
||||
### NT8 Adapters
|
||||
- `src/NT8.Adapters/**` - NT8 integration (future phase)
|
||||
|
||||
## New File Creation Rules
|
||||
|
||||
### When creating new files:
|
||||
1. Use proper namespace: `NT8.Core.OMS` for implementation, `NT8.Core.Tests.OMS` for tests
|
||||
2. Include XML documentation on all public members
|
||||
3. Follow existing file naming patterns (PascalCase, descriptive names)
|
||||
4. Add to appropriate project file if needed
|
||||
|
||||
### File naming examples:
|
||||
✅ `BasicOrderManager.cs` - Implementation class
|
||||
✅ `OrderModels.cs` - Model classes
|
||||
✅ `IOrderManager.cs` - Interface
|
||||
✅ `BasicOrderManagerTests.cs` - Test class
|
||||
✅ `MockNT8OrderAdapter.cs` - Mock for testing
|
||||
|
||||
## Verification
|
||||
Before any file operation, ask yourself:
|
||||
1. Is this file in an allowed directory?
|
||||
2. Am I modifying an existing Core interface? (FORBIDDEN)
|
||||
3. Am I creating a new file in the correct location?
|
||||
|
||||
If unsure, DO NOT proceed - ask for clarification first.
|
||||
153
.kilocode/rules/project_context.md
Normal file
153
.kilocode/rules/project_context.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# 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.
|
||||
164
.kilocode/rules/verification_requirements.md
Normal file
164
.kilocode/rules/verification_requirements.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Verification Requirements
|
||||
|
||||
You MUST verify your work at each checkpoint to ensure code quality and prevent errors.
|
||||
|
||||
## After EVERY File Creation or Modification
|
||||
|
||||
### Step 1: Run Build Verification
|
||||
```bash
|
||||
.\verify-build.bat
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✅ All checks passed!
|
||||
```
|
||||
|
||||
**If build fails:**
|
||||
1. Read the error message carefully
|
||||
2. Fix the error immediately
|
||||
3. Re-run verify-build.bat
|
||||
4. DO NOT proceed to next file until build passes
|
||||
|
||||
### Step 2: Verify File Location
|
||||
Check that the file is in an allowed directory:
|
||||
- ✅ `src/NT8.Core/OMS/` - Implementation files
|
||||
- ✅ `tests/NT8.Core.Tests/OMS/` - Test files
|
||||
- ✅ `tests/NT8.Core.Tests/Mocks/` - Mock files
|
||||
- ❌ Anywhere else - STOP and ask
|
||||
|
||||
### Step 3: Check Syntax Compliance
|
||||
Scan your code for forbidden patterns:
|
||||
- ❌ No `$"..."` - Use `string.Format()`
|
||||
- ❌ No `?.` or `?[` - Use explicit null checks
|
||||
- ❌ No `=>` in properties/methods - Use full syntax
|
||||
- ❌ No `nameof()` - Use string literals
|
||||
|
||||
## After Completing Each Class
|
||||
|
||||
### Step 4: Run Unit Tests (if applicable)
|
||||
```bash
|
||||
dotnet test tests\NT8.Core.Tests --filter "FullyQualifiedName~OMS"
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Passed! - Failed: 0, Passed: X
|
||||
```
|
||||
|
||||
### Step 5: Review Against Checklist
|
||||
- [ ] All public members have XML documentation
|
||||
- [ ] All dictionary access uses `lock (_lock)`
|
||||
- [ ] All public methods have try-catch
|
||||
- [ ] All logging uses `string.Format()`
|
||||
- [ ] No C# 6+ syntax anywhere
|
||||
- [ ] File compiles without warnings
|
||||
|
||||
## After Completing Full Task
|
||||
|
||||
### Step 6: Comprehensive Build
|
||||
```bash
|
||||
dotnet build NT8-SDK.sln --configuration Release
|
||||
```
|
||||
|
||||
### Step 7: Full Test Suite
|
||||
```bash
|
||||
dotnet test tests\NT8.Core.Tests --verbosity normal
|
||||
```
|
||||
|
||||
### Step 8: Code Coverage (Optional but Recommended)
|
||||
```bash
|
||||
dotnet test tests\NT8.Core.Tests --collect:"XPlat Code Coverage"
|
||||
```
|
||||
|
||||
**Target:** >80% coverage for new code
|
||||
|
||||
## Common Verification Failures
|
||||
|
||||
### "Feature 'string interpolation' is not available"
|
||||
**Cause:** Used `$"text {var}"`
|
||||
**Fix:** Replace with `string.Format("text {0}", var)`
|
||||
|
||||
### "Feature 'null-conditional operator' is not available"
|
||||
**Cause:** Used `obj?.Property`
|
||||
**Fix:** Replace with explicit null check
|
||||
|
||||
### "Cannot access member before initialization"
|
||||
**Cause:** Used auto-property initializer
|
||||
**Fix:** Move initialization to constructor
|
||||
|
||||
### Lock-related warnings
|
||||
**Cause:** Dictionary access outside lock
|
||||
**Fix:** Wrap in `lock (_lock) { ... }`
|
||||
|
||||
## Emergency Stop Conditions
|
||||
|
||||
STOP immediately and ask for help if:
|
||||
1. ❌ Build fails with errors you don't understand
|
||||
2. ❌ Tests fail unexpectedly after your changes
|
||||
3. ❌ You need to modify files outside allowed directories
|
||||
4. ❌ You're unsure about a design decision
|
||||
5. ❌ Performance is severely degraded
|
||||
|
||||
## Verification Workflow Summary
|
||||
|
||||
```
|
||||
Write Code
|
||||
↓
|
||||
Run verify-build.bat
|
||||
↓
|
||||
Build passes? → NO → Fix errors, repeat
|
||||
↓ YES
|
||||
Check syntax (no C# 6+)
|
||||
↓
|
||||
Check patterns (locks, try-catch, logging)
|
||||
↓
|
||||
Check documentation (XML docs)
|
||||
↓
|
||||
Run unit tests (if applicable)
|
||||
↓
|
||||
All pass? → NO → Fix tests, repeat
|
||||
↓ YES
|
||||
Mark file complete ✅
|
||||
↓
|
||||
Move to next file
|
||||
```
|
||||
|
||||
## Quality Gates
|
||||
|
||||
Your code MUST pass these gates before being considered complete:
|
||||
|
||||
### Gate 1: Compilation
|
||||
- ✅ `verify-build.bat` outputs "All checks passed!"
|
||||
- ✅ No compiler warnings
|
||||
- ✅ All references resolve
|
||||
|
||||
### Gate 2: Syntax Compliance
|
||||
- ✅ No C# 6+ features detected
|
||||
- ✅ Only .NET Framework 4.8 APIs used
|
||||
- ✅ Proper using statements
|
||||
|
||||
### Gate 3: Pattern Compliance
|
||||
- ✅ Thread-safe operations
|
||||
- ✅ Error handling present
|
||||
- ✅ Logging at correct levels
|
||||
- ✅ XML documentation complete
|
||||
|
||||
### Gate 4: Testing
|
||||
- ✅ Unit tests written and passing
|
||||
- ✅ Coverage >80% (target)
|
||||
- ✅ Edge cases tested
|
||||
|
||||
## Self-Check Questions
|
||||
|
||||
Before marking a file complete, ask:
|
||||
1. Does `verify-build.bat` pass?
|
||||
2. Did I use any C# 6+ syntax?
|
||||
3. Is all dictionary access inside locks?
|
||||
4. Do all public methods have try-catch?
|
||||
5. Does all logging use string.Format?
|
||||
6. Do all public members have XML docs?
|
||||
7. Are there unit tests for this code?
|
||||
8. Do the tests pass?
|
||||
|
||||
**If any answer is "No" or "I'm not sure" → DO NOT PROCEED**
|
||||
184
BUILD_WARNINGS_REFERENCE.md
Normal file
184
BUILD_WARNINGS_REFERENCE.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Build Warnings - Quick Fix Guide
|
||||
|
||||
**Date:** February 15, 2026
|
||||
**Build Status:** ✅ SUCCESS (with warnings)
|
||||
|
||||
---
|
||||
|
||||
## Current Warnings Summary
|
||||
|
||||
### CS1998: Async method without await (12 occurrences)
|
||||
|
||||
**Location:**
|
||||
- `OrderManager.cs` (7 warnings)
|
||||
- `OrderManagerTests.cs` (2 warnings)
|
||||
|
||||
**Issue:** Methods marked as `async` but don't use `await`
|
||||
|
||||
**Fix Options:**
|
||||
|
||||
#### Option 1: Remove async if not needed
|
||||
```csharp
|
||||
// BEFORE (Warning)
|
||||
public async Task<string> MethodName()
|
||||
{
|
||||
return "result";
|
||||
}
|
||||
|
||||
// AFTER (Fixed)
|
||||
public Task<string> MethodName()
|
||||
{
|
||||
return Task.FromResult("result");
|
||||
}
|
||||
```
|
||||
|
||||
#### Option 2: Add await if async operation exists
|
||||
```csharp
|
||||
// If you have async operations
|
||||
public async Task<string> MethodName()
|
||||
{
|
||||
await SomeAsyncOperation();
|
||||
return "result";
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CS0169/CS0414: Unused fields (5 occurrences)
|
||||
|
||||
**Location:** `SimpleORBNT8Wrapper.cs`
|
||||
|
||||
**Issue:** Fields declared but never used
|
||||
|
||||
**Fields:**
|
||||
- `_rangeSize`
|
||||
- `_openingRangeHigh`
|
||||
- `_openingRangeStart`
|
||||
- `_openingRangeLow`
|
||||
- `_openingRangeCalculated`
|
||||
|
||||
**Fix Options:**
|
||||
|
||||
#### Option 1: Remove if truly unused
|
||||
```csharp
|
||||
// Remove these lines if not needed:
|
||||
private double _openingRangeHigh;
|
||||
private double _openingRangeLow;
|
||||
```
|
||||
|
||||
#### Option 2: Use the fields
|
||||
```csharp
|
||||
// If you plan to use them, implement the logic
|
||||
private double _openingRangeHigh = 0;
|
||||
|
||||
void CalculateRange()
|
||||
{
|
||||
_openingRangeHigh = High[0]; // Use the field
|
||||
}
|
||||
```
|
||||
|
||||
#### Option 3: Suppress if placeholder for future
|
||||
```csharp
|
||||
#pragma warning disable CS0169
|
||||
private double _openingRangeHigh; // Will be used in Phase 2
|
||||
#pragma warning restore CS0169
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Action Items
|
||||
|
||||
### Priority 1: Critical for OMS
|
||||
❌ **None** - OMS implementation hasn't started yet
|
||||
|
||||
### Priority 2: Existing Code Cleanup
|
||||
These warnings are in **existing code** (not OMS):
|
||||
- `OrderManager.cs` - 7 async warnings
|
||||
- `SimpleORBNT8Wrapper.cs` - 5 unused field warnings
|
||||
- `OrderManagerTests.cs` - 2 async warnings
|
||||
|
||||
**Recommendation:** Fix these **after** OMS implementation to avoid modifying existing code.
|
||||
|
||||
---
|
||||
|
||||
## For Kilocode: Warning Rules
|
||||
|
||||
### ✅ ALLOWED: Warnings in existing code
|
||||
Kilocode can ignore warnings in:
|
||||
- `src/NT8.Adapters/**` (existing wrapper)
|
||||
- Existing `OrderManager.cs` (if it exists before OMS work)
|
||||
- Existing test files
|
||||
|
||||
### ❌ FORBIDDEN: Warnings in new OMS code
|
||||
Kilocode MUST NOT introduce warnings in new code:
|
||||
- New `src/NT8.Core/OMS/**` files
|
||||
- New `tests/NT8.Core.Tests/OMS/**` files
|
||||
|
||||
### Rule for Kilocode:
|
||||
```
|
||||
When creating new OMS files:
|
||||
- NO CS1998 warnings (remove async or add await)
|
||||
- NO CS0169/CS0414 warnings (use all declared fields)
|
||||
- Build with ZERO warnings for new code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Verification
|
||||
|
||||
### Current Status
|
||||
```
|
||||
Build: ✅ SUCCESS
|
||||
Warnings: 17 total
|
||||
- 12 × CS1998 (async without await)
|
||||
- 5 × CS0169/CS0414 (unused fields)
|
||||
|
||||
All warnings in EXISTING code (not OMS)
|
||||
```
|
||||
|
||||
### Target for OMS
|
||||
```
|
||||
Build: ✅ SUCCESS
|
||||
New OMS files: ZERO warnings
|
||||
Existing warnings: Can remain (cleanup later)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Fix Script (Optional)
|
||||
|
||||
If you want to clean up existing warnings before OMS work:
|
||||
|
||||
```powershell
|
||||
# Fix unused fields in SimpleORBNT8Wrapper.cs
|
||||
# Option 1: Comment out unused fields
|
||||
# Option 2: Implement ORB calculation logic
|
||||
# Option 3: Add #pragma warning disable
|
||||
|
||||
# Fix async warnings in OrderManager.cs
|
||||
# Review each method and either:
|
||||
# - Remove async keyword + return Task.FromResult()
|
||||
# - Add await operations
|
||||
# - Keep as-is if async needed for interface
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**For OMS Implementation:**
|
||||
- ✅ Build is working correctly
|
||||
- ✅ Existing warnings are acceptable
|
||||
- ✅ Kilocode should NOT modify existing code
|
||||
- ✅ New OMS code must have ZERO warnings
|
||||
|
||||
**After OMS Complete:**
|
||||
- Clean up existing warnings
|
||||
- Review async patterns
|
||||
- Remove unused fields or implement them
|
||||
|
||||
---
|
||||
|
||||
**Build status: Ready for OMS implementation!** 🚀
|
||||
|
||||
The warnings are in existing code, not a blocker for starting OMS work.
|
||||
229
KILOCODE_SETUP_COMPLETE.md
Normal file
229
KILOCODE_SETUP_COMPLETE.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# ✅ Kilocode Configuration - Installation Complete!
|
||||
|
||||
## Installation Summary
|
||||
|
||||
**Date:** February 15, 2026
|
||||
**Repository:** C:\dev\nt8-sdk
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
## Files Installed
|
||||
|
||||
### Kilocode Custom Rules (5 files in `.kilocode\rules\`)
|
||||
✅ `csharp_50_syntax.md` - C# 5.0 syntax enforcement
|
||||
✅ `file_boundaries.md` - File modification boundaries
|
||||
✅ `coding_patterns.md` - Mandatory coding patterns
|
||||
✅ `verification_requirements.md` - Verification requirements
|
||||
✅ `project_context.md` - Project context and architecture
|
||||
|
||||
### VS Code Configuration (2 files in `.vscode\`)
|
||||
✅ `settings.json` - IDE settings and Kilocode configuration
|
||||
✅ `tasks.json` - Quick build and test tasks
|
||||
|
||||
### Editor Configuration (1 file in root)
|
||||
✅ `.editorconfig` - C# 5.0 enforcement at editor level
|
||||
|
||||
---
|
||||
|
||||
## What This Configuration Does
|
||||
|
||||
### Automatic C# 5.0 Enforcement
|
||||
- ❌ Prevents string interpolation (`$"..."`)
|
||||
- ❌ Prevents null-conditional operators (`?.`, `?[`)
|
||||
- ❌ Prevents expression-bodied members (`=>`)
|
||||
- ❌ Prevents all C# 6+ features
|
||||
- ✅ Kilocode will only suggest C# 5.0 compatible code
|
||||
|
||||
### File Boundary Protection
|
||||
- ✅ Kilocode can only modify OMS-related files
|
||||
- ❌ Cannot modify Core/Risk/Sizing (existing systems)
|
||||
- ❌ Cannot modify build configuration
|
||||
- ❌ Cannot modify documentation
|
||||
|
||||
### Mandatory Patterns Enforcement
|
||||
- ✅ Thread-safe dictionary access (locks required)
|
||||
- ✅ Try-catch on all public methods
|
||||
- ✅ Structured logging with string.Format
|
||||
- ✅ XML documentation on all public members
|
||||
- ✅ Event raising outside locks
|
||||
|
||||
### Verification After Every File
|
||||
- ✅ Reminds Kilocode to run `verify-build.bat`
|
||||
- ✅ Checks for C# 5.0 compliance
|
||||
- ✅ Validates coding patterns
|
||||
|
||||
### Project Context Awareness
|
||||
- ✅ Kilocode knows it's working on OMS
|
||||
- ✅ Understands NT8 SDK architecture
|
||||
- ✅ Knows performance targets (<200ms latency)
|
||||
- ✅ Understands this is production trading code
|
||||
|
||||
---
|
||||
|
||||
## Quick Start with Kilocode
|
||||
|
||||
### Step 1: Restart VS Code
|
||||
Close and reopen VS Code to load the new configuration.
|
||||
|
||||
### Step 2: Verify Rules Loaded
|
||||
1. Open Kilocode panel
|
||||
2. Click the law icon (⚖️) in bottom right
|
||||
3. You should see **5 rules** listed and enabled:
|
||||
- csharp_50_syntax
|
||||
- file_boundaries
|
||||
- coding_patterns
|
||||
- verification_requirements
|
||||
- project_context
|
||||
|
||||
### Step 3: Test Quick Tasks
|
||||
Press `Ctrl+Shift+B` - this should run `verify-build.bat`
|
||||
|
||||
### Step 4: Start Your First Kilocode Session
|
||||
In Kilocode chat, type:
|
||||
|
||||
```
|
||||
I'm ready to implement the OMS (Order Management System).
|
||||
|
||||
I will follow the task breakdown in Kilocode_Implementation_Guide.md
|
||||
starting with Task A1: Create OrderModels.cs
|
||||
|
||||
Please confirm you've loaded all rules from .kilocode/rules/
|
||||
and understand the C# 5.0 syntax requirements.
|
||||
```
|
||||
|
||||
Kilocode should respond acknowledging the rules and confirming it's ready to start.
|
||||
|
||||
---
|
||||
|
||||
## Configuration Details
|
||||
|
||||
### Kilocode Settings (in `.vscode\settings.json`)
|
||||
```json
|
||||
{
|
||||
"kilocode.customRulesPath": ".kilocode/rules",
|
||||
"kilocode.enableAutoApproval": false,
|
||||
"kilocode.maxTokens": 4000
|
||||
}
|
||||
```
|
||||
|
||||
### Default Build Task (Ctrl+Shift+B)
|
||||
Runs: `.\verify-build.bat`
|
||||
|
||||
### Other Available Tasks
|
||||
- `test-oms` - Run OMS-specific tests
|
||||
- `test-all` - Run full test suite
|
||||
- `build-release` - Build in Release mode
|
||||
- `test-with-coverage` - Run tests with coverage
|
||||
|
||||
Access via: `Ctrl+Shift+P` → "Tasks: Run Task"
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Rules Not Loading?
|
||||
1. Check files exist in `.kilocode\rules\`
|
||||
2. Restart VS Code
|
||||
3. Check Kilocode extension is active
|
||||
4. Click law icon (⚖️) to verify rules list
|
||||
|
||||
### Tasks Not Working?
|
||||
1. Check `.vscode\tasks.json` exists
|
||||
2. Try `Ctrl+Shift+P` → "Tasks: Run Task"
|
||||
3. Manually run: `.\verify-build.bat`
|
||||
|
||||
### EditorConfig Not Applied?
|
||||
1. Check `.editorconfig` exists in repository root
|
||||
2. Restart VS Code
|
||||
3. Check EditorConfig extension is installed
|
||||
|
||||
---
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
### When You Open a .cs File
|
||||
- 4-space indentation enforced
|
||||
- Trailing whitespace removed on save
|
||||
- CRLF line endings
|
||||
- Using statements organized on save
|
||||
|
||||
### When You Use Kilocode
|
||||
- Suggests only C# 5.0 compatible code
|
||||
- Respects file modification boundaries
|
||||
- Follows mandatory coding patterns
|
||||
- Runs verification after changes
|
||||
- Understands project context
|
||||
|
||||
### When You Press Ctrl+Shift+B
|
||||
- Runs `verify-build.bat` automatically
|
||||
- Shows output in terminal
|
||||
- Success: "✅ All checks passed!"
|
||||
|
||||
---
|
||||
|
||||
## What's Already in Your .kilocode\rules\ Directory
|
||||
|
||||
I noticed your `.kilocode\rules\` directory already has these files:
|
||||
- archon.md
|
||||
- CODE_REVIEW_CHECKLIST.md
|
||||
- CODE_STYLE_GUIDE.md
|
||||
- Compile error guidance.md
|
||||
- development_workflow.md
|
||||
- Guidelines.md
|
||||
- nt8compilespec.md
|
||||
|
||||
**Good news:** Kilocode will load ALL of these together! The new files I added complement your existing rules.
|
||||
|
||||
**Total Rules:** 12 files (5 new + 7 existing)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ **Restart VS Code** to load configuration
|
||||
2. ✅ **Verify rules loaded** (click law icon ⚖️)
|
||||
3. ✅ **Test Ctrl+Shift+B** (runs verify-build.bat)
|
||||
4. ✅ **Begin OMS implementation** following Kilocode_Implementation_Guide.md
|
||||
|
||||
---
|
||||
|
||||
## File Locations Summary
|
||||
|
||||
```
|
||||
C:\dev\nt8-sdk\
|
||||
├── .kilocode\
|
||||
│ └── rules\
|
||||
│ ├── csharp_50_syntax.md ✅ NEW
|
||||
│ ├── file_boundaries.md ✅ NEW
|
||||
│ ├── coding_patterns.md ✅ NEW
|
||||
│ ├── verification_requirements.md ✅ NEW
|
||||
│ ├── project_context.md ✅ NEW
|
||||
│ ├── archon.md (existing)
|
||||
│ ├── CODE_REVIEW_CHECKLIST.md (existing)
|
||||
│ ├── CODE_STYLE_GUIDE.md (existing)
|
||||
│ ├── Compile error guidance.md (existing)
|
||||
│ ├── development_workflow.md (existing)
|
||||
│ ├── Guidelines.md (existing)
|
||||
│ └── nt8compilespec.md (existing)
|
||||
├── .vscode\
|
||||
│ ├── settings.json ✅ NEW
|
||||
│ └── tasks.json ✅ NEW
|
||||
├── .editorconfig ✅ NEW
|
||||
└── [your existing files...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success! 🎉
|
||||
|
||||
Your repository is now fully configured for Kilocode development!
|
||||
|
||||
**Estimated time savings:** 2+ hours on OMS implementation
|
||||
**ROI:** ~25x return on 5-minute setup
|
||||
|
||||
**Ready to start building!**
|
||||
|
||||
---
|
||||
|
||||
*Configuration installed by Claude on February 15, 2026*
|
||||
169
OMS_IMPLEMENTATION_START.md
Normal file
169
OMS_IMPLEMENTATION_START.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# ✅ OMS Implementation - Ready to Start!
|
||||
|
||||
**Date:** February 15, 2026
|
||||
**Repository:** C:\dev\nt8-sdk
|
||||
**Status:** ALL FILES READY
|
||||
|
||||
---
|
||||
|
||||
## 📋 OMS Documentation Files (In Repository)
|
||||
|
||||
✅ **OMS_Design_Specification.md** (42 KB)
|
||||
- Complete technical design
|
||||
- Interface definitions
|
||||
- State machine specification
|
||||
- Implementation requirements
|
||||
|
||||
✅ **Kilocode_Implementation_Guide.md** (40 KB)
|
||||
- Step-by-step task breakdown
|
||||
- Phase A-E detailed instructions
|
||||
- Code templates and examples
|
||||
- Verification steps
|
||||
|
||||
✅ **OMS_Test_Scenarios.md** (18 KB)
|
||||
- 50+ comprehensive test cases
|
||||
- Edge case coverage
|
||||
- Performance benchmarks
|
||||
- Test data builders
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Ready to Start with Kilocode
|
||||
|
||||
### OPTION 1: Code Mode (Recommended)
|
||||
|
||||
**Use this for direct implementation following the guide.**
|
||||
|
||||
**Paste into Kilocode Code Mode:**
|
||||
|
||||
```
|
||||
I'm ready to implement the OMS (Order Management System).
|
||||
|
||||
I will follow the task breakdown in Kilocode_Implementation_Guide.md
|
||||
starting with Task A1: Create OrderModels.cs
|
||||
|
||||
Please confirm you've loaded all rules from .kilocode/rules/
|
||||
and understand:
|
||||
- C# 5.0 syntax requirements (no $, ?., =>)
|
||||
- File modification boundaries (OMS directories only)
|
||||
- Mandatory coding patterns (locks, try-catch, logging)
|
||||
- Verification requirements (verify-build.bat after each file)
|
||||
- Project context (production trading code)
|
||||
|
||||
Let's start with creating OrderModels.cs in src/NT8.Core/OMS/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### OPTION 2: Architect Mode (If You Want Design Review First)
|
||||
|
||||
**Use this if you want Kilocode to review the design before coding.**
|
||||
|
||||
**Paste into Kilocode Architect Mode:**
|
||||
|
||||
```
|
||||
Review the OMS design in OMS_Design_Specification.md and
|
||||
Kilocode_Implementation_Guide.md
|
||||
|
||||
Analyze:
|
||||
1. Are there any design issues or improvements needed?
|
||||
2. Is the implementation plan optimal?
|
||||
3. Any risks or concerns before we start coding?
|
||||
|
||||
After review, we'll switch to Code Mode for implementation.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 File Locations
|
||||
|
||||
All documentation is in your repository root:
|
||||
|
||||
```
|
||||
C:\dev\nt8-sdk\
|
||||
├── OMS_Design_Specification.md ✅ 42 KB
|
||||
├── Kilocode_Implementation_Guide.md ✅ 40 KB
|
||||
├── OMS_Test_Scenarios.md ✅ 18 KB
|
||||
├── KILOCODE_SETUP_COMPLETE.md ✅ Setup guide
|
||||
└── BUILD_WARNINGS_REFERENCE.md ✅ Build info
|
||||
```
|
||||
|
||||
Implementation code will go in:
|
||||
```
|
||||
src/NT8.Core/OMS/ ← Implementation files
|
||||
tests/NT8.Core.Tests/OMS/ ← Unit tests
|
||||
tests/NT8.Core.Tests/Mocks/ ← Mock adapters
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ Implementation Timeline
|
||||
|
||||
**Total Estimated Time:** 6 hours
|
||||
|
||||
| Phase | Task | Time | Files |
|
||||
|-------|------|------|-------|
|
||||
| **A** | Core Models & Interfaces | 30 min | 3 files |
|
||||
| **B** | BasicOrderManager | 2 hours | 1 file |
|
||||
| **C** | Mock Adapter | 30 min | 1 file |
|
||||
| **D** | Unit Tests | 2 hours | 5 test files |
|
||||
| **E** | Verification | 30 min | Validation |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Next Actions
|
||||
|
||||
**STEP 1:** Open Kilocode panel in VS Code
|
||||
|
||||
**STEP 2:** Choose your mode:
|
||||
- **Code Mode** → Direct implementation (faster)
|
||||
- **Architect Mode** → Design review first (safer)
|
||||
|
||||
**STEP 3:** Paste the appropriate starter prompt from above
|
||||
|
||||
**STEP 4:** Confirm Kilocode has loaded the rules (should see 12 rules)
|
||||
|
||||
**STEP 5:** Begin implementation following the guide
|
||||
|
||||
---
|
||||
|
||||
## ✅ Pre-Flight Checklist
|
||||
|
||||
Before starting, verify:
|
||||
|
||||
- [ ] VS Code restarted (to load Kilocode rules)
|
||||
- [ ] Kilocode panel open
|
||||
- [ ] Law icon (⚖️) shows 12 rules loaded
|
||||
- [ ] Build is clean (`Ctrl+Shift+B` works)
|
||||
- [ ] All 3 OMS documents visible in repo root
|
||||
- [ ] Ready to commit ~6 hours to implementation
|
||||
|
||||
---
|
||||
|
||||
## 💡 Recommendation
|
||||
|
||||
**Use Code Mode** because:
|
||||
1. ✅ Design is complete and detailed
|
||||
2. ✅ Implementation guide is step-by-step
|
||||
3. ✅ Rules enforce quality automatically
|
||||
4. ✅ Faster path to working OMS
|
||||
|
||||
Switch to Architect Mode only if you hit unexpected design issues.
|
||||
|
||||
---
|
||||
|
||||
## 📞 During Implementation
|
||||
|
||||
If you need to:
|
||||
- **Pause**: Just stop, Kilocode will resume from last file
|
||||
- **Switch modes**: Close and reopen Kilocode in different mode
|
||||
- **Get help**: Reference the design spec or test scenarios
|
||||
- **Verify**: Run `Ctrl+Shift+B` after each file
|
||||
|
||||
---
|
||||
|
||||
**Everything is ready. Choose your mode and start!** 🚀
|
||||
|
||||
---
|
||||
|
||||
*Documentation copied to repository: February 15, 2026*
|
||||
727
docs/architecture/interface_stability_contract.md
Normal file
727
docs/architecture/interface_stability_contract.md
Normal file
@@ -0,0 +1,727 @@
|
||||
# Interface Stability Contract - SDK ↔ Adapter Boundary
|
||||
|
||||
**Version**: 1.0
|
||||
**Date**: February 14, 2026
|
||||
**Status**: DRAFT - Needs Review & Approval
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the **stable API contract** between:
|
||||
- **NT8.Core.dll** (SDK - platform-agnostic)
|
||||
- **NT8.Adapters.dll** (Adapters - platform-specific)
|
||||
|
||||
**Goal**: Ensure SDK updates don't break adapters, and vice versa.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
### 1. **Stable Interfaces, Evolving Implementations**
|
||||
- Interfaces are contracts (change rarely)
|
||||
- Implementations can evolve freely (change often)
|
||||
- Adapters depend on interfaces, NOT implementations
|
||||
|
||||
### 2. **Semantic Versioning**
|
||||
- **MAJOR**: Breaking changes to interfaces
|
||||
- **MINOR**: New features (backward compatible)
|
||||
- **PATCH**: Bug fixes (no API changes)
|
||||
|
||||
### 3. **Explicit Deprecation Cycle**
|
||||
- Deprecated methods stay for 2+ minor versions
|
||||
- Mark with `[Obsolete]` attribute
|
||||
- Provide migration path in docs
|
||||
|
||||
---
|
||||
|
||||
## Current Interface Contract (v1.0)
|
||||
|
||||
### Core SDK Interfaces (STABLE)
|
||||
|
||||
These interfaces define the boundary. **Changes require MAJOR version bump.**
|
||||
|
||||
#### 1. Strategy Interface
|
||||
|
||||
```csharp
|
||||
// src/NT8.Core/Common/Interfaces/IStrategy.cs
|
||||
// VERSION: 1.0.0
|
||||
// STABILITY: STABLE
|
||||
|
||||
public interface IStrategy
|
||||
{
|
||||
// Properties
|
||||
StrategyMetadata Metadata { get; }
|
||||
|
||||
// Methods
|
||||
void Initialize(StrategyConfig config, IMarketDataProvider dataProvider, ILogger logger);
|
||||
StrategyIntent OnBar(BarData bar, StrategyContext context);
|
||||
StrategyIntent OnTick(TickData tick, StrategyContext context);
|
||||
Dictionary<string, object> GetParameters();
|
||||
void SetParameters(Dictionary<string, object> parameters);
|
||||
}
|
||||
```
|
||||
|
||||
**Stability Guarantee:**
|
||||
- ✅ Method signatures won't change
|
||||
- ✅ Method names won't change
|
||||
- ✅ Return types won't change (may add properties to returned objects)
|
||||
- ✅ Parameter types won't change (may add optional parameters)
|
||||
|
||||
**Allowed Changes:**
|
||||
- ➕ Add new optional methods with default implementations
|
||||
- ➕ Add properties to `StrategyMetadata`
|
||||
- ➕ Add properties to `StrategyConfig`
|
||||
- ❌ Cannot remove existing methods
|
||||
- ❌ Cannot change existing method signatures
|
||||
|
||||
---
|
||||
|
||||
#### 2. Data Models (STABLE)
|
||||
|
||||
```csharp
|
||||
// src/NT8.Core/Common/Models/BarData.cs
|
||||
// VERSION: 1.0.0
|
||||
// STABILITY: STABLE
|
||||
|
||||
public class BarData
|
||||
{
|
||||
// Core properties (IMMUTABLE)
|
||||
public string Symbol { get; set; }
|
||||
public DateTime Time { get; set; }
|
||||
public double Open { get; set; }
|
||||
public double High { get; set; }
|
||||
public double Low { get; set; }
|
||||
public double Close { get; set; }
|
||||
public long Volume { get; set; }
|
||||
public TimeSpan BarSize { get; set; }
|
||||
|
||||
// Constructor (IMMUTABLE signature)
|
||||
public BarData(
|
||||
string symbol,
|
||||
DateTime time,
|
||||
double open,
|
||||
double high,
|
||||
double low,
|
||||
double close,
|
||||
long volume,
|
||||
TimeSpan barSize)
|
||||
{ ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Stability Guarantee:**
|
||||
- ✅ Existing properties keep same names
|
||||
- ✅ Existing properties keep same types
|
||||
- ✅ Constructor signature won't change (may add overloads)
|
||||
- ✅ Property getters/setters won't change behavior
|
||||
|
||||
**Allowed Changes:**
|
||||
- ➕ Add new properties (with sensible defaults)
|
||||
- ➕ Add new constructor overloads
|
||||
- ➕ Add helper methods
|
||||
- ❌ Cannot rename existing properties
|
||||
- ❌ Cannot change property types
|
||||
- ❌ Cannot remove properties
|
||||
|
||||
---
|
||||
|
||||
#### 3. Strategy Intent (STABLE)
|
||||
|
||||
```csharp
|
||||
// src/NT8.Core/Common/Models/StrategyIntent.cs
|
||||
// VERSION: 1.0.0
|
||||
// STABILITY: STABLE
|
||||
|
||||
public class StrategyIntent
|
||||
{
|
||||
// Core properties (IMMUTABLE)
|
||||
public string IntentId { get; private set; }
|
||||
public DateTime Timestamp { get; private set; }
|
||||
public string Symbol { get; set; }
|
||||
public OrderSide Side { get; set; }
|
||||
public OrderType EntryType { get; set; }
|
||||
public double? LimitPrice { get; set; }
|
||||
public int StopTicks { get; set; }
|
||||
public int? TargetTicks { get; set; }
|
||||
public double Confidence { get; set; }
|
||||
public string Reason { get; set; }
|
||||
public Dictionary<string, object> Metadata { get; set; }
|
||||
|
||||
// Constructor (IMMUTABLE signature)
|
||||
public StrategyIntent(
|
||||
string symbol,
|
||||
OrderSide side,
|
||||
OrderType entryType,
|
||||
double? limitPrice,
|
||||
int stopTicks,
|
||||
int? targetTicks,
|
||||
double confidence,
|
||||
string reason,
|
||||
Dictionary<string, object> metadata)
|
||||
{ ... }
|
||||
|
||||
// Validation (IMMUTABLE signature)
|
||||
public bool IsValid() { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Stability Guarantee:**
|
||||
- ✅ All property names fixed
|
||||
- ✅ All property types fixed
|
||||
- ✅ `IsValid()` signature fixed
|
||||
- ✅ Enums can add new values (but not remove)
|
||||
|
||||
**Allowed Changes:**
|
||||
- ➕ Add new optional properties
|
||||
- ➕ Add new validation methods
|
||||
- ➕ Add enum values to `OrderSide`, `OrderType`
|
||||
- ❌ Cannot remove properties
|
||||
- ❌ Cannot change property types
|
||||
- ❌ Cannot remove enum values
|
||||
|
||||
---
|
||||
|
||||
#### 4. Strategy Context (STABLE)
|
||||
|
||||
```csharp
|
||||
// src/NT8.Core/Common/Models/StrategyContext.cs
|
||||
// VERSION: 1.0.0
|
||||
// STABILITY: STABLE
|
||||
|
||||
public class StrategyContext
|
||||
{
|
||||
// Core properties (IMMUTABLE)
|
||||
public string Symbol { get; set; }
|
||||
public DateTime CurrentTime { get; set; }
|
||||
public Position CurrentPosition { get; set; }
|
||||
public AccountInfo Account { get; set; }
|
||||
public MarketSession Session { get; set; }
|
||||
public Dictionary<string, object> CustomData { get; set; }
|
||||
|
||||
// Constructor (IMMUTABLE signature)
|
||||
public StrategyContext(
|
||||
string symbol,
|
||||
DateTime currentTime,
|
||||
Position currentPosition,
|
||||
AccountInfo account,
|
||||
MarketSession session,
|
||||
Dictionary<string, object> customData)
|
||||
{ ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Stability Guarantee:**
|
||||
- ✅ Context structure is stable
|
||||
- ✅ Nested objects (`Position`, `AccountInfo`, `MarketSession`) can add properties
|
||||
- ✅ `CustomData` dictionary for extensibility
|
||||
|
||||
**Allowed Changes:**
|
||||
- ➕ Add properties to `Position`, `AccountInfo`, `MarketSession`
|
||||
- ➕ Add new top-level properties to `StrategyContext`
|
||||
- ❌ Cannot remove existing properties
|
||||
- ❌ Cannot change property types
|
||||
|
||||
---
|
||||
|
||||
### Adapter Interface (SEMI-STABLE)
|
||||
|
||||
This is platform-specific. Can evolve more freely.
|
||||
|
||||
```csharp
|
||||
// src/NT8.Adapters/NinjaTrader/INT8Adapter.cs
|
||||
// VERSION: 1.0.0
|
||||
// STABILITY: SEMI-STABLE (can evolve between minor versions)
|
||||
|
||||
public interface INT8Adapter
|
||||
{
|
||||
// Initialization
|
||||
void Initialize(IRiskManager riskManager, IPositionSizer positionSizer);
|
||||
|
||||
// Data conversion (SDK models as return types = STABLE)
|
||||
BarData ConvertToSdkBar(string symbol, DateTime time, double open, double high, double low, double close, long volume, int barSize);
|
||||
AccountInfo ConvertToSdkAccount(double equity, double buyingPower, double dailyPnL, double maxDrawdown, DateTime lastUpdate);
|
||||
Position ConvertToSdkPosition(string symbol, int quantity, double averagePrice, double unrealizedPnL, double realizedPnL, DateTime lastUpdate);
|
||||
|
||||
// Intent execution (SDK models as parameters = STABLE)
|
||||
void ExecuteIntent(StrategyIntent intent, SizingResult sizing);
|
||||
|
||||
// NT8 callbacks (NT8-specific parameters = CAN CHANGE)
|
||||
void OnOrderUpdate(string orderId, double limitPrice, double stopPrice, int quantity, int filled, double averageFillPrice, string orderState, DateTime time, string errorCode, string nativeError);
|
||||
void OnExecutionUpdate(string executionId, string orderId, double price, int quantity, string marketPosition, DateTime time);
|
||||
}
|
||||
```
|
||||
|
||||
**Stability Guarantee:**
|
||||
- ✅ Methods that return SDK models are stable
|
||||
- ✅ Methods that accept SDK models are stable
|
||||
- 🟡 NT8-specific signatures can evolve (minor versions)
|
||||
|
||||
**Allowed Changes:**
|
||||
- ➕ Add new conversion methods
|
||||
- ➕ Add optional parameters to NT8-specific methods
|
||||
- ➕ Add new callback methods
|
||||
- ❌ Cannot change SDK model signatures
|
||||
- 🟡 Can change NT8-specific signatures (with deprecation)
|
||||
|
||||
---
|
||||
|
||||
## Versioning Strategy
|
||||
|
||||
### SDK Core (NT8.Core.dll)
|
||||
|
||||
```
|
||||
Version Format: MAJOR.MINOR.PATCH
|
||||
|
||||
1.0.0 → Initial release (Phase 1)
|
||||
1.1.0 → Add new optional features (Phase 2)
|
||||
1.2.0 → More new features (Phase 3)
|
||||
2.0.0 → Breaking interface changes (major refactor)
|
||||
```
|
||||
|
||||
**Breaking Changes (MAJOR bump):**
|
||||
- Remove methods from `IStrategy`
|
||||
- Change method signatures in core interfaces
|
||||
- Remove properties from data models
|
||||
- Change property types in data models
|
||||
|
||||
**Compatible Changes (MINOR bump):**
|
||||
- Add new optional interface methods (with defaults)
|
||||
- Add new properties to data models
|
||||
- Add new data models
|
||||
- Add new interfaces
|
||||
|
||||
**Bug Fixes (PATCH bump):**
|
||||
- Fix bugs in implementations
|
||||
- Performance improvements
|
||||
- Internal refactoring
|
||||
- Documentation updates
|
||||
|
||||
---
|
||||
|
||||
### Adapters (NT8.Adapters.dll)
|
||||
|
||||
```
|
||||
Version Format: Matches SDK version for compatibility
|
||||
|
||||
NT8.Core 1.0.0 → NT8.Adapters 1.0.x (compatible)
|
||||
NT8.Core 1.1.0 → NT8.Adapters 1.1.x (compatible)
|
||||
NT8.Core 2.0.0 → NT8.Adapters 2.0.x (requires rewrite)
|
||||
```
|
||||
|
||||
**Adapter versions MUST match SDK MAJOR.MINOR**
|
||||
|
||||
---
|
||||
|
||||
## Interface Evolution Examples
|
||||
|
||||
### Example 1: Adding Optional Feature (MINOR version)
|
||||
|
||||
**Scenario**: Add support for multiple targets
|
||||
|
||||
```csharp
|
||||
// v1.0.0 - Original
|
||||
public class StrategyIntent
|
||||
{
|
||||
public int? TargetTicks { get; set; }
|
||||
// ...
|
||||
}
|
||||
|
||||
// v1.1.0 - Enhanced (BACKWARD COMPATIBLE)
|
||||
public class StrategyIntent
|
||||
{
|
||||
public int? TargetTicks { get; set; } // Keep for compatibility
|
||||
|
||||
// NEW: Optional multiple targets
|
||||
public List<int> TargetTicksList { get; set; } // Defaults to null
|
||||
|
||||
// Helper to maintain compatibility
|
||||
public int? GetPrimaryTarget()
|
||||
{
|
||||
if (TargetTicksList != null && TargetTicksList.Count > 0)
|
||||
return TargetTicksList[0];
|
||||
return TargetTicks;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Adapter Impact**: ✅ None - old code still works
|
||||
**Strategy Impact**: ✅ None - can optionally use new feature
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Deprecating Old Method (MINOR version with warning)
|
||||
|
||||
**Scenario**: Rename method for clarity
|
||||
|
||||
```csharp
|
||||
// v1.0.0 - Original
|
||||
public interface IStrategy
|
||||
{
|
||||
StrategyIntent OnBar(BarData bar, StrategyContext context);
|
||||
}
|
||||
|
||||
// v1.1.0 - Add new, deprecate old
|
||||
public interface IStrategy
|
||||
{
|
||||
[Obsolete("Use OnBarClose instead. Will be removed in v2.0.0")]
|
||||
StrategyIntent OnBar(BarData bar, StrategyContext context);
|
||||
|
||||
// NEW preferred method
|
||||
StrategyIntent OnBarClose(BarData bar, StrategyContext context);
|
||||
}
|
||||
|
||||
// v1.2.0 - Still support both
|
||||
// ... same as v1.1.0 ...
|
||||
|
||||
// v2.0.0 - Remove old (BREAKING CHANGE)
|
||||
public interface IStrategy
|
||||
{
|
||||
StrategyIntent OnBarClose(BarData bar, StrategyContext context);
|
||||
}
|
||||
```
|
||||
|
||||
**Migration Timeline**:
|
||||
- v1.1.0: Add new method, deprecate old (warning)
|
||||
- v1.2.0: Keep both (warning)
|
||||
- v2.0.0: Remove old (breaking change, requires adapter update)
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Breaking Change (MAJOR version)
|
||||
|
||||
**Scenario**: Change position model to support multi-symbol
|
||||
|
||||
```csharp
|
||||
// v1.x.x - Original
|
||||
public class StrategyContext
|
||||
{
|
||||
public Position CurrentPosition { get; set; } // Single position
|
||||
}
|
||||
|
||||
// v2.0.0 - Breaking change
|
||||
public class StrategyContext
|
||||
{
|
||||
public Dictionary<string, Position> Positions { get; set; } // Multi-symbol
|
||||
|
||||
// Helper for single-symbol strategies
|
||||
public Position GetPosition(string symbol)
|
||||
{
|
||||
return Positions.ContainsKey(symbol) ? Positions[symbol] : null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Adapter Impact**: ❌ Must update - breaking change
|
||||
**Migration Required**: Yes, all adapters need rewrite
|
||||
**Version Bump**: 1.x.x → 2.0.0
|
||||
|
||||
---
|
||||
|
||||
## Compatibility Matrix
|
||||
|
||||
### SDK ↔ Adapter Compatibility
|
||||
|
||||
| SDK Version | Adapter Version | Compatible? | Notes |
|
||||
|-------------|-----------------|-------------|-------|
|
||||
| 1.0.0 | 1.0.x | ✅ Yes | Perfect match |
|
||||
| 1.1.0 | 1.0.x | ✅ Yes | Forward compatible |
|
||||
| 1.1.0 | 1.1.x | ✅ Yes | Perfect match |
|
||||
| 1.2.0 | 1.1.x | ✅ Yes | Forward compatible |
|
||||
| 2.0.0 | 1.x.x | ❌ No | Breaking change |
|
||||
| 2.0.0 | 2.0.x | ✅ Yes | Perfect match |
|
||||
|
||||
**Rule**: Adapter MINOR can be less than SDK MINOR (forward compatible)
|
||||
**Rule**: Adapter MAJOR must equal SDK MAJOR
|
||||
|
||||
---
|
||||
|
||||
## Contract Testing
|
||||
|
||||
### Automated Contract Tests
|
||||
|
||||
Create tests that verify interface stability:
|
||||
|
||||
```csharp
|
||||
// tests/NT8.Core.Tests/Contracts/InterfaceStabilityTests.cs
|
||||
|
||||
[Fact]
|
||||
public void IStrategy_Interface_Should_Be_Stable()
|
||||
{
|
||||
var type = typeof(IStrategy);
|
||||
|
||||
// Verify method count hasn't decreased
|
||||
var methods = type.GetMethods();
|
||||
Assert.True(methods.Length >= 5, "IStrategy methods removed!");
|
||||
|
||||
// Verify specific methods exist
|
||||
Assert.NotNull(type.GetMethod("OnBar"));
|
||||
Assert.NotNull(type.GetMethod("OnTick"));
|
||||
Assert.NotNull(type.GetMethod("Initialize"));
|
||||
|
||||
// Verify method signatures
|
||||
var onBarMethod = type.GetMethod("OnBar");
|
||||
Assert.Equal(typeof(StrategyIntent), onBarMethod.ReturnType);
|
||||
|
||||
var parameters = onBarMethod.GetParameters();
|
||||
Assert.Equal(2, parameters.Length);
|
||||
Assert.Equal(typeof(BarData), parameters[0].ParameterType);
|
||||
Assert.Equal(typeof(StrategyContext), parameters[1].ParameterType);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void BarData_Properties_Should_Be_Stable()
|
||||
{
|
||||
var type = typeof(BarData);
|
||||
|
||||
// Verify required properties exist
|
||||
Assert.NotNull(type.GetProperty("Symbol"));
|
||||
Assert.NotNull(type.GetProperty("Time"));
|
||||
Assert.NotNull(type.GetProperty("Open"));
|
||||
Assert.NotNull(type.GetProperty("High"));
|
||||
Assert.NotNull(type.GetProperty("Low"));
|
||||
Assert.NotNull(type.GetProperty("Close"));
|
||||
Assert.NotNull(type.GetProperty("Volume"));
|
||||
|
||||
// Verify property types haven't changed
|
||||
Assert.Equal(typeof(string), type.GetProperty("Symbol").PropertyType);
|
||||
Assert.Equal(typeof(DateTime), type.GetProperty("Time").PropertyType);
|
||||
Assert.Equal(typeof(double), type.GetProperty("Open").PropertyType);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void StrategyIntent_Constructor_Should_Be_Stable()
|
||||
{
|
||||
var type = typeof(StrategyIntent);
|
||||
|
||||
// Verify constructor exists with expected parameters
|
||||
var constructor = type.GetConstructor(new[]
|
||||
{
|
||||
typeof(string), // symbol
|
||||
typeof(OrderSide), // side
|
||||
typeof(OrderType), // entryType
|
||||
typeof(double?), // limitPrice
|
||||
typeof(int), // stopTicks
|
||||
typeof(int?), // targetTicks
|
||||
typeof(double), // confidence
|
||||
typeof(string), // reason
|
||||
typeof(Dictionary<string, object>) // metadata
|
||||
});
|
||||
|
||||
Assert.NotNull(constructor);
|
||||
}
|
||||
```
|
||||
|
||||
**Run these tests** in CI/CD to catch accidental breaking changes!
|
||||
|
||||
---
|
||||
|
||||
## Adapter-Safe Practices
|
||||
|
||||
### For SDK Developers
|
||||
|
||||
**DO:**
|
||||
- ✅ Add optional parameters with defaults
|
||||
- ✅ Add new properties with sensible defaults
|
||||
- ✅ Add new interfaces for new features
|
||||
- ✅ Add helper methods to existing classes
|
||||
- ✅ Mark deprecated methods with `[Obsolete]`
|
||||
- ✅ Run contract tests before release
|
||||
|
||||
**DON'T:**
|
||||
- ❌ Remove existing methods
|
||||
- ❌ Change method signatures
|
||||
- ❌ Rename properties
|
||||
- ❌ Change property types
|
||||
- ❌ Remove enum values
|
||||
- ❌ Break existing constructors
|
||||
|
||||
### For Adapter Developers
|
||||
|
||||
**DO:**
|
||||
- ✅ Depend only on interfaces, not implementations
|
||||
- ✅ Use factory patterns for object creation
|
||||
- ✅ Handle new optional properties gracefully
|
||||
- ✅ Catch and log unknown enum values
|
||||
- ✅ Version-check SDK at runtime if needed
|
||||
|
||||
**DON'T:**
|
||||
- ❌ Depend on internal implementation details
|
||||
- ❌ Assume fixed property counts
|
||||
- ❌ Hard-code enum values
|
||||
- ❌ Access private members via reflection
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions (IMMUTABLE)
|
||||
|
||||
These naming patterns are **contracts** and won't change:
|
||||
|
||||
### Interface Names
|
||||
```
|
||||
Pattern: I{Concept}
|
||||
Examples: IStrategy, IRiskManager, IPositionSizer, ILogger
|
||||
```
|
||||
|
||||
### Model Classes
|
||||
```
|
||||
Pattern: {Concept}{Type}
|
||||
Examples: BarData, TickData, StrategyIntent, StrategyContext
|
||||
```
|
||||
|
||||
### Enums
|
||||
```
|
||||
Pattern: {Concept}{Optional Suffix}
|
||||
Examples: OrderSide, OrderType, TickType, RiskLevel
|
||||
```
|
||||
|
||||
### Methods
|
||||
```
|
||||
Pattern: {Verb}{Noun}
|
||||
Examples: OnBar, OnTick, Initialize, ValidateOrder, CalculateSize
|
||||
```
|
||||
|
||||
### Properties
|
||||
```
|
||||
Pattern: {Noun} or {Adjective}{Noun}
|
||||
Examples: Symbol, Timestamp, CurrentPosition, DailyPnL
|
||||
```
|
||||
|
||||
**These patterns are STABLE and won't change.**
|
||||
|
||||
---
|
||||
|
||||
## Extension Points (For Future Growth)
|
||||
|
||||
### 1. Metadata Dictionaries
|
||||
```csharp
|
||||
public Dictionary<string, object> Metadata { get; set; }
|
||||
```
|
||||
**Use for**: Adding data without breaking compatibility
|
||||
|
||||
### 2. Optional Parameters
|
||||
```csharp
|
||||
public void Initialize(
|
||||
StrategyConfig config,
|
||||
IMarketDataProvider dataProvider,
|
||||
ILogger logger,
|
||||
Dictionary<string, object> options = null) // Extension point
|
||||
```
|
||||
|
||||
### 3. Interface Composition
|
||||
```csharp
|
||||
// Instead of changing IStrategy, create new interface
|
||||
public interface IAdvancedStrategy : IStrategy
|
||||
{
|
||||
void OnMarketDepth(MarketDepthData depth);
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Feature Flags
|
||||
```csharp
|
||||
public class StrategyMetadata
|
||||
{
|
||||
public Dictionary<string, bool> SupportedFeatures { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
**Adapters can check**: `if (metadata.SupportedFeatures["MultiTarget"]) { ... }`
|
||||
|
||||
---
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
### For Every Interface Change
|
||||
|
||||
**Must Document:**
|
||||
1. **What changed** (method/property added/removed/changed)
|
||||
2. **Why it changed** (business reason)
|
||||
3. **Version** it changed in
|
||||
4. **Migration path** for adapters
|
||||
5. **Deprecation timeline** (if applicable)
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## v1.1.0 - January 2026
|
||||
|
||||
### Added
|
||||
- `StrategyIntent.TargetTicksList` - Support for multiple profit targets
|
||||
- **Migration**: Not required. Old code using `TargetTicks` still works.
|
||||
- **New feature**: Strategies can now specify multiple targets.
|
||||
|
||||
### Deprecated
|
||||
- `IStrategy.OnBar()` - Deprecated in favor of `OnBarClose()`
|
||||
- **Reason**: Clearer naming for bar-close strategies
|
||||
- **Timeline**: Will be removed in v2.0.0 (12+ months)
|
||||
- **Migration**: Replace `OnBar` with `OnBarClose` (same signature)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Approval Process
|
||||
|
||||
### Before Releasing Interface Changes
|
||||
|
||||
**Required Reviews:**
|
||||
1. ✅ Technical review (breaking vs. non-breaking)
|
||||
2. ✅ Contract tests pass
|
||||
3. ✅ Documentation updated
|
||||
4. ✅ Migration guide written (if needed)
|
||||
5. ✅ Version number updated correctly
|
||||
|
||||
**For Breaking Changes:**
|
||||
1. ✅ All of the above, plus:
|
||||
2. ✅ Deprecation period completed (2+ minor versions)
|
||||
3. ✅ Adapter developers notified 30+ days in advance
|
||||
4. ✅ Migration tooling provided (if possible)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### The Contract
|
||||
|
||||
**SDK Core provides:**
|
||||
- Stable interfaces (`IStrategy`, `IRiskManager`, `IPositionSizer`)
|
||||
- Stable data models (`BarData`, `StrategyIntent`, `StrategyContext`)
|
||||
- Versioned API (semantic versioning)
|
||||
- Backward compatibility within MAJOR versions
|
||||
|
||||
**Adapters rely on:**
|
||||
- Interface contracts (not implementations)
|
||||
- Data model structures
|
||||
- Method signatures
|
||||
- Enum values
|
||||
|
||||
**The promise:**
|
||||
- SDK can evolve WITHOUT breaking adapters (within MAJOR version)
|
||||
- Adapters can evolve WITHOUT rewriting SDK
|
||||
- Clear versioning communicates compatibility
|
||||
- Deprecation gives time to migrate
|
||||
|
||||
---
|
||||
|
||||
## Action Items
|
||||
|
||||
### Immediate (Before Phase 1 Release)
|
||||
|
||||
- [ ] Review all public interfaces for stability
|
||||
- [ ] Add contract tests to CI/CD
|
||||
- [ ] Document current interface versions
|
||||
- [ ] Establish version numbering (start at 1.0.0)
|
||||
- [ ] Get team approval on this contract
|
||||
|
||||
### Ongoing
|
||||
|
||||
- [ ] Run contract tests on every build
|
||||
- [ ] Review all PR's for interface stability
|
||||
- [ ] Document changes in CHANGELOG.md
|
||||
- [ ] Notify adapter developers of deprecations
|
||||
- [ ] Maintain compatibility matrix
|
||||
|
||||
---
|
||||
|
||||
**Version History:**
|
||||
- v1.0 (2026-02-14): Initial draft
|
||||
- [Future versions will be listed here]
|
||||
|
||||
212
plans/nt8_sdk_analysis_report.md
Normal file
212
plans/nt8_sdk_analysis_report.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# NT8 SDK Analysis Report
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The NT8 Institutional SDK represents a well-structured, risk-first trading framework designed for NinjaTrader 8 integration. The codebase demonstrates a clear architectural separation of concerns with strong emphasis on risk management, position sizing, and deterministic behavior. The project has successfully completed Phase 0 and is positioned for Phase 1 development focused on NT8 integration.
|
||||
|
||||
## Current Configuration Analysis
|
||||
|
||||
### 1. Architecture Overview
|
||||
|
||||
#### Core Components
|
||||
- **NT8.Core**: Contains the fundamental building blocks including risk management, position sizing, and order management
|
||||
- **NT8.Adapters**: Houses NinjaTrader 8 integration adapters
|
||||
- **NT8.Strategies**: Placeholder for trading strategies (to be implemented in Phase 1)
|
||||
- **NT8.Contracts**: Data contracts layer (to be implemented in Phase 1)
|
||||
|
||||
#### Framework Configuration
|
||||
- **Target Framework**: .NET Framework 4.8 (compliant with NinjaTrader 8)
|
||||
- **Language Level**: C# 5.0 (maintaining compatibility with NT8)
|
||||
- **Build System**: MSBuild with Directory.Build.props ensuring consistent configuration
|
||||
- **Testing**: MSTest framework with >90% coverage for core components
|
||||
|
||||
### 2. Risk Management System
|
||||
|
||||
#### BasicRiskManager Implementation
|
||||
- Implements Tier 1 risk controls with thread-safe operations
|
||||
- Features:
|
||||
- Daily loss cap enforcement
|
||||
- Per-trade risk limiting
|
||||
- Position count limiting
|
||||
- Emergency flatten functionality
|
||||
- Risk level escalation (Low/Medium/High/Critical)
|
||||
- Uses locks for thread safety in state management
|
||||
- Comprehensive logging with correlation IDs
|
||||
|
||||
#### Risk Decision Pipeline
|
||||
```
|
||||
Strategy Intent → Risk Validation → Risk Decision → Position Sizing → Order Execution
|
||||
```
|
||||
|
||||
### 3. Position Sizing System
|
||||
|
||||
#### BasicPositionSizer Implementation
|
||||
- Supports two primary sizing methods:
|
||||
- Fixed contracts: Configurable number of contracts with min/max clamping
|
||||
- Fixed dollar risk: Calculates contracts based on risk parameters and stop distance
|
||||
- Includes conservative rounding (floor) for contract quantities
|
||||
- Multi-symbol support with accurate tick values
|
||||
- Configuration validation with detailed error reporting
|
||||
|
||||
### 4. Order Management System
|
||||
|
||||
#### IOrderManager Interface
|
||||
Comprehensive interface supporting:
|
||||
- Order submission, cancellation, and modification
|
||||
- Algorithmic execution (TWAP, VWAP, Iceberg)
|
||||
- Smart order routing
|
||||
- Risk integration
|
||||
- Performance metrics and monitoring
|
||||
|
||||
#### OrderManager Implementation
|
||||
- Fully featured OMS with:
|
||||
- Smart routing logic based on cost, speed, and reliability factors
|
||||
- Algorithmic execution capabilities
|
||||
- Execution venue management
|
||||
- Performance metrics collection
|
||||
- Proper state management with thread safety
|
||||
|
||||
### 5. Adapter Layer
|
||||
|
||||
#### NT8 Integration Architecture
|
||||
- **INT8Adapter**: Defines the interface for NT8 integration
|
||||
- **NT8Adapter**: Main implementation coordinating data, orders, and logging
|
||||
- **NT8OrderAdapter**: Handles order execution and updates
|
||||
- **NT8DataAdapter**: Manages data conversion between NT8 and SDK formats
|
||||
- **NT8LoggingAdapter**: Provides logging services
|
||||
|
||||
## Strengths of Current Implementation
|
||||
|
||||
### 1. Architectural Excellence
|
||||
- **Risk-First Design**: All trading activity flows through risk validation
|
||||
- **Thin Strategy Pattern**: Strategies focus solely on signal generation
|
||||
- **Separation of Concerns**: Clear boundaries between risk, sizing, and execution
|
||||
- **Interface-Based Architecture**: Enables extensibility and testability
|
||||
|
||||
### 2. Robust Risk Controls
|
||||
- **Multiple Risk Tiers**: Tier 1 controls implemented with framework for higher tiers
|
||||
- **Thread Safety**: Proper locking mechanisms protect shared state
|
||||
- **Comprehensive Validation**: Multiple layers of risk checks
|
||||
- **Emergency Procedures**: Built-in flatten functionality
|
||||
|
||||
### 3. Compatibility Focus
|
||||
- **NT8 Compliance**: Strict adherence to .NET Framework 4.8 and C# 5.0
|
||||
- **Backward Compatibility**: Avoids modern C# features incompatible with NT8
|
||||
- **Build Verification**: Comprehensive build validation script
|
||||
|
||||
### 4. Observability
|
||||
- **Structured Logging**: Consistent logging across components
|
||||
- **Performance Metrics**: Detailed metrics collection
|
||||
- **Monitoring Capabilities**: Health checks and status reporting
|
||||
|
||||
## Weaknesses and Areas for Improvement
|
||||
|
||||
### 1. State Management in OMS
|
||||
- **Immutable Metrics**: OmsMetrics class has read-only properties, making metric updates difficult
|
||||
- **Limited State Persistence**: No clear mechanism for persisting state across sessions
|
||||
|
||||
### 2. Configuration Management
|
||||
- **Hardcoded Values**: Some values (e.g., daily loss limits in BasicRiskManager) are hardcoded
|
||||
- **Limited Flexibility**: Configuration parameters could be more dynamic
|
||||
|
||||
### 3. Error Handling
|
||||
- **Generic Exceptions**: Some areas could benefit from more specific exception types
|
||||
- **Retry Logic**: Limited automatic retry mechanisms for transient failures
|
||||
|
||||
## Recommendations for Next Steps (Phase 1)
|
||||
|
||||
### 1. NinjaTrader 8 Integration (Priority: High)
|
||||
- **Complete NT8 Adapter Implementation**:
|
||||
- Implement actual order execution methods (EnterLong, EnterShort, SetStopLoss, etc.)
|
||||
- Integrate with NT8's market data feeds
|
||||
- Connect order update and execution handlers
|
||||
|
||||
- **Data Provider Implementation**:
|
||||
- Create concrete implementation of IMarketDataProvider
|
||||
- Integrate with NT8's historical and real-time data systems
|
||||
- Implement data quality validation
|
||||
|
||||
### 2. Enhanced Risk Controls (Priority: High)
|
||||
- **Tier 2 Implementation**:
|
||||
- Add per-symbol risk limits
|
||||
- Implement correlation risk controls
|
||||
- Add sector/group risk management
|
||||
- Add VaR and CVaR calculations
|
||||
|
||||
- **Risk Configuration Enhancement**:
|
||||
- Make risk limits configurable rather than hardcoded
|
||||
- Implement dynamic risk adjustment based on market conditions
|
||||
|
||||
### 3. Order Management Improvements (Priority: Medium)
|
||||
- **Advanced Algorithms**:
|
||||
- Complete TWAP algorithm with volume profile integration
|
||||
- Implement VWAP with proper volume-weighted calculations
|
||||
- Enhance Iceberg with randomized visibility
|
||||
|
||||
- **Smart Routing Enhancement**:
|
||||
- Integrate with real execution venues
|
||||
- Implement real-time venue performance tracking
|
||||
- Add latency and cost optimization
|
||||
|
||||
### 4. Performance Optimization (Priority: Medium)
|
||||
- **Memory Management**:
|
||||
- Optimize allocation patterns in hot paths
|
||||
- Implement object pooling for frequently created objects
|
||||
- Reduce garbage collection pressure
|
||||
|
||||
- **Execution Speed**:
|
||||
- Optimize critical paths in risk validation
|
||||
- Implement caching for frequently accessed data
|
||||
- Profile and optimize algorithmic execution
|
||||
|
||||
### 5. Testing and Validation (Priority: High)
|
||||
- **Integration Testing**:
|
||||
- Develop comprehensive integration tests with NT8
|
||||
- Create realistic market data simulation
|
||||
- Test edge cases and error conditions
|
||||
|
||||
- **Performance Testing**:
|
||||
- Load testing for high-frequency scenarios
|
||||
- Stress testing under adverse conditions
|
||||
- Latency measurement and optimization
|
||||
|
||||
### 6. Documentation and Examples (Priority: Medium)
|
||||
- **Developer Documentation**:
|
||||
- API documentation for all public interfaces
|
||||
- Integration guides for NT8
|
||||
- Best practices and patterns
|
||||
|
||||
- **Example Strategies**:
|
||||
- Implement sample strategies demonstrating SDK usage
|
||||
- Create educational examples for different trading styles
|
||||
- Provide templates for common strategy patterns
|
||||
|
||||
## Technical Debt Items for Future Resolution
|
||||
|
||||
### 1. OMS Metrics Immutability
|
||||
- Issue: OmsMetrics properties are read-only, preventing updates
|
||||
- Solution: Either add setters or implement a mutable wrapper
|
||||
|
||||
### 2. Configuration Centralization
|
||||
- Issue: Configuration scattered across multiple classes
|
||||
- Solution: Create centralized configuration management system
|
||||
|
||||
### 3. Logging Enhancement
|
||||
- Issue: Basic logging implementation
|
||||
- Solution: Implement more sophisticated structured logging with correlation IDs
|
||||
|
||||
## Conclusion
|
||||
|
||||
The NT8 SDK demonstrates a mature, well-designed architecture with strong risk management foundations. The project is well-positioned for Phase 1 development with its clear separation of concerns, compatibility focus, and robust testing approach. The main focus for the next phase should be completing the NinjaTrader 8 integration while enhancing risk controls and algorithmic execution capabilities.
|
||||
|
||||
The architecture provides a solid foundation for institutional trading with its emphasis on risk management, determinism, and observability. With proper execution of the Phase 1 roadmap, this SDK will provide a powerful platform for institutional algorithmic trading within the NinjaTrader 8 ecosystem.
|
||||
|
||||
## Immediate Action Items
|
||||
|
||||
1. **Begin NT8 Adapter Implementation**: Start with core order execution functionality
|
||||
2. **Enhance Risk Configuration**: Replace hardcoded values with configurable parameters
|
||||
3. **Develop Integration Tests**: Create comprehensive test suite for NT8 integration
|
||||
4. **Profile Performance**: Identify bottlenecks in critical paths
|
||||
5. **Document API**: Create comprehensive documentation for SDK interfaces
|
||||
|
||||
This analysis confirms the codebase is in excellent shape to proceed with Phase 1 development focused on NinjaTrader 8 integration.
|
||||
42
setup-kilocode-files.ps1
Normal file
42
setup-kilocode-files.ps1
Normal file
@@ -0,0 +1,42 @@
|
||||
# Kilocode Configuration Setup Script
|
||||
# Auto-generated for NT8 SDK
|
||||
|
||||
Write-Host "=== Copying Kilocode Configuration Files ===" -ForegroundColor Cyan
|
||||
|
||||
# Array of files to copy: source, destination
|
||||
$files = @(
|
||||
@{src="/tmp/coding_patterns.md"; dest="C:\dev\nt8-sdk\.kilocode\rules\coding_patterns.md"},
|
||||
@{src="/tmp/verification_requirements.md"; dest="C:\dev\nt8-sdk\.kilocode\rules\verification_requirements.md"},
|
||||
@{src="/tmp/project_context.md"; dest="C:\dev\nt8-sdk\.kilocode\rules\project_context.md"},
|
||||
@{src="/tmp/settings.json"; dest="C:\dev\nt8-sdk\.vscode\settings.json"},
|
||||
@{src="/tmp/tasks.json"; dest="C:\dev\nt8-sdk\.vscode\tasks.json"},
|
||||
@{src="/tmp/.editorconfig"; dest="C:\dev\nt8-sdk\.editorconfig"}
|
||||
)
|
||||
|
||||
$success = 0
|
||||
$failed = 0
|
||||
|
||||
foreach ($file in $files) {
|
||||
try {
|
||||
Copy-Item -Path $file.src -Destination $file.dest -Force
|
||||
Write-Host " ✓ Copied: $($file.dest)" -ForegroundColor Green
|
||||
$success++
|
||||
} catch {
|
||||
Write-Host " ✗ Failed: $($file.dest)" -ForegroundColor Red
|
||||
Write-Host " Error: $_" -ForegroundColor Red
|
||||
$failed++
|
||||
}
|
||||
}
|
||||
|
||||
Write-Host "`n=== Summary ===" -ForegroundColor Cyan
|
||||
Write-Host " Success: $success" -ForegroundColor Green
|
||||
Write-Host " Failed: $failed" -ForegroundColor $(if ($failed -eq 0) { "Green" } else { "Red" })
|
||||
|
||||
if ($failed -eq 0) {
|
||||
Write-Host "`n✓ All files copied successfully!" -ForegroundColor Green
|
||||
Write-Host "`nNext steps:" -ForegroundColor Cyan
|
||||
Write-Host "1. Restart VS Code"
|
||||
Write-Host "2. Open Kilocode panel"
|
||||
Write-Host "3. Click law icon (⚖️) to verify 5 rules loaded"
|
||||
Write-Host "4. Press Ctrl+Shift+B to test verify-build task"
|
||||
}
|
||||
Reference in New Issue
Block a user