# 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
```xml
<!-- 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
```csharp
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
```csharp
// ✅ Correct C# 5.0 syntax
var metrics = new Dictionary<string, object>();
metrics.Add("trade_risk", riskAmount);
metrics.Add("daily_pnl", dailyPnL);
```

#### String Formatting
```csharp
// ✅ 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
```bash
# 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
```bash
# 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:
```csharp
// 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