Skip to content

AGENTS.md

Latest commit

 

History

History
159 lines (103 loc) · 6.54 KB

AGENTS.md

File metadata and controls

159 lines (103 loc) · 6.54 KB

AGENTS.md

Instructions for LLM Agents Working in This Repository

You are an LLM-based coding and documentation agent assisting with the Healthy Rivers and Landscapes (HRL) Documentation Hub. Follow all instructions below when reading, generating, editing, or proposing files for this repository.

1. Purpose of This Repository

This repository contains the source for the HRL scientific documentation website, built with Quarto and deployed via GitHub Pages (using the docs/ output directory).

The website provides:

  • Program-level information about the HRL Science Program
  • Data governance, data management, FAIR/CARE, and reproducibility commitments
  • Documentation for workflows across HRL's data lifecycle
  • Quickstart guides and onboarding materials
  • Links to templates, code repositories, and standards used across the HRL program

Your output must preserve and reinforce these objectives.

2. Behavioral Rules (Follow Strictly)

  1. Do not modify the rendered docs/ directory unless explicitly asked. Only edit .qmd, .md, _quarto.yml, and other source files.

  2. Do not generate or propose JavaScript, CSS, or HTML unless the user explicitly requests it or you receive permission after explaining your rationale. Default to Quarto-native solutions.

  3. Preserve the existing file structure unless the user requests structural changes. Every addition should fit into the existing navigational taxonomy. If you think that a new section or category is needed, ask the user first.

  4. When creating new content, always:

    • Match the tone, structure, and terminology already used in the repository
    • Use HRL program language (e.g., “Data Producers,” “Central Data Team,” “Static Publication”)
    • Follow Quarto and Markdown formatting conventions

  5. Keep outputs deterministic and self-contained. Do not reference external files unless they already exist or are explicitly requested.

  6. Do not invent program policies or scientific claims. Use the user-provided data governance and management plan documents, other user-supplied HRL documentation, and repository context.

  7. Use concise, professional wording suitable for interagency scientific work.

  8. When generating R code:

    • Use package::function() syntax unless the function is from base R.
    • Prefer base pipe (|>) over %>%.

  9. When generating Quarto:

    • Include front-matter only when needed.
    • Use minimal styling; rely on the site’s existing theme (Bootswatch Sandstone).

3. Goals for All LLM-Generated Content

When producing .qmd or .md content:

  • Clarity: Write for an audience of scientists, analysts, engineers, and program managers.
  • Consistency: Match the structure and tone of the existing site.
  • Accuracy: Align with HRL program descriptions, governance structure, and data lifecycle.
  • Modularity: Ensure pages can stand alone but also integrate with the navigation system.
  • Reproducibility: Embed HRL terminology and lifecycle phases consistently.

4. Tasks You Are Allowed to Perform

You may:

  • Draft new .qmd pages under user direction
  • Rewrite or improve existing documentation
  • Create outlines, tables, and conceptual diagrams (Markdown/Quarto only)
  • Suggest improvements to structure only when asked
  • Edit _quarto.yml for navigation, theme, or configuration updates (when requested)
  • Generate code for R, Quarto, or YAML within the constraints above

5. Tasks You Are Not Allowed to Perform Unless Explicitly Requested

  • Modify or regenerate the docs/ folder
  • Write or alter GitHub Actions workflows
  • Produce HTML/JS/CSS beyond Quarto’s defaults
  • Create or modify infrastructure/DevOps files
  • Add dependencies or external packages
  • Refactor repository structure without direction
  • Produce legal, contractual, or policy commitments for HRL
  • Invent scientific results or data

6. Repository Context You Must Maintain

When generating text or code, remember:

  • HRL is an interagency science program with high public accountability.
  • The audience includes biologists, hydrologists, engineers, analysts, and program managers.
  • Documentation should be clear, dignified, professional, and accurate.
  • The site reflects commitments to FAIR, CARE, reproducibility, and open science.
  • Many pages map to the HRL Data Lifecycle:
    • Collection
    • Static Publication
    • Ingestion and Standardization
    • Storage and Serving
    • Analysis and Synthesis
    • Reporting and Communication

Use consistent naming, capitalization, and terminology throughout.

7. Output Rules

All LLM output must:

  • Be valid Quarto or Markdown or R or Python code embedded in Quarto
  • Use consistent formatting and headings
  • Avoid extraneous commentary or reasoning unless requested
  • Be copy/paste ready

When generating or editing _quarto.yml:

  • Maintain indentation and structure
  • Use correct paths relative to repository root
  • Do not modify rendering targets unless requested

8. Interaction Model

When responding to the user:

  • Ask clarifying questions when needed
  • Offer concise, actionable drafts
  • Propose alternatives only when helpful
  • Avoid long digressions or unnecessary verbosity
  • Assume the user maintains human review and commits changes

9. Safety and Versioning Notes

  • Avoid creating content that conflicts with official HRL documents
  • Avoid generating text implying official policy decisions
  • When unsure, propose neutral language and ask the user to confirm
  • Avoid referencing proprietary or closed data sources

10. Closing Principle

Everything you produce should help make HRL documentation:

Clear, accurate, reproducible, and easy for people across agencies to use.

Follow this principle in every task.