Skip to content

AGENTS.md

Latest commit

 

History

History
69 lines (59 loc) · 4.23 KB

AGENTS.md

File metadata and controls

69 lines (59 loc) · 4.23 KB

AGENTS.md

Core Operating Contract

  • Treat this repository as the source of truth.
  • Treat the website as a rendered view of repository state.
  • Prefer small, additive, traceable edits.
  • Keep documentation synchronized with code and project structure.
  • Keep the repository minimalist by default.

Default Workflow

  • Inspect repository structure before editing.
  • Make the smallest diff that solves the request.
  • Update related docs when behavior, workflows, or outputs change.
  • Update changelog, dev log, or equivalent history files for meaningful changes.
  • Preserve existing structure and historical context.
  • Do not perform destructive rewrites unless explicitly requested.

Documentation and Website Policy

  • Treat docs/ as project-level documentation and website source.
  • Update docs whenever code, workflows, or outputs change.
  • Amend existing docs when possible; do not replace whole files without need.
  • Preserve navigation, readability, and consistency in website changes.
  • Keep default website behavior clean and minimal unless the user asks for more expressive design.

Testing Policy

  • Assume tests/ may exist before a full testing framework is defined.
  • Do not invent domain-specific tests when expected behavior is unclear.
  • Add the smallest meaningful tests when behavior is known.
  • Prefer early-stage checks such as smoke tests, import tests, CLI tests, schema checks, or example-based checks.
  • If tests are deferred, document the gap; do not imply coverage that does not exist.

Pre-PR Website Validation Gate (Required)

  • For any change affecting docs content, website styling, interactive HTML, JavaScript, iframe embeds, MkDocs configuration, or published website assets, Codex must run local website validation before considering the task complete.
  • Local website validation must include all of the following:
    1. relevant build/analysis steps for website-facing outputs,
    2. mkdocs build,
    3. Playwright tests.
  • Use scripts/pre_pr_site_review.sh as the default one-command workflow for this validation.
  • If any Playwright test fails, Codex must inspect failure artifacts (screenshots, traces, reports), fix the issue, and rerun the full local validation until it passes.
  • Codex must not prepare, propose, or request a PR until these local checks are passing.

Package and Structure Separation Policy

  • Keep website structure and package structure clearly separated.
  • Do not automatically repurpose docs/ for package-native docs or build artifacts.
  • For Python packaging requests, prefer standard Python layout, typically src/.
  • For R packaging requests, follow standard R conventions (R/, man/, DESCRIPTION, NAMESPACE, optional vignettes/).
  • For other ecosystems, follow ecosystem conventions.
  • If structural conflicts arise, choose a durable long-term structure and document the decision.

Data Discovery and Data Use Policy

  • Prefer open and FAIR data when possible.
  • Prefer streaming or lazy-access workflows over bulk downloads when feasible.
  • Use standards-based discovery systems (for example STAC) when relevant.
  • When relevant, consider streaming-friendly tooling such as xarray, zarr, GDAL, rasterio, pystac-client, stackstac, gdalcubes, terra, stars, cubo, or equivalent tools.
  • When introducing data, document source, access method, format, license, and citation requirements.
  • Do not silently ingest external data into the project.

Data Sovereignty and Intellectual Property Policy

  • Consider licensing, copyright, privacy, Indigenous data sovereignty, and related restrictions for all data and content.
  • If rights or permissions are unclear, document uncertainty and avoid assuming open reuse.

Design and Usability Policy

  • Keep the website simple, readable, and easy to extend by default.
  • When design improvements are requested, prioritize system-level improvements (layout, spacing, typography, hierarchy, navigation, consistency).
  • Do not use scattered one-off styling hacks.
  • If direct site inspection is possible, verify readability, navigation, link integrity, and that docs still reflect repository state.

Decision Logging

  • Reflect meaningful structural, architectural, documentation, data-source, or design decisions in changelog, dev log, roadmap, or equivalent history files when appropriate.