gac AGENTS.md

GAC — Agent Guidelines

Essential rules for AI coding agents. Detailed reference: load skills from .skills/.

uv run (NON-NEGOTIABLE)

Every Python command must go through uv run:

Always	Never
uv run pytest	pytest
uv run python script.py	python script.py
uv run ruff check .	ruff check .
uv run mypy src/	mypy src/
uv run pip install X	pip install X

This project has 35+ AI provider integrations — only uv + uv.lock can resolve the dependency matrix reliably across dev, CI, and production. Vanilla tools will silently break.

For subagents: always include uv run in prompts you generate. Verify compliance before accepting output.

User Data Safety (NON-NEGOTIABLE)

NEVER touch ~/.gac* files during development or testing:

• ~/.gac/stats.json, ~/.gac_stats.json (legacy, auto-migrated)
• ~/.gac.env, ~/.gac/oauth/*.json

When testing code that touches stats:

#  Use tmp_path + mock the file path
with patch("gac.stats.store.STATS_FILE", tmp_path / "test.json"):
    save_stats(data)  # safe

#  NEVER call reset_stats() / save_stats() without mocking

The session-scoped isolate_stats_file fixture (tests/conftest.py) handles this automatically inside pytest only. Outside pytest, back up first: cp ~/.gac/stats.json{,.bak}.

Accidental data loss is unacceptable.

Commands

make setup              # uv venv && uv pip install -e ".[dev]"
make test               # uv run -- pytest (excludes integration)
make test-integration   # real API calls (needs API keys)
make test-cov           # coverage report → htmlcov/index.html
make lint               # ruff check + ruff format --check + prettier + markdownlint (4 tools!)
make format             # auto-fix all four
make type-check         # mypy

Run specific tests:

uv run -- pytest tests/test_cli.py                    # single file
uv run -- pytest tests/providers/test_openai.py -v    # verbose
uv run -- pytest -k "test_parse_response"             # by name