Substak-MCP AGENTS.md

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Quick Command Reference (Use These!)

# ALWAYS activate virtual environment first:
source venv/bin/activate

# Run tests (use python3!):
python3 -m pytest                           # Run all tests
python3 -m pytest tests/unit/test_foo.py -v # Run specific test
python3 -m pytest --cov=src --cov-report=term # Check coverage

# Code quality:
black src tests     # Format code
mypy src           # Type checking

# Common fixes:
# If "python: command not found" → use python3
# If "ModuleNotFoundError" → activate venv first
# If creating docs → put in docs/ not root!

Interaction

• Any time you interact with me, you MUST address me as "Sir"

Starting a new project

Whenever you build out a new project and specifically start a new AGENTS.md - you should pick a name for yourself, and a name for me (something short a sweet). This is important

• When picking names it should be really unhinged, and super fun. not necessarily code related. think 90s, monstertrucks, and something gen z would laugh at

Writing code

• CRITICAL: NEVER USE --no-verify WHEN COMMITTING CODE
• NEVER commit without running tests first
• NEVER commit directly to main branch - use feature branches
• We prefer simple, clean, maintainable solutions over clever or complex ones, even if the latter are more concise or performant. Readability and maintainability are primary concerns.
• Make the smallest reasonable changes to get to the desired outcome. You MUST ask permission before reimplementing features or systems from scratch instead of updating the existing implementation.
• When modifying code, match the style and formatting of surrounding code, even if it differs from standard style guides. Consistency within a file is more important than strict adherence to external standards.
• NEVER make code changes that aren't directly related to the task you're currently assigned. If you notice something that should be fixed but is unrelated to your current task, document it in a new issue instead of fixing it immediately.
• NEVER remove code comments unless you can prove that they are actively false. Comments are important documentation and should be preserved even if they seem redundant or unnecessary to you.
• All code files should start with a brief 2 line comment explaining what the file does. Each line of the comment should start with the string "ABOUTME: " to make it easy to grep for.
• When writing comments, avoid referring to temporal context about refactors or recent changes. Comments should be evergreen and describe the code as it is, not how it evolved or was recently changed.
• NEVER implement a mock mode for testing or for any purpose. We always use real data and real APIs, never mock implementations.
• When you are trying to fix a bug or compilation error or any other issue, YOU MUST NEVER throw away the old implementation and rewrite without expliict permission from the user. If you are going to do this, YOU MUST STOP and get explicit permission from the user.
• NEVER name things as 'improved' or 'new' or 'enhanced', etc. Code naming should be evergreen. What is new today will be "old" someday.