Imported from OWissett/terrain-gues (AGENTS.md). Install upstream with npx skills add OWissett/terrain-gues. Copyright stays with the author.

Repository Guidelines

Git Instructions

• Agents should maintain changes in feature branches named codex/feat/your-feature-name or codex/fix/your-bugfix-name.
• Changes should be committed in logical chunks with clear messages. Use git commit -m "type: short description" format (e.g., feat: add new terrain analysis module).
• Before pushing, ensure your branch is up to date with git pull origin main and resolve any conflicts.
• Push your branch with git push origin your-branch-name

Project Structure & Module Organization

• Current tree is intentionally minimal. Add Python source under src/terrain_gues/ (package modules, adapters) and keep executable entry points or notebooks in scripts/ or notebooks/ if needed.
• Mirror code layout in tests/ (tests/terrain_gues/test_*.py) so fixtures and helpers align with the modules they cover.
• Place large artifacts in git-ignored folders (data/, artifacts/) and keep small sample inputs under tests/fixtures/ for reproducible runs.
• Keep project-level configuration (e.g., pyproject.toml, ruff.toml, pytest.ini) at the repo root.

Build, Test, and Development Commands

• Create an environment: python -m venv .venv && source .venv/bin/activate.
• Install dependencies (once requirements.txt or pyproject.toml exists): pip install -r requirements.txt or pip install -e .[dev] for editable development extras.
• Lint/format with Ruff: ruff format src tests then ruff check src tests to enforce style and catch errors quickly.
• Run tests with pytest: pytest -q for the full suite, or pytest tests/test_module.py -k subset for focused checks.
• Optional: python -m build before publishing to ensure packaging metadata is valid.

Coding Style & Naming Conventions

• Python-first; use 4-space indentation, type hints everywhere, and prefer dataclasses for structured data.
• Naming: snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE_CASE for constants, and short, lowercase module names.
• Keep functions small and side-effect-aware; raise domain-specific exceptions rather than generic ones.
• Docstrings in Google style for public functions/classes; include argument units and expected shapes where relevant.

Testing Guidelines

• Use pytest with tests named test_*.py and functions test_*. Co-locate fixtures in tests/conftest.py or tests/fixtures/.
• Aim for meaningful coverage (≈80%+) focusing on boundary conditions and error paths; prefer pure functions to simplify testing.
• Mark slow or external-resource tests with @pytest.mark.slow and exclude them by default (pytest -m \"not slow\").
• When adding new behavior, include at least one regression test demonstrating the intended contract.

Commit & Pull Request Guidelines

• Follow a Conventional Commit style for clarity (e.g., feat: add elevation loader, fix: handle empty tileset). Keep subject lines under ~65 chars.
• Commits should be scoped and reversible; avoid mixing refactors with feature changes.
• PRs: include a short summary, linked issue/reference, test results (pytest, ruff), and screenshots or CLI samples if user-visible output changes.
• Note any config, migration, or data expectations in the PR description so reviewers can reproduce locally.

Security & Configuration Tips

• Do not commit secrets; use a local .env (git-ignored) and, if needed, provide a sanitized .env.example.
• Validate inputs before file or network operations; keep temporary outputs under ./tmp or ./.cache with appropriate ignores.
• Review dependencies for licenses and pin versions in lock files to ensure reproducible builds once dependency management is added.