From ab37c880a38e11e026c5a8b4f95a96e92964cc60 Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Wed, 4 Mar 2026 09:55:11 -0800 Subject: [PATCH 01/10] Initial custom agents for testing and document writing --- .github/agents/technical-doc-writer.agent.md | 24 ++++++++++++++++++++ .github/agents/test-specialist.md | 17 ++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 .github/agents/technical-doc-writer.agent.md create mode 100644 .github/agents/test-specialist.md diff --git a/.github/agents/technical-doc-writer.agent.md b/.github/agents/technical-doc-writer.agent.md new file mode 100644 index 00000000000..bc8c1aed967 --- /dev/null +++ b/.github/agents/technical-doc-writer.agent.md @@ -0,0 +1,24 @@ +--- +name: technical-doc-writer +description: "Use this agent when the user asks to write or improve documentation." +--- + +# technical-doc-writer instructions + +You are an expert technical documentation specialist with deep software engineering knowledge and exceptional communication skills. Your strength lies in translating complex technical concepts into clear, understandable prose while maintaining scientific and architectural precision. + +Target audience are scientist, researchers, and system integrators. + +Machine configuration is specific to system integrators. + +Your responsibilities: + +- Analyze changes in current branch and add technical documentation +- Assess documentation needs by understanding the technical context and intended audience +- Organize information hierarchically with clear conceptual flow +- Balance depth with accessibility - explain concepts thoroughly without being verbose +- Include runnable, tested examples that demonstrate real-world usage +- Document edge cases, limitations, and gotchas prominently +- Ask clarifying questions when requirements are ambiguous + +Commit to asking these clarifying questions upfront rather than making assumptions. Your goal is documentation that precisely meets the user's needs. diff --git a/.github/agents/test-specialist.md b/.github/agents/test-specialist.md new file mode 100644 index 00000000000..20d51f344be --- /dev/null +++ b/.github/agents/test-specialist.md @@ -0,0 +1,17 @@ +--- +name: test-specialist +description: Focuses on test coverage, quality, and testing besst practices without modifying production code. +--- + +You are a testing specialist focused on improving code quality through comprehensive +testing. You are well versed with python and pytest package. + +Your responsibilities: + +- Analyze changes in current branch +- Write unit tests, integration tests, and end-to-end tests following best practices +- Review test quality and suggest improvements for maintainability +- Ensure tests are isolated, deterministic, and well-documented +- Focus only on test files and avoid modifying production code unsless specifically requested + +Always include clear test descriptiuons and use appropriate testing patterns for python and pytest. From 1182270db656646902f77b3c80fa47770abd7876 Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Thu, 12 Mar 2026 12:51:50 -0700 Subject: [PATCH 02/10] chore: cleanup main agents file --- AGENTS.md | 184 ++++++++++++++++++------------------------------------ 1 file changed, 62 insertions(+), 122 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 75f517e91a1..a7e46cb13a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,5 @@ # AGENTS.md -This file provides guidance to AI agents when working with code in this repository. - ## Note to AI agents This AGENTS.md is maintained by the CIME project. Do not overwrite or @@ -12,126 +10,92 @@ regenerate this file with init commands. A CLAUDE.md file is in .claude directory. It includes this file. Ignore tips to run init. -## Project Overview - -CIME (Common Infrastructure for Modeling the Earth) provides a Case Control System (CCS) for configuring, compiling, and executing Earth System Models, plus a framework for system testing. CIME is a Python-based infrastructure currently used by CESM, E3SM, NorESM and other models. It does NOT contain model source code itself, but provides the infrastructure to manage model runs. - -## Running Tests +## Overview -### Unit and System Tests +At it's core CIME provides a user the ability to configure, build, and run +simulation models. In addition it provides tools to post-process and archive +model output. CIME provides model developers the ability to test their models +under specific criteria e.g. check performance or reproducibility. -From the repository root, run tests using either: +Documentation: https://esmci.github.io/cime -```bash -# Using pytest (recommended) -pytest CIME/tests +### User Usage -# Run specific test file -pytest CIME/tests/test_unit_foo.py +Requires a supported machine and supported model (E3SM, CESM, NorESM). -# Run specific test class -pytest CIME/tests/test_unit_foo.py::TestClass +- Create a case: `./scripts/create_newcase --compset --res --case --machine `, e.g. `./scripts/create_newcase --compset A --res f19_g16 --case ./cases/case01 --machine docker` +- Setup case: `./case.setup` +- Build case: `./case.build` +- Submit case: `./case.submit` +- Query case config: `./xmlquery` +- Change case config: `./xmlchange` +- Preview namelist: `./preview_namelists` +- Run a model system test: `./scripts/create_test --machine SMS.f19_g16.X`, e.g. `./scripts/create_test --machine docker SMS.f19_g16.X` +- Query configuration: `./scripts/query_config --compsets`, `./scripts/query_config --grids`, `./scripts/query_config --machines` -# Run specific test case -pytest CIME/tests/test_unit_foo.py::TestClass::test_method -``` +## Developer -Test files follow a naming convention: -- Unit tests: `test_unit_*.py` -- System tests: `test_sys_*.py` +### Container -### Pre-commit Hooks +Provides a supported machine for CIME development and testing. -Before committing, always run: +Assume supported model is cloned in parent directory. -```bash -pip install pre-commit -pre-commit run -a -``` +Build the container: `docker build -t ghcr.io/esmci/cime:latest -f docker/Dockerfile .` +Run a non-persistent container: `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime -v ./inputdata:/root/inputdata -v ./storage:/root/storage -e CIME_MODEL=e3sm ghcr.io/esmci/cime:latest pytest CIME/tests/test_unit*`:w +Start persistent container: `docker run -d --name cime --hostname docker -v ../:/root/model -w /root/model/cime -v ./inputdata:/root/inputdata -v ./storage:/root/storage -e CIME_MODEL=e3sm ghcr.io/esmci/cime:latest` +Run develop test: `docker exec -it cime /entrypoint.sh pytest CIME/tests/test_unit*` +Create a case: `docker exec -it cime /entrypoint.sh ./scripts/create_newcase --compset X --res f19_g16 --case /root/storage/cases/case01` +Setup a case: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./case.setup` +Build a case: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./case.build` +Submit a case: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./case.submit` +Query case config: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./xmlquery` +Change a case config: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./xmlchange` +Run a model system test: `docker exec -it cime /entrypoint.sh ./scripts/create_test SMS.f19_g16.S` -This runs: -- `black` formatter on CIME code -- `pylint` with project-specific configuration -- XML validation on config files -- End-of-file and trailing whitespace checks +### Testing -## Code Quality +Unit tests: `CIME/tests/test_unit*.py` +E2E tests: `CIME/tests/test_sys*.py` -- Code is formatted with `black` -- Linted with `pylint` (see `.pre-commit-config.yaml` for disabled checks) -- Python 3.9+ required -- Follow PEP8 style guidelines +Setup: `pip install -r test-requirements.txt` -## Key Architecture Concepts +Running tests: `pytest CIME/tests/test_*.py` -### Case Control System (CCS) +### Code Quality -The heart of CIME is the `Case` class (`CIME/case/case.py`), which manages all interactions with a CIME case. The Case class coordinates between: +Follow `pep8` style guidelines. -1. **Config XML Classes** (readonly) - Located in `CIME/XML/`, these read CIME distribution config files like `config_*.xml`. Python classes are named after the XML they read (e.g., `Machines` reads machine configs). +Use Google style for docstrings. -2. **Env XML Classes** (read/write) - Also in `CIME/XML/`, these manage case-specific `env_*.xml` files. Classes are named `Env*` (e.g., `EnvRun`, `EnvBuild`). +Use `black` and `pylint` for formatting and linting. -The Case class contains an array of Env classes and uses Config classes to populate them during case creation/configuration. +Always use `pre-commit` before commiting code, e.g. `pre-commit run -a`. -### Directory Structure +### Documentation -``` -CIME/ -├── case/ # Case control modules (setup, run, submit, etc.) -├── XML/ # XML parsers for config and env files -├── SystemTests/ # System test implementations (ERS, ERT, etc.) -├── Tools/ # Case manipulation tools (xmlchange, xmlquery, etc.) -├── scripts/ # Top-level user-facing scripts -├── data/ # Config files, XML schemas -├── tests/ # Unit and system tests -├── BuildTools/ # Build system utilities -└── non_py/ # Non-Python components (C/Fortran) +Documentation is found under `doc/`. -scripts/ -├── create_newcase # Create new case -├── create_test # Create and run tests -├── create_clone # Clone existing case -├── query_config # Query available configurations -└── query_testlists # Query test lists +Always write documentation in reStructured text. -tools/ -└── mapping/ # Grid mapping file generation tools -``` +Setup: `pip install -r doc/requirements.txt` -### Common Workflows +Build documentation: `cd doc; make html` -**Create a case** (requires machine configuration): -```bash -./scripts/create_newcase --case CASENAME --compset COMPSET --res GRID [--machine MACHINE] -``` +### Architecture -**Create and run tests**: -```bash -./scripts/create_test TESTNAME -./scripts/create_test TESTNAME1 TESTNAME2 ... -./scripts/create_test -f TESTFILE # from file -``` +The `Case` class (`CIME/case/case.py`) is the core of CIME. -**Query configurations**: -```bash -./scripts/query_config --compsets -./scripts/query_config --grids -./scripts/query_config --machines -``` +Case configuration is handled by XML files. -### Model System Tests +- Dynamic configuration `CIME/XML/env_*.py`, read/write configuration specific to a `Case`. +- Static configuration, all non `env_*.py` files under `CIME/XML/*.py`, readonly provided before `Case` is constructed. -These are tests of properties of the model CIME is included in. -System tests inherit from `SystemTestsCommon` base class (`CIME/SystemTests/system_tests_common.py`). Common test types: -- **ERS**: Exact restart test -- **ERT**: Exact restart with different threading -- **SMS**: Smoke test -- **SEQ**: Sequencing test +Dynamic config classes named after XML they read e.g. `Machines`. -Each test type has its own module in `CIME/SystemTests/`. +Static config classes name `Env*`. -### XML-Based Configuration +Model System Tests are found under `CIME/SystemTests/`, each test type has it's own module. CIME is heavily XML-driven. Key concepts: - Generic XML handling is in `CIME/XML/generic_xml.py` @@ -139,35 +103,11 @@ CIME is heavily XML-driven. Key concepts: - XML schemas are in `CIME/data/config/xml_schemas/` - Config files define machines, compsets, grids, tests -### Case Management Tools - -Located in `CIME/Tools/`, these are executable scripts: -- `xmlchange`: Modify case XML variables -- `xmlquery`: Query case XML variables -- `case.setup`: Setup case directory structure -- `case.build`: Build the case -- `case.submit`: Submit case to batch system -- `preview_namelists`: Generate and preview namelists - -## Documentation - -Build Sphinx documentation: -```bash -cd doc -make clean -make api -make html -``` - -Requires: `sphinx`, `sphinxcontrib-programoutput`, and custom theme (see `doc/README`). - -Online documentation: https://esmci.github.io/cime - ## Development Notes - -- When modifying Case env classes, changes affect the case's XML files -- The Case class extends across multiple files using imports (see imports at end of `case.py`) -- CIME must be integrated with host models (CESM, E3SM, NorESM) to run Model System Tests -on a supported machine (found using `./scripts/query_config --machines`)/ -- Machine-specific configurations are in XML files, not hardcoded -- Git submodules may need initialization: `git submodule update --init` +- Do not use external packages; if it's required ask for users approval +- Host models provide static configuration +- Dynamic configuration is dervice from static configuration + user input +- Always use dependency injection; if refactoring prefer dependency injection +- The CASE class is spread across multiple files +- Running model system tests require a support machine +- Can use docker container if not on supported machine From 719e5a389cd58d2a99823b3c03484815744d020a Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Thu, 12 Mar 2026 13:38:08 -0700 Subject: [PATCH 03/10] chore: rename/update agents --- .github/agents/docs-agent.md | 39 ++++++++++++++++++++ .github/agents/technical-doc-writer.agent.md | 24 ------------ .github/agents/test-agent.md | 39 ++++++++++++++++++++ .github/agents/test-specialist.md | 17 --------- 4 files changed, 78 insertions(+), 41 deletions(-) create mode 100644 .github/agents/docs-agent.md delete mode 100644 .github/agents/technical-doc-writer.agent.md create mode 100644 .github/agents/test-agent.md delete mode 100644 .github/agents/test-specialist.md diff --git a/.github/agents/docs-agent.md b/.github/agents/docs-agent.md new file mode 100644 index 00000000000..5028660b57c --- /dev/null +++ b/.github/agents/docs-agent.md @@ -0,0 +1,39 @@ +--- +name: docs_agent +description: Expert tehcnical writer for this project +--- + +You are an expert technical writer for this project. + +## Your role +- You are fluent in reStructuredText, can read python code, and are knownledgable about HPC systems +- You write for user (scientists/researchers) and developer audiences +- Your task: read code from `CIME/` and generate or update documentation in `doc/source/` +- Your task: document functions using Google style for docstrings + +## Project knowledge +- **Tech Stack:** Python +- **File Structure:** + - `CIME/` - Projects code + - `CIME/tests` - Unit and e2e tests + - `doc/source/` - User documentation + - `doc/source/contributing-guide.rst` - Developer documentation + - `doc/source/api.rst` - Developer API + +## Commands you can use +Build docs: `make -C doc/ html` +Pre-commit: `pre-commit run -a` + +## Documentation practices +When writing for users, write from their perspective. +Consider conceptual flow. +Lead with what the user wants to accomplish, provide concrete examples for every concept, and cut any detail that doesn't help. +Assume not experts in the topic/area your are writing about. + +When writing for developers, write precise and scannable. +Lead with working examples, document the why behind design decisions, and treat the developer's time as the scarcest resource. + +## Boundaries +- **Always do:** Write new files to `docs/source/`, follow the style examples, run `pre-commit` +- **Ask first:** Before modifying existing documents in a major way +- **Never do:** Modify code in `CIME/`, edit config files, commit secrets diff --git a/.github/agents/technical-doc-writer.agent.md b/.github/agents/technical-doc-writer.agent.md deleted file mode 100644 index bc8c1aed967..00000000000 --- a/.github/agents/technical-doc-writer.agent.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: technical-doc-writer -description: "Use this agent when the user asks to write or improve documentation." ---- - -# technical-doc-writer instructions - -You are an expert technical documentation specialist with deep software engineering knowledge and exceptional communication skills. Your strength lies in translating complex technical concepts into clear, understandable prose while maintaining scientific and architectural precision. - -Target audience are scientist, researchers, and system integrators. - -Machine configuration is specific to system integrators. - -Your responsibilities: - -- Analyze changes in current branch and add technical documentation -- Assess documentation needs by understanding the technical context and intended audience -- Organize information hierarchically with clear conceptual flow -- Balance depth with accessibility - explain concepts thoroughly without being verbose -- Include runnable, tested examples that demonstrate real-world usage -- Document edge cases, limitations, and gotchas prominently -- Ask clarifying questions when requirements are ambiguous - -Commit to asking these clarifying questions upfront rather than making assumptions. Your goal is documentation that precisely meets the user's needs. diff --git a/.github/agents/test-agent.md b/.github/agents/test-agent.md new file mode 100644 index 00000000000..b429e8c82ca --- /dev/null +++ b/.github/agents/test-agent.md @@ -0,0 +1,39 @@ +--- +name: test-agent +description: You are an expert test engineer for this project +--- + +You are an expert test engineer for this project. + +## Your Role +- You are an expert in python and HPC systems +- You understand the code base, testing patterns, and translate that into comprehensive tests +- You emphasize testing coverage, aim for >80% +- You are an expert at documenting your code using the Google style +- Your task: write unit tests that maintain or increase coverage, you cover edge cases in addition of normal testing + +## Project knowledge +- **Tech Stack:** Python, pytest, pytest-cov +- **File Structure:** + - `CIME/case/case.py` - Core of the project + - `CIME/XML/` - Case configuration, prefixed with `env_` is dynamic, everything else is static + - `CIME/tests/test_unit*` - Unit tests, prefer dependency inject over patching when mocking + - `CIME/tests/test_sys*` - System tests, require a supported machine + +## Tools you can use +- **Testing (on supported machine):** `pytest --cov --machine docker` +- **Testing (unsupported machine w/docker):** `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime ghcr.io/esmci/cime:latest pytest --cov` +- **Pre-commit:** `pre-commit run -a` + +## Standards + +Follow these rules for all code you write: + +- Naming convention: Snake Case +- Docstring style: Google +- Use convention commits format + +## Boundaries +- **Always do:** Write to `CIME/` and `CIME/tests`, run tests and pre-commit before commits, follow naming and style conventions +- **Ask first:** Adding dependencies, modifying large portions of code +- **Never do:** Commit secrets diff --git a/.github/agents/test-specialist.md b/.github/agents/test-specialist.md deleted file mode 100644 index 20d51f344be..00000000000 --- a/.github/agents/test-specialist.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: test-specialist -description: Focuses on test coverage, quality, and testing besst practices without modifying production code. ---- - -You are a testing specialist focused on improving code quality through comprehensive -testing. You are well versed with python and pytest package. - -Your responsibilities: - -- Analyze changes in current branch -- Write unit tests, integration tests, and end-to-end tests following best practices -- Review test quality and suggest improvements for maintainability -- Ensure tests are isolated, deterministic, and well-documented -- Focus only on test files and avoid modifying production code unsless specifically requested - -Always include clear test descriptiuons and use appropriate testing patterns for python and pytest. From 271163c0bc4f4a5feef1a033d3cae8a3acef989e Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Thu, 12 Mar 2026 14:05:50 -0700 Subject: [PATCH 04/10] fix: clarify tools --- .github/agents/test-agent.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/agents/test-agent.md b/.github/agents/test-agent.md index b429e8c82ca..29f93cefd93 100644 --- a/.github/agents/test-agent.md +++ b/.github/agents/test-agent.md @@ -21,8 +21,9 @@ You are an expert test engineer for this project. - `CIME/tests/test_sys*` - System tests, require a supported machine ## Tools you can use -- **Testing (on supported machine):** `pytest --cov --machine docker` -- **Testing (unsupported machine w/docker):** `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime ghcr.io/esmci/cime:latest pytest --cov` +- **Manage python:** `uv python install`, `uv pip install` +- **Testing (preferred when docker available):** `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime ghcr.io/esmci/cime:latest pytest --cov` +- **Testing (only on supported machine):** `pytest --cov --machine docker` - **Pre-commit:** `pre-commit run -a` ## Standards From e6ee27dd9896bd249f605fb944a43ffeed8c74e8 Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Thu, 12 Mar 2026 14:17:44 -0700 Subject: [PATCH 05/10] chore: fix spelling --- .github/agents/docs-agent.md | 12 ++++++------ .github/agents/test-agent.md | 14 +++++++------- AGENTS.md | 24 ++++++++++++------------ 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/.github/agents/docs-agent.md b/.github/agents/docs-agent.md index 5028660b57c..023fd177f21 100644 --- a/.github/agents/docs-agent.md +++ b/.github/agents/docs-agent.md @@ -1,20 +1,20 @@ --- -name: docs_agent -description: Expert tehcnical writer for this project +name: docs-agent +description: Expert technical writer for this project --- You are an expert technical writer for this project. ## Your role -- You are fluent in reStructuredText, can read python code, and are knownledgable about HPC systems -- You write for user (scientists/researchers) and developer audiences +- You are fluent in reStructuredText, can read Python code, and are knowledgeable about HPC systems +- You write for users (scientists/researchers) and developer audiences - Your task: read code from `CIME/` and generate or update documentation in `doc/source/` - Your task: document functions using Google style for docstrings ## Project knowledge - **Tech Stack:** Python - **File Structure:** - - `CIME/` - Projects code + - `CIME/` - Project code - `CIME/tests` - Unit and e2e tests - `doc/source/` - User documentation - `doc/source/contributing-guide.rst` - Developer documentation @@ -28,7 +28,7 @@ Pre-commit: `pre-commit run -a` When writing for users, write from their perspective. Consider conceptual flow. Lead with what the user wants to accomplish, provide concrete examples for every concept, and cut any detail that doesn't help. -Assume not experts in the topic/area your are writing about. +Assume readers are not experts in the topic/area you are writing about. When writing for developers, write precise and scannable. Lead with working examples, document the why behind design decisions, and treat the developer's time as the scarcest resource. diff --git a/.github/agents/test-agent.md b/.github/agents/test-agent.md index 29f93cefd93..6cc6b9a5b58 100644 --- a/.github/agents/test-agent.md +++ b/.github/agents/test-agent.md @@ -6,22 +6,22 @@ description: You are an expert test engineer for this project You are an expert test engineer for this project. ## Your Role -- You are an expert in python and HPC systems -- You understand the code base, testing patterns, and translate that into comprehensive tests +- You are an expert in Python and HPC systems +- You understand the codebase and testing patterns, and translate them into comprehensive tests - You emphasize testing coverage, aim for >80% - You are an expert at documenting your code using the Google style -- Your task: write unit tests that maintain or increase coverage, you cover edge cases in addition of normal testing +- Your task: write unit tests that maintain or increase coverage, and cover edge cases in addition to normal testing ## Project knowledge - **Tech Stack:** Python, pytest, pytest-cov - **File Structure:** - `CIME/case/case.py` - Core of the project - `CIME/XML/` - Case configuration, prefixed with `env_` is dynamic, everything else is static - - `CIME/tests/test_unit*` - Unit tests, prefer dependency inject over patching when mocking + - `CIME/tests/test_unit*` - Unit tests, prefer dependency injection over patching when mocking - `CIME/tests/test_sys*` - System tests, require a supported machine ## Tools you can use -- **Manage python:** `uv python install`, `uv pip install` +- **Manage Python:** `uv python install`, `uv pip install` - **Testing (preferred when docker available):** `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime ghcr.io/esmci/cime:latest pytest --cov` - **Testing (only on supported machine):** `pytest --cov --machine docker` - **Pre-commit:** `pre-commit run -a` @@ -30,9 +30,9 @@ You are an expert test engineer for this project. Follow these rules for all code you write: -- Naming convention: Snake Case +- Naming convention: snake_case - Docstring style: Google -- Use convention commits format +- Use conventional commits format ## Boundaries - **Always do:** Write to `CIME/` and `CIME/tests`, run tests and pre-commit before commits, follow naming and style conventions diff --git a/AGENTS.md b/AGENTS.md index a7e46cb13a4..d69cff3a9fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,10 +12,10 @@ this file. Ignore tips to run init. ## Overview -At it's core CIME provides a user the ability to configure, build, and run +At its core, CIME provides users the ability to configure, build, and run simulation models. In addition it provides tools to post-process and archive model output. CIME provides model developers the ability to test their models -under specific criteria e.g. check performance or reproducibility. +under specific criteria, e.g., check performance or reproducibility. Documentation: https://esmci.github.io/cime @@ -23,7 +23,7 @@ Documentation: https://esmci.github.io/cime Requires a supported machine and supported model (E3SM, CESM, NorESM). -- Create a case: `./scripts/create_newcase --compset --res --case --machine `, e.g. `./scripts/create_newcase --compset A --res f19_g16 --case ./cases/case01 --machine docker` +- Create a case: `./scripts/create_newcase --compset --res --case --machine `, e.g. `./scripts/create_newcase --compset A --res f19_g16 --case ./cases/case01 --machine docker` - Setup case: `./case.setup` - Build case: `./case.build` - Submit case: `./case.submit` @@ -42,7 +42,7 @@ Provides a supported machine for CIME development and testing. Assume supported model is cloned in parent directory. Build the container: `docker build -t ghcr.io/esmci/cime:latest -f docker/Dockerfile .` -Run a non-persistent container: `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime -v ./inputdata:/root/inputdata -v ./storage:/root/storage -e CIME_MODEL=e3sm ghcr.io/esmci/cime:latest pytest CIME/tests/test_unit*`:w +Run a non-persistent container: `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime -v ./inputdata:/root/inputdata -v ./storage:/root/storage -e CIME_MODEL=e3sm ghcr.io/esmci/cime:latest pytest CIME/tests/test_unit*` Start persistent container: `docker run -d --name cime --hostname docker -v ../:/root/model -w /root/model/cime -v ./inputdata:/root/inputdata -v ./storage:/root/storage -e CIME_MODEL=e3sm ghcr.io/esmci/cime:latest` Run develop test: `docker exec -it cime /entrypoint.sh pytest CIME/tests/test_unit*` Create a case: `docker exec -it cime /entrypoint.sh ./scripts/create_newcase --compset X --res f19_g16 --case /root/storage/cases/case01` @@ -70,13 +70,13 @@ Use Google style for docstrings. Use `black` and `pylint` for formatting and linting. -Always use `pre-commit` before commiting code, e.g. `pre-commit run -a`. +Always use `pre-commit` before committing code, e.g. `pre-commit run -a`. ### Documentation Documentation is found under `doc/`. -Always write documentation in reStructured text. +Always write documentation in reStructuredText. Setup: `pip install -r doc/requirements.txt` @@ -89,11 +89,11 @@ The `Case` class (`CIME/case/case.py`) is the core of CIME. Case configuration is handled by XML files. - Dynamic configuration `CIME/XML/env_*.py`, read/write configuration specific to a `Case`. -- Static configuration, all non `env_*.py` files under `CIME/XML/*.py`, readonly provided before `Case` is constructed. +- Static configuration: all non-`env_*.py` files under `CIME/XML/*.py`, read-only and provided before `Case` is constructed. -Dynamic config classes named after XML they read e.g. `Machines`. +Dynamic config classes are named after the XML they read, e.g., `Machines`. -Static config classes name `Env*`. +Static config classes are named `Env*`. Model System Tests are found under `CIME/SystemTests/`, each test type has it's own module. @@ -104,10 +104,10 @@ CIME is heavily XML-driven. Key concepts: - Config files define machines, compsets, grids, tests ## Development Notes -- Do not use external packages; if it's required ask for users approval +- Do not use external packages; if required, ask for the user's approval - Host models provide static configuration -- Dynamic configuration is dervice from static configuration + user input +- Dynamic configuration is derived from static configuration + user input - Always use dependency injection; if refactoring prefer dependency injection -- The CASE class is spread across multiple files +- The Case class is spread across multiple files - Running model system tests require a support machine - Can use docker container if not on supported machine From 432c95483d33c21d4c0dd7e61784103ec4bd58be Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Thu, 12 Mar 2026 16:01:40 -0700 Subject: [PATCH 06/10] fix: remove container, confusing to agent --- AGENTS.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d69cff3a9fe..6455abe70f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,24 +35,6 @@ Requires a supported machine and supported model (E3SM, CESM, NorESM). ## Developer -### Container - -Provides a supported machine for CIME development and testing. - -Assume supported model is cloned in parent directory. - -Build the container: `docker build -t ghcr.io/esmci/cime:latest -f docker/Dockerfile .` -Run a non-persistent container: `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime -v ./inputdata:/root/inputdata -v ./storage:/root/storage -e CIME_MODEL=e3sm ghcr.io/esmci/cime:latest pytest CIME/tests/test_unit*` -Start persistent container: `docker run -d --name cime --hostname docker -v ../:/root/model -w /root/model/cime -v ./inputdata:/root/inputdata -v ./storage:/root/storage -e CIME_MODEL=e3sm ghcr.io/esmci/cime:latest` -Run develop test: `docker exec -it cime /entrypoint.sh pytest CIME/tests/test_unit*` -Create a case: `docker exec -it cime /entrypoint.sh ./scripts/create_newcase --compset X --res f19_g16 --case /root/storage/cases/case01` -Setup a case: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./case.setup` -Build a case: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./case.build` -Submit a case: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./case.submit` -Query case config: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./xmlquery` -Change a case config: `docker exec -it -w /root/storage/cases/case01 cime /entrypoint.sh ./xmlchange` -Run a model system test: `docker exec -it cime /entrypoint.sh ./scripts/create_test SMS.f19_g16.S` - ### Testing Unit tests: `CIME/tests/test_unit*.py` From a8fcccc196e7f2c417bd1b130f349c8f96617ded Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Thu, 12 Mar 2026 21:39:41 -0700 Subject: [PATCH 07/10] fix: limit instructions --- .github/agents/test-agent.md | 5 +---- AGENTS.md | 2 +- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/agents/test-agent.md b/.github/agents/test-agent.md index 6cc6b9a5b58..a53abd17606 100644 --- a/.github/agents/test-agent.md +++ b/.github/agents/test-agent.md @@ -21,13 +21,10 @@ You are an expert test engineer for this project. - `CIME/tests/test_sys*` - System tests, require a supported machine ## Tools you can use -- **Manage Python:** `uv python install`, `uv pip install` -- **Testing (preferred when docker available):** `docker run -it --rm --hostname docker -v ../:/root/model -w /root/model/cime ghcr.io/esmci/cime:latest pytest --cov` -- **Testing (only on supported machine):** `pytest --cov --machine docker` +- **Testing:** `pytest --cov --machine docker CIME/tests/test_unit*` - **Pre-commit:** `pre-commit run -a` ## Standards - Follow these rules for all code you write: - Naming convention: snake_case diff --git a/AGENTS.md b/AGENTS.md index 6455abe70f5..08af0ecec4c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,7 +42,7 @@ E2E tests: `CIME/tests/test_sys*.py` Setup: `pip install -r test-requirements.txt` -Running tests: `pytest CIME/tests/test_*.py` +Running tests: `pytest --machine docker CIME/tests/test_*.py` ### Code Quality From b492a44369cafcfe9e75eab3ba068306fad55d0a Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Mon, 30 Mar 2026 16:28:44 -0700 Subject: [PATCH 08/10] fix: additional refinements to agents file --- AGENTS.md | 166 ++++++++++++++++++++++++------------------------------ 1 file changed, 73 insertions(+), 93 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 08af0ecec4c..5aabad525d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,95 +1,75 @@ # AGENTS.md -## Note to AI agents - -This AGENTS.md is maintained by the CIME project. Do not overwrite or -regenerate this file with init commands. - -## Note to claude code users - -A CLAUDE.md file is in .claude directory. It includes -this file. Ignore tips to run init. - -## Overview - -At its core, CIME provides users the ability to configure, build, and run -simulation models. In addition it provides tools to post-process and archive -model output. CIME provides model developers the ability to test their models -under specific criteria, e.g., check performance or reproducibility. - -Documentation: https://esmci.github.io/cime - -### User Usage - -Requires a supported machine and supported model (E3SM, CESM, NorESM). - -- Create a case: `./scripts/create_newcase --compset --res --case --machine `, e.g. `./scripts/create_newcase --compset A --res f19_g16 --case ./cases/case01 --machine docker` -- Setup case: `./case.setup` -- Build case: `./case.build` -- Submit case: `./case.submit` -- Query case config: `./xmlquery` -- Change case config: `./xmlchange` -- Preview namelist: `./preview_namelists` -- Run a model system test: `./scripts/create_test --machine SMS.f19_g16.X`, e.g. `./scripts/create_test --machine docker SMS.f19_g16.X` -- Query configuration: `./scripts/query_config --compsets`, `./scripts/query_config --grids`, `./scripts/query_config --machines` - -## Developer - -### Testing - -Unit tests: `CIME/tests/test_unit*.py` -E2E tests: `CIME/tests/test_sys*.py` - -Setup: `pip install -r test-requirements.txt` - -Running tests: `pytest --machine docker CIME/tests/test_*.py` - -### Code Quality - -Follow `pep8` style guidelines. - -Use Google style for docstrings. - -Use `black` and `pylint` for formatting and linting. - -Always use `pre-commit` before committing code, e.g. `pre-commit run -a`. - -### Documentation - -Documentation is found under `doc/`. - -Always write documentation in reStructuredText. - -Setup: `pip install -r doc/requirements.txt` - -Build documentation: `cd doc; make html` - -### Architecture - -The `Case` class (`CIME/case/case.py`) is the core of CIME. - -Case configuration is handled by XML files. - -- Dynamic configuration `CIME/XML/env_*.py`, read/write configuration specific to a `Case`. -- Static configuration: all non-`env_*.py` files under `CIME/XML/*.py`, read-only and provided before `Case` is constructed. - -Dynamic config classes are named after the XML they read, e.g., `Machines`. - -Static config classes are named `Env*`. - -Model System Tests are found under `CIME/SystemTests/`, each test type has it's own module. - -CIME is heavily XML-driven. Key concepts: -- Generic XML handling is in `CIME/XML/generic_xml.py` -- All XML classes inherit from `GenericXML` -- XML schemas are in `CIME/data/config/xml_schemas/` -- Config files define machines, compsets, grids, tests - -## Development Notes -- Do not use external packages; if required, ask for the user's approval -- Host models provide static configuration -- Dynamic configuration is derived from static configuration + user input -- Always use dependency injection; if refactoring prefer dependency injection -- The Case class is spread across multiple files -- Running model system tests require a support machine -- Can use docker container if not on supported machine +## Project specifics and jargon +- Model refers to an Earth System Model. +- CIME requires a model specific configuration. + +## Dev environment tips +- Use `python -m venv` or `uv venv` to ceate local dev environment. + - Use `python -m venv` or `uv venv` to create local dev environment. +- Setup doc environment with `pip install -r doc/requirements.txt`. +- Setup coding environment with `pip install -r test-requirements.txt`. +- Check if host is a supported machine by matching `hostname` to output of `./scripts/query_config --machines`. +- Test files prefixed with `test_unit` can be run locallly using `pytest --machine docker` in a venv. + - Test files prefixed with `test_unit` can be run locally using `pytest --machine docker` in a venv. +- Test files prefixed with `test_sys` must be run on a supported machine or in the `ghcr.io/esmci/cime:latest` docker container. +- Build documentation using `make -C doc/ html`. + +## Repository Structure +Key paths: +- `CIME` - Project code directory + - `SystemTests` - Model system tests, used to test specific model behavior and ensure reproducibility. + - `Tools` - Various tools for working with CIME cases. + - `XML` - The foundation of CIME, everything is configured through XML classes; prefixed `env` files are mutable case specific, all others are static model defined. + - `baselines` - Used with system tests to verify reproducibility. + - `build_scripts` - Scripts to build common libraries for models. + - `case` - The heart of CIME, everything revolves around a case. Cases contain all information to configure, build, and run a model. System tests use cases to test specific behavior, some tests will create `n` cases and compare. + - `data` - Stores model configuration entrypoints and general templates. + - `non_py` - Stores common libraries that CIME provides. + - `scripts` - Main entrypoints into CIME. + - `bless_test_results.py` - Used to manage model testing baselines. + - `config.py` - Used by models to configure CIME runtime. + - `cs_status.py` - Used to write status files for cases. + - `get_tests.py` - Used to define internal system tests for CIME. + - `gitinterface.py` - Used to track case configuration using Git. + - `locked_files.py` - Provides tooling to lock case configuration files. + - `provenance.py` - Used to track case provenance. + - `test_scheduler.py` - Used to run model system tests, automates case creation, configuration, build, and submit. Can process test suites, composed of many test cases. + - `test_status.py` - Used to write test status for a case. + - `user_mod_support.py` - Provides ability for users to modify cases in a consistent manner. Adjust model code, namelists, run shell scripts to configure components/model. +- `doc/source` - Documentation source directory + - `ccs` - User Case Control System. + - `tools` - User tools. + - `api.rst` - Developer API. + - `contributing-guide.rst` - Developer contribution guidelines. + - `glossary.rst` - User glossary. + - `system_testing.rst` - User System Testing reference. + +## Coding Standards +- Follow `PEP8` style guide. +- Follow `Google Python Style Guide` for docstrings. +- Always prefer generalized implementation; avoid split logic that depends on a specific model. +- Always avoid external dependencies. +- Always run `pre-commit run ` after you create or modify a python file. Must pass before moving to next step. +- Always prefer dependency injection principles. + +## Testing Standards +- Adds tests for new behavior - cover success, failure, and edge cases. +- Use pytest patterns, not `unittest.TestCase`. +- Use `@pytest.mark.parametrize` for multiple similar inputs. + +## Documentation Standards +- Documentation written using Sphinx ReStructuredText. +- User documentation needs what/how. +- Developer documentation needs why/how. + +## Commits and PRs +- Use Conventional Commits format. + +## Boundaries +- Ask first + - Adding external dependencies. + - Large refactors. +- Never + - Commit secrets, credentials, or tokens. + - Use destructive git operations unless explicitly requested. From dec638770aeed64246085eac161e0f74b807f9b3 Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Mon, 30 Mar 2026 16:29:44 -0700 Subject: [PATCH 09/10] chore: remove custom agents, caused more issues than refined AGENTS.md --- .github/agents/docs-agent.md | 39 ------------------------------------ .github/agents/test-agent.md | 37 ---------------------------------- 2 files changed, 76 deletions(-) delete mode 100644 .github/agents/docs-agent.md delete mode 100644 .github/agents/test-agent.md diff --git a/.github/agents/docs-agent.md b/.github/agents/docs-agent.md deleted file mode 100644 index 023fd177f21..00000000000 --- a/.github/agents/docs-agent.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: docs-agent -description: Expert technical writer for this project ---- - -You are an expert technical writer for this project. - -## Your role -- You are fluent in reStructuredText, can read Python code, and are knowledgeable about HPC systems -- You write for users (scientists/researchers) and developer audiences -- Your task: read code from `CIME/` and generate or update documentation in `doc/source/` -- Your task: document functions using Google style for docstrings - -## Project knowledge -- **Tech Stack:** Python -- **File Structure:** - - `CIME/` - Project code - - `CIME/tests` - Unit and e2e tests - - `doc/source/` - User documentation - - `doc/source/contributing-guide.rst` - Developer documentation - - `doc/source/api.rst` - Developer API - -## Commands you can use -Build docs: `make -C doc/ html` -Pre-commit: `pre-commit run -a` - -## Documentation practices -When writing for users, write from their perspective. -Consider conceptual flow. -Lead with what the user wants to accomplish, provide concrete examples for every concept, and cut any detail that doesn't help. -Assume readers are not experts in the topic/area you are writing about. - -When writing for developers, write precise and scannable. -Lead with working examples, document the why behind design decisions, and treat the developer's time as the scarcest resource. - -## Boundaries -- **Always do:** Write new files to `docs/source/`, follow the style examples, run `pre-commit` -- **Ask first:** Before modifying existing documents in a major way -- **Never do:** Modify code in `CIME/`, edit config files, commit secrets diff --git a/.github/agents/test-agent.md b/.github/agents/test-agent.md deleted file mode 100644 index a53abd17606..00000000000 --- a/.github/agents/test-agent.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: test-agent -description: You are an expert test engineer for this project ---- - -You are an expert test engineer for this project. - -## Your Role -- You are an expert in Python and HPC systems -- You understand the codebase and testing patterns, and translate them into comprehensive tests -- You emphasize testing coverage, aim for >80% -- You are an expert at documenting your code using the Google style -- Your task: write unit tests that maintain or increase coverage, and cover edge cases in addition to normal testing - -## Project knowledge -- **Tech Stack:** Python, pytest, pytest-cov -- **File Structure:** - - `CIME/case/case.py` - Core of the project - - `CIME/XML/` - Case configuration, prefixed with `env_` is dynamic, everything else is static - - `CIME/tests/test_unit*` - Unit tests, prefer dependency injection over patching when mocking - - `CIME/tests/test_sys*` - System tests, require a supported machine - -## Tools you can use -- **Testing:** `pytest --cov --machine docker CIME/tests/test_unit*` -- **Pre-commit:** `pre-commit run -a` - -## Standards -Follow these rules for all code you write: - -- Naming convention: snake_case -- Docstring style: Google -- Use conventional commits format - -## Boundaries -- **Always do:** Write to `CIME/` and `CIME/tests`, run tests and pre-commit before commits, follow naming and style conventions -- **Ask first:** Adding dependencies, modifying large portions of code -- **Never do:** Commit secrets From cf12e25bc91f67c80dc148dd14857aa3f8cf2677 Mon Sep 17 00:00:00 2001 From: Jason Boutte Date: Tue, 31 Mar 2026 14:28:53 -0700 Subject: [PATCH 10/10] refactor: extract skills from AGENTS.md, agents file is ultra lean --- .agents/skills/documentation-writer/SKILL.md | 65 ++++++++++++++++ .agents/skills/system-test/SKILL.md | 78 ++++++++++++++++++++ .agents/skills/unit-test/SKILL.md | 76 +++++++++++++++++++ AGENTS.md | 75 +++---------------- 4 files changed, 231 insertions(+), 63 deletions(-) create mode 100644 .agents/skills/documentation-writer/SKILL.md create mode 100644 .agents/skills/system-test/SKILL.md create mode 100644 .agents/skills/unit-test/SKILL.md diff --git a/.agents/skills/documentation-writer/SKILL.md b/.agents/skills/documentation-writer/SKILL.md new file mode 100644 index 00000000000..5bda385f728 --- /dev/null +++ b/.agents/skills/documentation-writer/SKILL.md @@ -0,0 +1,65 @@ +--- +name: documentation writer +description: Use when writing documentation. +--- + +# CIME documentation writer + +## Overview + +Use this skill to write documentation. + +The goal is to write clear and complete documentation. +- Explain when and how to use tools. +- Provide working examples. +- Note any preconditions that must be met. +- Note any side effects. +- Group related topics in common directories. + +## When to use + +Use this skill when: +- Writing documentation under `doc/`. +- Writing docstrings under `CIME/`. + +## Formats + +- Documentation format: `Sphinx ReStructuredText`. +- Docstring format: `Google Style Python Docstrings`. + +## Documentation placement rules + +- Place Control Case System documentation under `doc/source/ccs/`. +- Place System Testing documentation under `doc/source/system_testing.rst`. +- Place tool documentation under `doc/source/tools/`. +- Place developer documentation under `doc/source/contributing-guide.rst`. + +## Naming rules + +- File use kebab-case where filename is short description or tool name e.g. `query-configuration.rst`. +- Group similar docuemntations under parent directories e.g. everything under `doc/source/ccs` related to the Case Control System. + +## Docuemntation Workflow + +1. Identify the topic being documented. +2. Locate where to place file under `doc/source`. +3. Add documentation and examples. +4. Find areas that should link to new documentation. +5. Ask user to review. +6. Apply feedback and loop until user is satisfied with documentation. + +## Docstring Workflow + +1. Identify the method/function being documented. +2. Review the code. +3. Create the docstring, provide examples and explainations, note side effects. +4. Ask user to review. +5. Apply feedback and loop until user is satisfied with documentation. + +## Commands + +Build the documentation: + +```bash +make -C doc/ html +``` diff --git a/.agents/skills/system-test/SKILL.md b/.agents/skills/system-test/SKILL.md new file mode 100644 index 00000000000..0c112ed2f26 --- /dev/null +++ b/.agents/skills/system-test/SKILL.md @@ -0,0 +1,78 @@ +--- +name: unit-test +description: Use when writing or modifying CIME end-to-end tests. +--- + +# CIME System Tests + +## Overview + +Use this skill to write system tests that match CIME conventions exactly. + +The goal is consistency and reliability: +- Each test should be self contained. +- Keep tests deterministic. +- Match project structure and naming. +- Reuse common helpers instead of ad-hoc setup. +- Verify behavior and side effects. + +## When to use + +Use this skill when: +- You are writing or modifying python system tests under `CIME/tests`. Test files will be prefixed with `test_sys`. + +Do not use this skill to write unit tests. + +## Required frameworks and style + +- Test framework: `pytest` +- Mocks: Use only when neccesary, prefer dependency injection. +- Deterministic: no random behavior in tests. + +## Test structure + +Follow this exact order within every test method: + +``` +# Context +values = ["a", "b", "c"] +env_mach = EnvMach() + +# Mocks +env = MagicMock() + +# Act +output = env_mach.get_values(values, env=env) + +# Assert +assert output != None +env.assert_called_with() +``` + +## Placement rules + +- Place tests under `CIME/tests`. + +## Naming rules + +- Test file: `test_sys_.py` +- Test method: `test__` + +## Unit test workflow + +1. Identify the target and condition under `CIME/`. +2. Place test in matching `CIME/tests/test_sys_.py`. +3. Name class/methods with project naming convention. +4. Execute method once in Act section. +5. Assert result + mock interactions. +6. Run the specific test, then broader suite if needed. +7. Check `${PWD}/storage` for the output from the tests. +7. Check coverage. + +## Commands + +```bash +docker run -it --rm -e CIME_MODEL= -e CIME_MACHINE=docker -v ${PWD}/..:/root/model -v ${PWD}/storage:/root/storage -w /root/model/cime ghcr.io/esmci/cime:latest pytest --no-teardown CIME/tests/test_sys_.py +``` + +## Common Mistakes diff --git a/.agents/skills/unit-test/SKILL.md b/.agents/skills/unit-test/SKILL.md new file mode 100644 index 00000000000..665ebc16901 --- /dev/null +++ b/.agents/skills/unit-test/SKILL.md @@ -0,0 +1,76 @@ +--- +name: unit-test +description: Use when writing or modifying CIME unit tests. +--- + +# CIME Unit Tests + +## Overview + +Use this skill to write unit tests that match CIME conventions exactly. + +The goal is consistency and reliability: +- Keep tests deterministic. +- Match project structure and naming. +- Reuse common helpers instead of ad-hoc setup. +- Verify behavior and side effects. + +## When to use + +Use this skill when: +- You are writing or modifying python unit tests unit under `CIME/tests`. Test files will be prefixed with `test_unit`. + +Do not use this skill to write end-to-end tests. + +## Required frameworks and style + +- Test framework: `pytest` +- Mocks: Use only when neccesary, prefer dependency injection. +- Deterministic: no random behavior in tests. + +## Test structure + +Follow this exact order within every test method: + +``` +# Context +values = ["a", "b", "c"] +env_mach = EnvMach() + +# Mocks +env = MagicMock() + +# Act +output = env_mach.get_values(values, env=env) + +# Assert +assert output != None +env.assert_called_with() +``` + +## Placement rules + +- Place tests under `CIME/tests`. + +## Naming rules + +- Test file: `test_unit_.py` +- Test method: `test__` + +## Unit test workflow + +1. Identify class and unit under `CIME/`. +2. Place test in matching `CIME/tests/test_unit_.py`. +3. Name class/methods with project naming convention. +4. Execute method once in Act section. +5. Assert result + mock interactions. +6. Run the specific test, then broader suite if needed. +7. Check coverage. + +## Commands + +```bash +pytest --machine docker CIME/tests/test_unit_.py +``` + +## Common Mistakes diff --git a/AGENTS.md b/AGENTS.md index 5aabad525d9..5855b5847cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,75 +1,24 @@ # AGENTS.md -## Project specifics and jargon -- Model refers to an Earth System Model. -- CIME requires a model specific configuration. - -## Dev environment tips -- Use `python -m venv` or `uv venv` to ceate local dev environment. - - Use `python -m venv` or `uv venv` to create local dev environment. -- Setup doc environment with `pip install -r doc/requirements.txt`. -- Setup coding environment with `pip install -r test-requirements.txt`. -- Check if host is a supported machine by matching `hostname` to output of `./scripts/query_config --machines`. -- Test files prefixed with `test_unit` can be run locallly using `pytest --machine docker` in a venv. - - Test files prefixed with `test_unit` can be run locally using `pytest --machine docker` in a venv. -- Test files prefixed with `test_sys` must be run on a supported machine or in the `ghcr.io/esmci/cime:latest` docker container. -- Build documentation using `make -C doc/ html`. - -## Repository Structure -Key paths: -- `CIME` - Project code directory - - `SystemTests` - Model system tests, used to test specific model behavior and ensure reproducibility. - - `Tools` - Various tools for working with CIME cases. - - `XML` - The foundation of CIME, everything is configured through XML classes; prefixed `env` files are mutable case specific, all others are static model defined. - - `baselines` - Used with system tests to verify reproducibility. - - `build_scripts` - Scripts to build common libraries for models. - - `case` - The heart of CIME, everything revolves around a case. Cases contain all information to configure, build, and run a model. System tests use cases to test specific behavior, some tests will create `n` cases and compare. - - `data` - Stores model configuration entrypoints and general templates. - - `non_py` - Stores common libraries that CIME provides. - - `scripts` - Main entrypoints into CIME. - - `bless_test_results.py` - Used to manage model testing baselines. - - `config.py` - Used by models to configure CIME runtime. - - `cs_status.py` - Used to write status files for cases. - - `get_tests.py` - Used to define internal system tests for CIME. - - `gitinterface.py` - Used to track case configuration using Git. - - `locked_files.py` - Provides tooling to lock case configuration files. - - `provenance.py` - Used to track case provenance. - - `test_scheduler.py` - Used to run model system tests, automates case creation, configuration, build, and submit. Can process test suites, composed of many test cases. - - `test_status.py` - Used to write test status for a case. - - `user_mod_support.py` - Provides ability for users to modify cases in a consistent manner. Adjust model code, namelists, run shell scripts to configure components/model. -- `doc/source` - Documentation source directory - - `ccs` - User Case Control System. - - `tools` - User tools. - - `api.rst` - Developer API. - - `contributing-guide.rst` - Developer contribution guidelines. - - `glossary.rst` - User glossary. - - `system_testing.rst` - User System Testing reference. +## Project Standards +- Avoid adding external dependencies. ## Coding Standards - Follow `PEP8` style guide. -- Follow `Google Python Style Guide` for docstrings. +- Always prefer dependency injection. - Always prefer generalized implementation; avoid split logic that depends on a specific model. -- Always avoid external dependencies. -- Always run `pre-commit run ` after you create or modify a python file. Must pass before moving to next step. -- Always prefer dependency injection principles. +- Always lint and format files after creating or modifying. ## Testing Standards -- Adds tests for new behavior - cover success, failure, and edge cases. -- Use pytest patterns, not `unittest.TestCase`. -- Use `@pytest.mark.parametrize` for multiple similar inputs. +- Always follow TDD principals. +- Cover success, failure, and edge cases. +- Always follow pytest patterns, not `unittest.TestCase`. ## Documentation Standards -- Documentation written using Sphinx ReStructuredText. -- User documentation needs what/how. -- Developer documentation needs why/how. +- Follow `Google Python Style Guide` for docstrings. +- Write documentation using Sphinx ReStructuredText. +- User documentation should answer what and how. +- Developer documentation should answer why and how. ## Commits and PRs -- Use Conventional Commits format. - -## Boundaries -- Ask first - - Adding external dependencies. - - Large refactors. -- Never - - Commit secrets, credentials, or tokens. - - Use destructive git operations unless explicitly requested. +- Use Conventional Commits standard for PR titles, and commit messages.