AI Agents for Development¶

The ProjectX Python SDK leverages specialized AI agents for development tasks. This guide explains how to work with these agents effectively for SDK development, maintenance, and enhancement.

Agent Overview¶

The project uses multiple specialized AI agents, each optimized for specific development tasks:

python-developer: Core SDK development and feature implementation
code-standards-enforcer: Code quality, standards compliance, and IDE diagnostics
code-refactor: Architecture improvements and code modernization
code-documenter: Documentation creation and maintenance
code-debugger: Issue diagnosis and troubleshooting
code-reviewer: Code review and quality assurance

Agent Selection Guidelines¶

When to Use Each Agent¶

python-developer¶

Best for: Core SDK development and feature implementation

Use when: - Implementing new trading components (OrderManager, PositionManager, etc.) - Creating financial indicators with Polars DataFrames - Building real-time data processing and WebSocket connections - Developing new TradingSuite features - Ensuring 100% async architecture compliance - Handling Decimal price precision requirements

Example scenarios:

"Implement a new technical indicator for options flow analysis"
"Add WebSocket reconnection logic with exponential backoff"
"Create async order placement methods with bracket order support"
"Build a new risk management component with portfolio-level controls"

code-standards-enforcer¶

Best for: Maintaining code quality and standards

CRITICAL: Always check IDE diagnostics first with mcp__ide__getDiagnostics

Use when: - Before committing any changes (proactive quality control) - Preparing for pull requests - Release validation processes - Verifying 100% async architecture compliance - Checking TradingSuite patterns adherence - Ensuring Polars-only DataFrame usage - Validating deprecation compliance - Type safety verification with TypedDict/Protocol

Workflow: 1. First: Check mcp__ide__getDiagnostics for modified files 2. Fix any IDE diagnostic errors/warnings 3. Then: Run traditional linting tools (ruff, mypy) 4. Verify with IDE diagnostics again after fixes

Example scenarios:

"Check code quality before committing new indicator implementation"
"Validate async patterns in the new order management system"
"Ensure type safety compliance across all modified files"
"Verify deprecation warnings are properly implemented"

code-refactor¶

Best for: Architecture improvements and modernization

Use when: - Migrating to TradingSuite patterns - Optimizing Polars DataFrame operations - Consolidating WebSocket handling - Modernizing async patterns and removing legacy sync code - Transitioning from monolithic to modular architectures - Optimizing event system performance - Implementing memory management improvements

Example scenarios:

"Refactor OrderManager to use EventBus for better decoupling"
"Optimize DataFrame operations in indicators for better performance"
"Migrate legacy synchronous code to modern async patterns"
"Consolidate WebSocket connections for improved resource usage"

code-documenter¶

Best for: Documentation creation and maintenance

Use when: - Documenting new TradingSuite APIs and features - Writing indicator function documentation with usage examples - Explaining WebSocket events and data flow patterns - Creating migration guides for breaking changes - Maintaining README files and examples directory - Writing deprecation notices with clear upgrade paths - Updating docstrings with comprehensive type hints - Creating tutorial notebooks and interactive examples

Example scenarios:

"Document the new risk management system with usage examples"
"Create migration guide for v3 to v4 breaking changes"
"Update API documentation for the enhanced order management system"
"Write comprehensive examples for the new indicator framework"

code-debugger¶

Best for: Issue diagnosis and troubleshooting

Use when: - Investigating WebSocket disconnection issues - Diagnosing order lifecycle failures - Troubleshooting real-time data gaps - Resolving event system deadlocks - Fixing price precision errors - Identifying memory leaks and performance bottlenecks - Debugging AsyncIO-related issues - Tracing SignalR connection problems

Example scenarios:

"Debug why orders aren't filling after placement"
"Investigate WebSocket reconnection failures under load"
"Trace event propagation issues in the real-time system"
"Diagnose memory leaks in long-running data streams"

code-reviewer¶

Best for: Code review and quality assurance

Use when: - Reviewing async patterns and implementations - Checking real-time performance characteristics - Validating financial data integrity and precision - Ensuring API stability and backward compatibility - Conducting pre-release code reviews - Reviewing pull requests for quality and standards

Example scenarios:

"Review the new bracket order implementation for correctness"
"Check real-time data processing for performance issues"
"Validate the new indicator calculations for accuracy"
"Review API changes for backward compatibility"

Agent Command Requirements¶

Essential Commands for All Agents¶

File Operations: - Read, Write, Edit, MultiEdit for file manipulation - Glob, Grep for code searching and analysis - LS for directory exploration

Version Control: - git status, git diff, git add for change management - git log for commit history analysis

Testing: - ./test.sh [script] - Always use this for running tests and examples - Never use uv run python directly - test.sh handles environment variables

Agent-Specific Commands¶

python-developer¶

# Development commands
uv add [package]              # Add new dependencies
uv run pytest tests/         # Run test suite
./test.sh examples/*.py       # Test example scripts
uv run mypy src/             # Type checking

# Example workflow
./test.sh examples/01_basic_client_connection.py
uv run pytest tests/test_new_feature.py -v

code-standards-enforcer¶

# CRITICAL: Always check IDE diagnostics first
mcp__ide__getDiagnostics     # Check IDE errors/warnings

# Traditional linting (after IDE check)
uv run ruff check .          # Lint code
uv run ruff format .         # Format code
uv run mypy src/             # Type checking
uv run pytest --cov         # Coverage analysis

# Example workflow
1. mcp__ide__getDiagnostics  # Always first
2. Fix any IDE issues
3. uv run ruff check . --fix
4. uv run mypy src/
5. mcp__ide__getDiagnostics  # Verify fixes

code-debugger¶

# Debugging commands
./test.sh --debug [script]   # Run with debug output
grep -r "error\|exception" src/  # Search for error patterns
uv run pytest -v -s --tb=long    # Verbose test output

# Performance profiling
uv run python -m cProfile script.py

MCP Server Integration¶

Essential MCP Servers for All Agents¶

Core Development: - mcp__smithery-ai-filesystem - File operations and management - mcp__aakarsh-sasi-memory-bank-mcp - Progress tracking and context - mcp__mcp-obsidian - Development planning and documentation

Agent-Specific MCP Servers¶

python-developer¶

mcp__project-x-py_Docs - Search existing documentation and patterns
mcp__upstash-context-7-mcp - Get library documentation for dependencies
mcp__waldzellai-clear-thought - Complex problem solving and architecture
mcp__itseasy-21-mcp-knowledge-graph - Map component relationships

Example usage:

# Search for existing patterns
await mcp__project_x_py_Docs__search_project_x_py_code(
    query="async def place_bracket_order"
)

# Track implementation progress
await mcp__aakarsh_sasi_memory_bank_mcp__track_progress(
    action="Implemented async bracket order system",
    description="Added OCO support with automatic stop/target placement"
)

code-standards-enforcer¶

mcp__ide__getDiagnostics - CRITICAL: Check IDE diagnostics first
mcp__project-x-py_Docs - Verify code against documentation standards

Example workflow:

# ALWAYS start with IDE diagnostics
ide_issues = await mcp__ide__getDiagnostics()

# Fix issues found by IDE
if ide_issues:
    # Fix each issue systematically
    pass

# Then run traditional tools
# uv run ruff check . --fix
# uv run mypy src/

code-refactor¶

mcp__waldzellai-clear-thought - Plan refactoring strategies
mcp__itseasy-21-mcp-knowledge-graph - Understand component dependencies
mcp__aakarsh-sasi-memory-bank-mcp - Log architectural decisions

code-documenter¶

mcp__mcp-obsidian - Create comprehensive documentation
mcp__project-x-py_Docs - Reference existing patterns
mcp__tavily-mcp - Research external API documentation

code-debugger¶

mcp__waldzellai-clear-thought - Systematic issue analysis
mcp__itseasy-21-mcp-knowledge-graph - Trace data flow and dependencies
mcp__ide__getDiagnostics - Get real-time error diagnostics

Multi-Agent Workflows¶

Feature Development Workflow¶

sequenceDiagram
    participant Dev as Developer
    participant PD as python-developer
    participant CSE as code-standards-enforcer
    participant CD as code-documenter
    participant CR as code-reviewer

    Dev->>PD: Implement new feature
    PD->>PD: Write code with tests
    PD->>CSE: Check standards compliance
    CSE->>CSE: Run IDE diagnostics
    CSE->>CSE: Fix issues found
    CSE->>CD: Create documentation
    CD->>CD: Write docs and examples
    CD->>CR: Review implementation
    CR->>CR: Final quality check
    CR->>Dev: Ready for commit

Example Implementation¶

When implementing a new feature, use agents in sequence:

python-developer: Core implementation

"Implement a new volatility-adjusted position sizing algorithm that:
- Uses ATR for volatility measurement
- Integrates with the existing RiskManager
- Supports both fixed and percentage-based risk models
- Includes comprehensive async tests"

code-standards-enforcer: Quality validation

"Review the new position sizing implementation for:
- Check IDE diagnostics for any errors
- Async pattern compliance
- Type safety with proper protocols
- Code formatting and style
- Test coverage requirements"

code-documenter: Documentation creation

"Document the new volatility-adjusted position sizing feature:
- API reference with comprehensive docstrings
- Usage examples with MNQ futures
- Integration guide for existing strategies
- Migration notes if any breaking changes"

code-reviewer: Final validation

"Perform final review of the position sizing feature:
- Code quality and maintainability
- Performance implications
- API design consistency
- Test coverage and quality"

Best Practices for Agent Usage¶

Agent Selection¶

Be Specific: Choose the most appropriate agent for the task
Use Proactively: Don't wait for explicit requests - choose the right agent
Combine When Needed: Use multiple agents for complex tasks
Parallel Execution: Run independent tasks concurrently when possible

Communication with Agents¶

Provide Context: Include relevant project information
Be Specific: Clear, detailed requirements
Reference Standards: Mention SDK-specific patterns and requirements
Include Examples: Show desired patterns or outcomes

Quality Assurance¶

IDE Diagnostics First: Always check mcp__ide__getDiagnostics before traditional tools
Test Everything: Use ./test.sh for all testing
Validate Changes: Ensure changes don't break existing functionality
Document Impact: Track architectural decisions and changes

Agent Coordination Patterns¶

Sequential Pattern¶

python-developer  code-standards-enforcer  code-documenter  code-reviewer

Use for: New feature development

Parallel Pattern¶

python-developer + code-refactor (simultaneously)

code-standards-enforcer

code-documenter + code-reviewer (simultaneously)

Use for: Large refactoring projects

Iterative Pattern¶

python-developer  code-debugger  code-standards-enforcer

code-documenter  code-reviewer

Use for: Complex bug fixes or performance optimizations

Common Agent Workflows¶

New Feature Development¶

python-developer: Implement core functionality
code-standards-enforcer: Validate standards and run diagnostics
code-documenter: Create documentation and examples
code-reviewer: Final quality review

Bug Investigation¶

code-debugger: Diagnose and isolate issue
python-developer: Implement fix
code-standards-enforcer: Validate fix quality
code-reviewer: Ensure fix doesn't introduce regressions

Architecture Improvement¶

code-refactor: Plan and execute refactoring
code-standards-enforcer: Ensure compliance with standards
code-documenter: Update affected documentation
code-reviewer: Validate architectural improvements

Integration with Development Tools¶

IDE Integration¶

Agents work with VS Code diagnostics via mcp__ide__getDiagnostics
Real-time error detection and fixing
Type checking integration with mypy

CI/CD Integration¶

Agents can be used in GitHub Actions workflows
Automated code quality checks
Documentation generation and validation

Project Management¶

Progress tracking via Memory Bank MCP
Architectural decision logging in Obsidian
Knowledge graph maintenance for component relationships

By leveraging these AI agents effectively, you can maintain high code quality, comprehensive documentation, and robust architecture while developing the ProjectX Python SDK efficiently.