reactive-agents: Instructions file for Codex

AGENTS.md

This file provides guidance to AI Agents when working with code in this repository.

Quick Start Checklist

Before running ANY command in this repository:

• ✅ Use poetry run <command> OR enter poetry shell first
• ❌ NEVER manually activate: source .venv/bin/activate
• ❌ NEVER run Python/pytest directly without poetry run
• ✅ Virtual environment is at .venv/ (managed by Poetry)
• ✅ Check you're in project root: /home/tylerbuell/Documents/AIProjects/reactive-agents

Example correct commands:

poetry run pytest                           # ✅ Correct
poetry run python playground/runner.py      # ✅ Correct

poetry shell                                # ✅ Enters poetry environment
pytest                                      # ✅ Now correct (inside shell)
python playground/runner.py                 # ✅ Now correct (inside shell)

Example WRONG commands:

pytest                                      # ❌ Not in poetry environment
python playground/runner.py                 # ❌ Will fail with import errors
source .venv/bin/activate                   # ❌ Don't manually activate

Development Commands

Virtual Environment Setup

IMPORTANT: This project uses Poetry for dependency management.

The virtual environment is located at .venv/ in the project root.

# DO NOT manually activate the virtual environment
# Poetry handles this automatically with 'poetry run'

# WRONG - Don't do this:
source .venv/bin/activate
python script.py

# CORRECT - Use poetry run:
poetry run python script.py
poetry run pytest

# To run multiple commands in the poetry environment:
poetry shell  # Opens a new shell with venv activated
# Now you can run commands directly:
pytest
python playground/runner.py

Key Points:

• Virtual environment: .venv/ (already created, don't recreate)
• Python version: 3.10+ (check with poetry run python --version)
• Always prefix commands with poetry run OR enter poetry shell first
• If you see import errors, you're likely not in the poetry environment