Skip to content

Using Agents

This page describes how we use AI coding agents — currently OpenAI Codex and Anthropic Claude Code — for uDALES development work. It is aimed at contributors working on this repository.

Improved agent instructions coming

A revised, expanded set of agent instructions is under development on the performance branch and will supersede parts of this page once merged.

When to use an agent

Agents are useful for:

  • repeated operational workflows on clusters
  • test execution and triage across multiple suites
  • refactors with careful bookkeeping
  • large documentation updates with cross-file consistency

Use an agent when the task benefits from:

  • consistent, repeatable steps
  • multi-file updates with traceability
  • detailed run logs or comparisons

Source of truth

Project-specific instructions for agents live in:

  • AGENTS.md (repo-level guidance, read by both Codex and Claude Code)
  • .github/skills/udales-exec/ (cluster execution runbook skill)
  • .github/skills/udales-detect/ (environment detection skill)

When in doubt, prefer the repo wrappers in tools/ and the curated test selectors under tests/.

Skill usage

The udales-exec skill is intended for cluster execution and test workflows. It detects the environment, loads the correct modules, and chooses the right build/run/test commands.

First run on a new system

When you first use a new machine or cluster, run the lightweight self-test to confirm that wrappers, Python tooling, and the environment fingerprint are correct before attempting heavier builds or MPI jobs. If it fails, update the cluster profile in .github/skills/udales-exec/references/clusters.md and rerun.

To run the self-test:

UD_VENV=/rds/general/user/$USER/home/udales/.venv
UD_PYTHON=python3
UD_VENV="$UD_VENV" UD_PYTHON="$UD_PYTHON" .github/skills/udales-exec/scripts/skill_selftest.sh

Use --full for execution-only verification with a prebuilt solver binary:

UD_VENV=/rds/general/user/$USER/home/udales/.venv
UD_PYTHON=python3
UD_BUILD=/path/to/u-dales
UD_VENV="$UD_VENV" UD_PYTHON="$UD_PYTHON" UD_BUILD="$UD_BUILD" \
  .github/skills/udales-exec/scripts/skill_selftest.sh --full

Do and don’t

  • Do keep the top-level repo workflow solver-first.
  • Do use tests/run_tests.py for curated selections.
  • Do run python tests/run_tests.py python-library after successful compilation as the default Python-library validation stream.
  • Do record new cluster profiles in .github/skills/udales-exec/references/clusters.md.
  • Don’t invent ad hoc module stacks when repo wrappers exist.
  • Don’t run heavy MPI tests inside sandboxed environments.