docs: add contributor guidelines for agents

AGENTS.md

@@ -0,0 +1,23 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Core code lives in `reviewtally/`, with `cli/` handling argument parsing, `analysis/` and `metrics_calculation.py` generating review metrics, and `visualization/` producing Plotly outputs. Shared cache logic sits under `cache/`, GraphQL helpers in `queries/`, and exporters in `exporters/`. Tests mirror these folders in `tests/`, reusing fixtures from `tests/fixtures/` and async helpers in `tests/utils.py`. Generated docs and chart assets stay in `docs/`; built wheels appear in `dist/`.
+
+## Build, Test, and Development Commands
+Install via `poetry install` (Python 3.11). Use `poetry run review-tally -o expressjs -l javascript` to exercise the CLI end-to-end. Quality gates:
+- `poetry run pytest` — async test suite.
+- `poetry run ruff check .` and `poetry run ruff format .` — lint + format.
+- `poetry run mypy reviewtally/` and `poetry run isort .` — type/import hygiene.
+- `poetry run pre-commit run --all-files` — replicate CI hooks before pushing.
+
+## Coding Style & Naming Conventions
+Ruff enforces PEP 8 with a 79-character limit. Use snake_case for functions, UpperCamelCase for classes, and keep module names short. Prefer explicit imports and typed signatures, especially around HTTP requests and cache boundaries. Add CLI switches following the existing long-flag style (`--plot-sprint`, `--cache-ttl`) and document them in `main.py` help text.
+
+## Testing Guidelines
+Write tests with `pytest`, `pytest-asyncio`, and `pytest-aiohttp`. Place scenario data in `tests/fixtures/` and reuse cache helpers when faking API responses. Name files `test_<area>.py`, cover both positive and failure paths for metrics, exporters, and visualization toggles, and ensure new metrics update snapshot expectations or CSV assertions. Run `poetry run pytest tests/get_reviewers/` to validate reviewer-specific flows before merging.
+
+## Commit & Pull Request Guidelines
+Commit messages follow Conventional Commits (`feat:`, `refactor:`, `chore:`) with concise scopes. Explain the user-facing change first and keep the subject under 72 characters. Pull requests should summarize the change, list new flags or outputs, link issues, and attach screenshots or saved plots when altering visuals. State that `poetry run pytest` and `poetry run ruff check .` both passed.
+
+## Security & Configuration Tips
+Export `GITHUB_TOKEN` in your shell profile; avoid hardcoding credentials or committing generated CSV/HTML artifacts. Review dependency diffs in `pyproject.toml` and justify new scopes or network calls. Clean up local cache exports before sharing archives to prevent leaking sprint data.