Add repository guidelines for AI Agent document outlining project structure, coding style, testing, and commit practices

Author: adamamer20

AGENTS.md

@@ -0,0 +1,40 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `mesa_frames/`: Source package.
+  - `abstract/` and `concrete/`: Core APIs and implementations.
+  - Key modules: `agents.py`, `agentset.py`, `space.py`, `datacollector.py`, `types_.py`.
+- `tests/`: Pytest suite (`test_*.py`) covering public APIs.
+- `docs/`: MkDocs and Sphinx content for user and API docs.
+- `examples/`: Reproducible demo models and performance scripts.
+
+## Build, Test, and Development Commands
+- Install (dev stack): `uv sync` (always use uv)
+- Lint & format: `uv run ruff check . --fix && uv run ruff format .`
+- Tests (quiet + coverage): `export MESA_FRAMES_RUNTIME_TYPECHECKING = 1 && uv run pytest -q --cov=mesa_frames --cov-report=term-missing`
+- Pre-commit (all files): `uv run pre-commit run -a`
+- Docs preview: `uv run mkdocs serve`
+
+Always run tools via uv: `uv run <command>`.
+
+## Coding Style & Naming Conventions
+- Python 3.11+, 4-space indent, type hints required for public APIs.
+- Docstrings: NumPy style (validated by Ruff/pydoclint).
+- Formatting/linting: Ruff (formatter + lints). Fix on save if your IDE supports it.
+- Names: `CamelCase` for classes, `snake_case` for functions/attributes, tests as `test_<unit>.py` with `Test<Class>` groups.
+
+## Testing Guidelines
+- Framework: Pytest; place tests under `tests/` mirroring module paths.
+- Conventions: One test module per feature; name tests `test_<method_or_behavior>`.
+- Coverage: Aim to exercise new branches and error paths; keep `--cov=mesa_frames` green.
+- Run fast locally: `pytest -q` or `uv run pytest -q`.
+
+## Commit & Pull Request Guidelines
+- Commits: Imperative mood, concise subject, meaningful body when needed.
+  Example: `Fix AgentsDF.sets copy binding and tests`.
+- PRs: Link issues, summarize changes, note API impacts, add/adjust tests and docs.
+- CI hygiene: Run `ruff`, `pytest`, and `pre-commit` locally before pushing.
+
+## Security & Configuration Tips
+- Never commit secrets; use env vars. Example: `MESA_FRAMES_RUNTIME_TYPECHECKING=1` for stricter dev runs.
+- Treat underscored attributes as internal.