nt8-sdk/AI_TEAM_SETUP_DOCUMENTATION.md

NT8 SDK - AI Team Configuration and Setup Documentation

Overview

This document provides the complete setup and configuration guide for managing AI development teams working on the NT8 Institutional SDK. It covers the technical requirements, repository structure, and governance mechanisms established to ensure .NET Framework 4.8 compatibility and institutional-grade code quality.

Project Background

Business Context

• Objective: Build institutional trading SDK for NinjaTrader 8 integration
• Architecture: Risk-first design with thin strategy plugins
• Critical Requirement: Must maintain .NET Framework 4.8 compatibility for NT8
• Quality Standard: Zero-tolerance for compilation errors, institutional-grade risk management

Technical Challenge Solved

• Problem: AI team initially built with .NET Core 9 and modern C# features
• Impact: Incompatible with NinjaTrader 8's .NET Framework 4.8 requirement
• Solution: Complete framework conversion with comprehensive AI guardrails
• Result: Working build with enforced compatibility standards

Repository Structure and Location

Repository Path

C:\dev\nt8-sdk\

Key Directory Structure

nt8-sdk/
├── src/
│   ├── NT8.Core/                    # Core framework (risk, sizing, logging)
│   ├── NT8.Adapters/                # NT8 integration layer
│   ├── NT8.Strategies/              # Strategy implementations  
│   └── NT8.Contracts/               # Data transfer objects
├── tests/
│   ├── NT8.Core.Tests/              # Unit tests (MSTest)
│   ├── NT8.Integration.Tests/       # Integration tests
│   └── NT8.Performance.Tests/       # Performance tests
├── docs/                            # Documentation
└── [AI Configuration Files]        # See below

AI Team Configuration Files

1. Core Guidelines (MUST READ)

File	Purpose	Priority
AI_DEVELOPMENT_GUIDELINES.md	Core compatibility requirements, forbidden features	CRITICAL
CODE_STYLE_GUIDE.md	Required C# 5.0 patterns and examples	CRITICAL
CODE_REVIEW_CHECKLIST.md	Pre-commit verification checklist	CRITICAL
.aiconfig	AI agent workflow and configuration	HIGH

2. Build and Quality Control

File	Purpose	Usage
verify-build.bat	Complete build verification script	Run before every commit
.editorconfig	Code formatting and style rules	Automatic enforcement
Directory.Build.props	MSBuild configuration for all projects	Framework targeting

3. Documentation

File	Purpose	Audience
README.md	Project overview and quick start	All developers
NET_FRAMEWORK_CONVERSION.md	Background on compatibility changes	Context for decisions
CODE_REVIEW_CHECKLIST.md	Quality assurance process	Reviewers and AI agents

Critical Technical Requirements

Framework and Language Constraints

<!-- ALL projects must use this configuration -->
<PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <LangVersion>5.0</LangVersion>
    <Nullable>disable</Nullable>
</PropertyGroup>

Forbidden Technologies and Features

Language Features (C# 6+ - Will Not Compile)

• ❌ record types → Use class with constructors
• ❌ Nullable reference types (string?) → Use string
• ❌ String interpolation ($"...") → Use String.Format()
• ❌ Dictionary initializers (new Dict { ["key"] = value }) → Use .Add()
• ❌ Pattern matching → Use switch or if/else
• ❌ Auto-property initializers → Initialize in constructor

Package Dependencies

• ❌ Microsoft.Extensions.* packages → Use custom implementations
• ❌ System.Text.Json → Use Newtonsoft.Json
• ❌ xUnit/NUnit → Use MSTest only
• ❌ .NET Core packages → Use .NET Framework compatible only

Required Patterns (C# 5.0 Compatible)

Class Definition

public class ClassName
{
    private readonly ILogger _logger;
    
    public string PropertyName { get; set; }
    
    public ClassName(ILogger logger, string property)
    {
        if (logger == null) throw new ArgumentNullException("logger");
        _logger = logger;
        PropertyName = property;
    }
}

Dictionary Initialization

// ✅ Correct C# 5.0 syntax
var metrics = new Dictionary<string, object>();
metrics.Add("trade_risk", riskAmount);
metrics.Add("daily_pnl", dailyPnL);

String Formatting

// ✅ Correct C# 5.0 syntax
_logger.LogDebug("Order approved: {0} {1} risk=${2:F2}", 
    intent.Symbol, intent.Side, tradeRisk);

Development Workflow for AI Teams

Pre-Development Setup

1. Repository Access: Ensure team has access to C:\dev\nt8-sdk
2. Baseline Verification: Run .\verify-build.bat - must pass
3. Documentation Review: Team must read all CRITICAL priority files
4. Pattern Familiarization: Review existing code in src/NT8.Core/

Development Process

Before Starting Any Task

# 1. Verify baseline build
cd C:\dev\nt8-sdk
.\verify-build.bat

# 2. Review guidelines for the specific module
# 3. Check existing patterns in relevant source files

During Development

• Follow patterns in CODE_STYLE_GUIDE.md exactly
• Use only C# 5.0 compatible syntax
• Maintain risk-first architecture (all trades through IRiskManager)
• Add unit tests for new functionality using MSTest

Before Committing

# MANDATORY verification
.\verify-build.bat

Must output: ✅ All checks passed!

Quality Gates (Zero Tolerance)

Every commit must pass ALL of these:

1. ✅ Compilation with zero errors
2. ✅ Zero build warnings
3. ✅ All tests passing
4. ✅ C# 5.0 syntax compliance
5. ✅ Architecture compliance (risk-first)
6. ✅ Code style compliance

Architecture Governance

Risk-First Design (Non-Negotiable)

All trading logic must follow this pattern:

// 1. Strategy generates intent
var intent = strategy.OnBar(bar, context);

// 2. Risk validation (MANDATORY)
var riskDecision = riskManager.ValidateOrder(intent, context, config);
if (!riskDecision.Allow)
{
    // Trade rejected - log and stop
    return;
}

// 3. Position sizing
var sizingResult = positionSizer.CalculateSize(intent, context, config);

// 4. Order execution (Phase 1)
// Will be implemented in NT8 adapters

Thin Strategy Pattern

Strategies must only:

• Generate trading signals (StrategyIntent)
• Implement IStrategy interface
• NOT access markets directly
• NOT implement risk management
• NOT handle position sizing

Phase Management

Current Phase: Phase 1

Focus Areas (ONLY implement these):

• NT8 adapter implementations
• Market data provider integration
• Order management system
• Enhanced risk controls (Tier 2 only)

DO NOT Implement:

• Features from Phases 2-6
• UI components
• Advanced analytics
• Performance optimizations (until Phase 3)
• Confluence scoring (Phase 4)

Phase Boundaries

Each phase has specific deliverables and constraints. AI teams must stay within current phase scope to avoid architecture drift and maintain project timeline.

Error Prevention and Troubleshooting

Common Build Failures

Error Type	Cause	Solution
CS8026: Feature not available in C# 5	Used modern C# syntax	Check CODE_STYLE_GUIDE.md for correct pattern
CS0246: Type not found	Used incompatible package	Use .NET Framework compatible alternatives
Build warnings	Various style issues	Review .editorconfig and existing patterns

Verification Script Failures

If .\verify-build.bat fails:

1. Read error messages carefully
2. Check against CODE_REVIEW_CHECKLIST.md
3. Review recent changes for C# 6+ features
4. Compare against working code patterns

Architecture Violations

Common violations and fixes:

• Direct market access: Route through SDK framework
• Risk bypass: Ensure all trades go through IRiskManager
• Complex inheritance: Use composition and interfaces
• Framework incompatibility: Use only .NET Framework 4.8 features

Team Management Guidelines

Onboarding New AI Agents

1. Documentation Review: Complete read of all CRITICAL files
2. Pattern Training: Review existing implementations in src/NT8.Core/
3. Verification Practice: Run build script multiple times
4. Test Implementation: Create simple test class following MSTest patterns

Code Review Process

For Human Reviewers

1. Run .\verify-build.bat first
2. Use CODE_REVIEW_CHECKLIST.md systematically
3. Verify phase compliance (no future features)
4. Check architecture compliance (risk-first)

For AI Agents (Self-Review)

1. Complete CODE_REVIEW_CHECKLIST.md before submission
2. Verify against AI_DEVELOPMENT_GUIDELINES.md
3. Confirm build verification passes
4. Review code against existing patterns

Performance Monitoring

Track these metrics for AI team effectiveness:

• Build Success Rate: Should be >95% after onboarding
• Compliance Rate: C# 5.0 syntax violations should be <5%
• Architecture Adherence: Risk-first pattern compliance should be 100%
• Phase Boundary Respect: Zero implementations of future phase features

Maintenance and Updates

Regular Maintenance Tasks

• Weekly: Run .\verify-build.bat on clean checkout
• Monthly: Review AI team compliance metrics
• Per Phase: Update phase-specific guidelines as needed

Updating AI Guidelines

When making changes to AI configuration:

1. Update relevant documentation files
2. Test with AI team on non-critical changes
3. Verify build compatibility
4. Communicate changes clearly

Backup and Recovery

• Repository should be backed up regularly
• All configuration files are version controlled
• Build verification script provides quick health check

Success Metrics

Technical Metrics

• Build Success Rate: >98%
• Compilation Time: <30 seconds for full solution
• Test Pass Rate: 100%
• Warning Count: 0

Quality Metrics

• Code Coverage: >80% for core components
• Architecture Compliance: 100% (all trades through risk management)
• Framework Compatibility: 100% (.NET Framework 4.8)
• Phase Compliance: 100% (no future features implemented)

Conclusion

This configuration provides comprehensive governance for AI development teams working on the NT8 SDK. The combination of technical constraints, clear guidelines, automated verification, and human oversight ensures high-quality, compatible code that meets institutional trading requirements.

The setup balances AI team autonomy with necessary constraints, providing clear patterns to follow while preventing common compatibility pitfalls. Regular verification and monitoring ensure ongoing compliance with critical requirements.

---

Document Version: 1.0
Last Updated: Current implementation
Next Review: After Phase 1 completion
Owner: NT8 SDK Project Team