Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (70 loc) · 5.05 KB

AGENTS.md

File metadata and controls

81 lines (70 loc) · 5.05 KB

AGENTS.md - Team Registry

Active Team Members

Agent Role Responsibility Data Ownership (Folders/Files)
Data Engineer Builds and maintains all external API integrations (NBA API, The Odds API) and SQLite database operations /data/ (nba_client.py, odds_client.py, storage.py)
Quantitative Modeler Implements statistical distributions (CMP, Bayesian Bivariate, Logistic+Poisson) for player prop projections /models/ (distributions.py, projections.py)
Logic Architect Develops adjustment algorithms (pace, defensive efficiency), usage reallocation, and ensemble edge scoring /logic/ (usage_realloc.py, adjustments.py, ensemble.py)
Test Engineer Writes unit, integration, and property-based tests; validates statistical model accuracy /tests/ (test_models.py, test_logic.py, test_data.py)
Integration Specialist Orchestrates main.py CLI, handles configuration, manages agent coordination, and produces final output /main.py, /config.py, /utils/ (garbage_time.py, formatting.py)

Rules of Engagement

Global Rules

  1. No Direct Cross-Writes: An agent should NEVER modify files outside their owned directories without explicit coordination via WHITEBOARD.md
  2. Interface Contracts: When one agent needs data from another, they must use documented function signatures (public API) rather than reading private implementation details
  3. Test-First for Models: The Quantitative Modeler must validate each distribution function with the Test Engineer before merging
  4. API Key Security: Only the Data Engineer and Integration Specialist may reference .env variables; never hardcode or log API keys
  5. Database Migrations: Any schema changes initiated by the Data Engineer must be approved by the Test Engineer to ensure test fixtures remain valid

Dependency Flow

┌─────────────────┐
│ Integration     │ ◄── Orchestrator (main.py)
│ Specialist      │
└────────┬────────┘
         │ calls
         ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Data Engineer   │────►│ Quantitative    │────►│ Logic Architect │
│ (API/DB)        │     │ Modeler         │     │ (Adjustments)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                      │                       │
         └──────────────────────┴───────────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │ Test Engineer   │
                        │ (Validation)    │
                        └─────────────────┘

Coordination Protocol

  • Before Starting: Check WHITEBOARD.md for blockers, in-progress tasks, and priority notes
  • After Completing: Update WHITEBOARD.md with completion status, any errors encountered, and dependencies for next agent
  • Code Reviews: The Test Engineer must approve all code from Data Engineer, Quantitative Modeler, and Logic Architect before Integration Specialist can incorporate

Naming Conventions (Project-Wide)

Type Convention Example
Files snake_case.py usage_realloc.py
Classes PascalCase ProjectionEngine
Functions snake_case calculate_edge_score()
Variables snake_case projected_points
Constants UPPER_SNAKE_CASE DEFAULT_PACE_FACTOR
SQL Tables snake_case (plural) projections, players

Feature Flags (MVP Scope)

Feature Status Responsible Agent
Fetch Today's Games ✅ P0 (Required) Data Engineer
Play-by-Play Data Extraction ✅ P0 (Required) Data Engineer
Market Odds Retrieval ✅ P0 (Required) Data Engineer
Bottom-Up Projections ✅ P0 (Required) Quantitative Modeler
Usage Reallocation ⚠️ P1 (Core+) Logic Architect
Pace & Defensive Adjustments ⚠️ P1 (Core+) Logic Architect
Edge Score Calculation ⚠️ P1 (Core+) Logic Architect
Historical Tracking ⚠️ P1 (Core+) Data Engineer
Garbage Time Filtering 🔹 P2 (Nice-to-have) Integration Specialist
CLI Output Formatting ✅ P0 (Required) Integration Specialist

Communication Channels

  • Progress Updates: WHITEBOARD.md - Agent Status section
  • Blockers/Errors: WHITEBOARD.md - Issues & Blockers section
  • Architecture Decisions: BLUEPRINT.md - read-only for agents
  • Requirements Reference: APPREQS.md, ALGOBUILD.md - read-only for agents