AGENTS.md

AGENTS.md: Developer & AI Coding Assistant Guide

This document provides operational guidance, repository architecture, build/test commands, and strict governance rules for developers and AI coding assistants working on noaadata (README.md).

IMPORTANT CONTINUOUS UPDATE MANDATE: As noaadata undergoes Spec-Driven Development (SDD) modernization from legacy packaging (setup.py) to modern Python (>=3.13, pyproject.toml, uv, pytest, ruff, strict static typing), you must continuously update all sections of AGENTS.md (overview, repository layout, build/test commands, formatting standards, and architecture notes) as the codebase evolves.

---

1. Project Overview (Current State)

noaadata is a Python library for encoding, decoding, and processing NOAA CO-OPS marine water level data, Automatic Identification System (AIS) ship traffic binary messages, USCG N-AIS receive fields, and NMEA-0183 marine sentences. It also provides database bridges (PostgreSQL/PostGIS, SQLite3) and GIS exporters (Google Earth KML).

The project has completed a multi-phase Spec-Driven Development (SDD) modernization initiative outlined in PRD.md, SPEC.md, and TASKS.md. Legacy setup.py setuptools packaging has been replaced with modern PEP 621 declarative packaging using hatchling and uv environment management. All 336 unit, property, and benchmark tests pass, code is formatted with ruff and mdformat, static typing is checked with mypy, and automated CI/CD pipelines run on GitHub Actions.

---

2. Repository Layout (Current State)

• src/: Pure-Python source package directory containing PEP 561 py.typed markers:
  • src/noaadata/: NOAA CO-OPS water level SOAP and DAP client/parsing (stations.py, waterlevel_dap.py, waterlevelraw.py, dumpallwl.py), and CLI entry points in cli/.
  • src/ais/: Marine AIS binary message definitions (messages 1–24, IMO messages, binary waterlevel messages, whale notices, compilers/translators) optimized with C-backed word-level bitwise shifts.
  • src/aisutils/: Core BitVector.py, 6-bit ASCII strings (aisstring.py), binary bit unpacking (binary.py), database bridges (database.py, sqlhelp.py), USCG extensions (uscg.py), and grid calculations (grid.py) with __slots__ memory layout.
  • src/nmea/: Standard NMEA-0183 sentences (gga.py, rmc.py, zda.py, znt.py, and checksum validation checksum.py).
• docs/: Documentation site source files built with mkdocs and mkdocstrings (docs/index.md, docs/migration_guide.md, docs/api/).
• .github/: GitHub Actions CI/CD workflows (.github/workflows/ci.yml, .github/workflows/release.yml) and community governance (CODEOWNERS, PULL_REQUEST_TEMPLATE.md).
• tests/: Dedicated directory for pytest unit, property, and benchmark test suites.
• SECURITY.md & CODE_OF_CONDUCT.md: Community governance policies.
• pyproject.toml: Modern PEP 621 declarative packaging configuration using hatchling as the PEP 517 build backend.
• mkdocs.yml: MkDocs Material documentation configuration.
• uv.lock: Deterministic dependency lockfile generated by uv.

---

3. Build & Test Commands (Current State)

Environment Setup & Tool Commands (uv)

noaadata uses uv and pyproject.toml for packaging and environment management:

# Sync environment and install package with dev dependencies
uv sync

# Run pytest unit, property, and benchmark test suites
uv run pytest

# Check code formatting and linting
uv run ruff format --check
uv run ruff check

# Run pre-commit hooks across all files
uv run pre-commit run --all-files

# Check markdown formatting and spelling
uv run mdformat --check README.md docs/ sdd/
uv run codespell .

# Static type checking
uv run mypy src/

# Build documentation site
uv run mkdocs build

# Build package distributions (sdist & wheel)
uv build

---

4. Strict Version Control & Git Commit Rules

All contributors and AI coding assistants MUST adhere to the following version control guardrails:

4.1 Conventional Commits Required

Every Git commit message MUST follow the Conventional Commits specification:

<type>(<scope>): <subject>

• Allowed Types:
  • feat: A new feature or capability (e.g., feat(ais): add support for message 24).
  • fix: A bug fix (e.g., fix(nmea): resolve checksum boundary error).
  • refactor: Code refactoring without behavioral changes (e.g., refactor(aisutils): implement dunder protocols on BitVector).
  • test: Adding or updating test suites (e.g., test(noaadata): migrate legacy grid tests to pytest).
  • build: Packaging or dependency updates (e.g., build: migrate from setup.py to pyproject.toml and hatchling).
  • docs: Documentation updates (e.g., docs: update migration guide and AGENTS.md).
  • chore: Maintenance tasks (e.g., chore: configure ruff and mdformat pre-commit hooks).
• Scope: Must name the specific package or component being modified (ais, aisutils, nmea, noaadata, scripts, test, build, docs).
• Subject: Concise, imperative description of the change (lower-case, no trailing period).

4.2 ABSOLUTELY NO Tag or Conversation ID Entries in Commits

• CRITICAL: Do NOT include any TAG=gy, TAG=agy, CONV=..., BUG=..., or conversation ID metadata trailers in Git commit messages for this repository.
• Commit messages must remain clean, standard Conventional Commits without automated conversation tracking trailers.

4.3 Mandatory Pre-Commit Hook Execution

• CRITICAL: All developers and AI coding assistants MUST ALWAYS run uv run pre-commit run --all-files before committing any changes.
• All pre-commit hooks (formatting, linting, security scans, static typing) must pass without errors prior to creating a Git commit.

---

5. Style & Documentation Standards

• Docstrings: Use Google Python Docstring Style (Args:, Returns:, Raises:, Attributes:) for all modules, classes, and functions.
• Formatting: Maintain 88-column line length for Python code (enforced by ruff format in Phase 3) and 80-column line length for Markdown documentation (enforced by mdformat).
• Type Annotations: Follow PEP 585/PEP 604 syntax (list[int], str | None, typing.Self). Do not introduce ambiguous Any types without explicit documentation.