Ts/vendor dev guides

.github/workflows/update_dev_guides.yml

@@ -0,0 +1,97 @@
+# Drop this file into a consumer repo at `.github/workflows/update_dev_guides.yml`.
+# It pulls the latest DeveloperGuides into `docs/dev-guides/` via `git subtree`
+# on the 1st of every month and opens a PR when there are changes.
+#
+# Prerequisites:
+#   - DeveloperGuides has already been added as a subtree at `docs/dev-guides/`:
+#       git subtree add --prefix docs/dev-guides \
+#           https://github.com/CliMA/DeveloperGuides.git main --squash
+#   - The repo's GitHub Actions are allowed to open pull requests
+#     (Settings → Actions → General → "Allow GitHub Actions to create and
+#     approve pull requests").
+#
+# Important:
+#   - PRs that touch the subtree merge metadata (the initial `subtree add` and
+#     all subsequent sync PRs) MUST be merged with a merge commit — never
+#     squash-merged. Squash-merging destroys the two-parent commit structure
+#     that `git subtree pull` relies on, causing future pulls to fail with
+#     "fatal: can't squash-merge: 'docs/dev-guides' was never added."
+#     If this has already happened, the fix is to remove and re-add the subtree:
+#       git rm -r docs/dev-guides && git commit -m "remove broken subtree"
+#       git subtree add --prefix docs/dev-guides \
+#           https://github.com/CliMA/DeveloperGuides.git main --squash
+
+name: Update Dev Guides
+on:
+  schedule:
+    # 1st of every month at 03:07 UTC. An off-peak, off-the-hour time reduces
+    # the scheduler delay that GitHub applies to popular slots like 00:00.
+    - cron: '7 3 1 * *'
+  workflow_dispatch:
+
+jobs:
+  update-subtree:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # Full history is required for subtree pull
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Pull latest dev guides
+        id: pull
+        run: |
+          before=$(git rev-parse HEAD)
+          git checkout -b update-dev-guides
+          # Capture the result so we can tell "nothing new to merge" (benign)
+          # apart from a real failure (merge conflict, broken subtree metadata,
+          # network error). A blanket `|| true` would hide those and let the
+          # workflow report success while silently never syncing again.
+          set +e
+          out=$(git subtree pull --prefix docs/dev-guides \
+                    https://github.com/CliMA/DeveloperGuides.git main --squash \
+                    -m "chore: sync dev guides from central repo" 2>&1)
+          status=$?
+          set -e
+          echo "$out"
+          if [ "$status" -ne 0 ] && ! echo "$out" | grep -qiE "up.to.date|already at commit"; then
+            echo "::error::git subtree pull failed — see log above."
+            exit 1
+          fi
+          # A new commit means the subtree advanced, i.e. there are changes.
+          if [ "$before" != "$(git rev-parse HEAD)" ]; then
+            echo "changes=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changes=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create Pull Request
+        if: steps.pull.outputs.changes == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git push -f origin update-dev-guides
+          existing=$(gh pr list --head update-dev-guides --state open --json number --jq '.[0].number')
+          if [ -n "$existing" ]; then
+            echo "PR #$existing already exists — skipping creation."
+          else
+            # Build the body with printf so the alert lands on its own lines.
+            # (A double-quoted "\n" is a literal backslash-n to gh, not a newline.)
+            printf '%s\n' \
+              'Automated PR to sync `docs/dev-guides` with the latest changes from `CliMA/DeveloperGuides`.' \
+              '' \
+              '> [!CAUTION]' \
+              '> **Merge with a merge commit, NOT with squash merge.** Squash-merging destroys the subtree metadata and breaks future syncs.' \
+              > "$RUNNER_TEMP/pr-body.md"
+            gh pr create --title "chore: sync dev guides with central repo" \
+                         --body-file "$RUNNER_TEMP/pr-body.md" \
+                         --base "${{ github.event.repository.default_branch }}" \
+                         --head update-dev-guides
+          fi

AGENTS.md

@@ -0,0 +1,34 @@
+# RRTMGP.jl Agent Guide
+
+## Ecosystem Guidelines
+
+Please refer to the shared CliMA agent index for ecosystem-wide rules regarding architecture, performance, code quality, infrastructure, and workflows:
+
+- [docs/dev-guides/AGENTS.md](docs/dev-guides/AGENTS.md) — Shared CliMA agent guidelines.
+
+> Shared guides live at `docs/dev-guides/` and are vendored from the canonical source:
+> https://github.com/CliMA/DeveloperGuides. Edit shared guides there, not here.
+
+## Repo-Specific Guidelines
+
+RRTMGP.jl computes radiative fluxes and heating rates with the RTE + RRTMGP correlated-`k` method, on CPU and GPU and in either `Float32` or `Float64`. Before working here, read the docs that define its public contract and internals:
+
+- [docs/src/getters.md](docs/src/getters.md) — the getter contract: the ClimaCore-free data-exchange interface hosts use to read and write the solver's buffers.
+- [docs/src/functional_core.md](docs/src/functional_core.md) — the functional core (`solve_lw!`/`solve_sw!`) beneath the `RRTMGPSolver` + `update_fluxes!` API.
+- [docs/src/precision.md](docs/src/precision.md) — the `Float32` numerics: cancellation-avoiding reformulations, `eps`-scaled guard constants (`RRTMGP.Numerics`), and the consistency harness.
+- [docs/src/RTE.md](docs/src/RTE.md) and [docs/src/Optics.md](docs/src/Optics.md) — the radiative transfer equations and the optics.
+
+## Local norms
+
+- The public API is layered: core containers → `RRTMGPSolver` + getters + `update_fluxes!` → the standalone entry points (`solve`, `solve_gray`, `standard_atmosphere`). Keep this separation; hosts should exchange data only through the getters.
+- `update_fluxes!` must stay allocation-free and type-stable on both devices (asserted in [test/standalone.jl](test/standalone.jl) and [test/all_sky_with_aerosols_utils.jl](test/all_sky_with_aerosols_utils.jl)). Read fluxes through the getters — do not `copy(getter(solver))` or `parent(getter(solver))`; both defeat the copy-free contract.
+- Kernels are device-agnostic and generic in the float type: they index buffers `[gcol, ilev]` (`(ncol, nlev)`), while physical storage is column-first on the GPU and vertical-first on the CPU. Numerical guard constants belong in `RRTMGP.Numerics`, each scaled by `eps(FT)`.
+- Run `julia --project=.dev .dev/climaformat.jl .` before committing (margin 80). This matches the CI formatter (pinned to Julia 1.10); a plain `format(".")` from a default JuliaFormatter install produces a different diff.
+- Prefer `Pkg.test()` over manually `include`ing `test/runtests.jl`: test-only deps (e.g. `JET`) are loaded through the package test path.
+- For a local docs build, `Pkg.develop(path = pwd())` in the `docs` environment first (the committed `docs/Manifest.toml` can be stale); restore it with `git checkout docs/Manifest.toml` before committing, never mid-build.
+- Match existing style: explicit names, narrow imports, comments that explain why. Follow the CliMA documentation policy (explicit `# Fields` sections in struct docstrings, not `DocStringExtensions.FIELDS`).
+
+## Self-correction
+
+- If a design doc referenced above is discovered to be stale relative to the code, update it.
+- If the user gives a correction about how work should be done in this repo, add it to `Local norms` (or another clearly labeled persistent section) so future sessions inherit it.

README.md

@@ -148,6 +148,15 @@ RRTMGP.jl provides radiative fluxes and heating rates for the
 For questions, check the [documentation](https://clima.github.io/RRTMGP.jl/latest/)
 or open an issue on [GitHub](https://github.com/CliMA/RRTMGP.jl).
 
+## Contributing
+
+Contributors should follow the shared CliMA engineering standards in
+[`docs/dev-guides/`](docs/dev-guides/), which cover architecture, performance,
+code quality, documentation, and workflows. These are vendored from
+[CliMA/DeveloperGuides](https://github.com/CliMA/DeveloperGuides). The repo's
+[`AGENTS.md`](AGENTS.md) is a starting point for AI agents with repo-specific
+guidance.
+
 ## Acknowledgments
 
 - [Robert Pincus](https://github.com/RobertPincus) for his invaluable help.

docs/dev-guides/AGENTS.md

@@ -0,0 +1,65 @@
+# CliMA Developer Guides: Agent Entry Point
+
+Read this file first. It is the agent entry point for the shared engineering guidelines. Each guide applies across the CliMA ecosystem unless stated otherwise.
+
+In consumer repos, these guides live at `docs/dev-guides/` and are supplied by a git subtree from the canonical source <https://github.com/CliMA/DeveloperGuides>. The consumer's root `AGENTS.md` references this file and the repo-specific guide. Edit shared guides in the canonical repo, not in the subtree copy.
+
+## Before you act: agent autonomy
+
+Local, reversible work (editing files, running tests, formatting, committing to the current branch) needs no permission. Get explicit user approval before any irreversible, externally visible, or scientifically consequential action:
+
+- **Git/GitHub**: `git push`, force-push, rebasing or amending pushed commits, `git reset --hard` or `git clean` with uncommitted changes, deleting branches, opening/merging/closing PRs, commenting on issues or PRs, tagging or pushing releases.
+- **Versioning and dependencies**: bumping `version` in `Project.toml`, editing `Manifest.toml`, changing `[compat]` or `[deps]`, `Pkg.update()`.
+- **Reproducibility data**: editing reference counters, MSE tolerances, or checksum/golden files in reproducibility-test directories. Change these only for a user-confirmed output change.
+- **CI and infrastructure**: editing `.buildkite/pipeline.yml` or `.github/workflows/*`, adding or removing CI jobs, disabling tests, skipping hooks (`--no-verify`).
+- **Public API and user-visible behavior**: renaming or removing exported symbols, renaming diagnostics or changing their units, changing or removing user-visible config keys.
+
+The full enumeration and the allowed-without-approval list are in [workflow/agent_autonomy.md](workflow/agent_autonomy.md). When in doubt, ask.
+
+## Guides
+
+### Architecture
+
+- [repo_structure.md](architecture/repo_structure.md): how to navigate any CliMA Julia package.
+- [ecosystem_conventions.md](architecture/ecosystem_conventions.md): module aliases, `Y`/`Yₜ`/`p` state layout, `ᶜ`/`ᶠ` notation, CI structure, reproducibility, diagnostics.
+- [architectural_boundaries.md](architecture/architectural_boundaries.md): layered architecture and boundary rules.
+- [cross_repo_contracts.md](architecture/cross_repo_contracts.md): call-site conventions for ecosystem packages.
+- [dependency_management.md](architecture/dependency_management.md): runtime vs dev dependencies, compat bounds.
+
+### Performance
+
+- [gpu_performance.md](performance/gpu_performance.md): GPU kernel rules, broadcast patterns, allocation avoidance.
+- [branchless_code.md](performance/branchless_code.md): avoiding warp divergence with `ifelse`, evaluate-both-cases splits, and fixed-iteration solvers chosen by offline tests.
+- [type_stability.md](performance/type_stability.md): Float32 compatibility, inference checks, struct field rules.
+- [numerical_robustness.md](performance/numerical_robustness.md): denominator regularization, clamping, NaN/Inf avoidance.
+- [ad_compatibility.md](performance/ad_compatibility.md): AD-safe patterns for ForwardDiff and Enzyme.
+- [allocation_debugging.md](performance/allocation_debugging.md): locating heap allocations with `Profile.Allocs`, JET, `@code_warntype`, flame graphs.
+
+### Code Quality
+
+- [getting_started.md](code-quality/getting_started.md): orienting newcomers to writing pointwise code compatible with ClimaCore `Field`s and broadcasting.
+- [code_style.md](code-quality/code_style.md): formatting, variable locality, Git workflow, feature removal, naming conventions.
+- [documentation_policy.md](code-quality/documentation_policy.md): docstrings, repository-level docs, minimally viable documentation.
+- [changelogs_and_versions.md](code-quality/changelogs_and_versions.md): `NEWS.md` format, SemVer rules, and the release/tagging flow.
+- [variable_list.md](code-quality/variable_list.md): standardized CliMA variable naming conventions.
+- [glossary.md](code-quality/glossary.md): general CliMA software and simulation terminology.
+- [software_design_patterns.md](code-quality/software_design_patterns.md): numbered SDPs for branchless logic, functors, parameter extraction, and more.
+
+### Infrastructure
+
+- [testing_and_validation.md](infrastructure/testing_and_validation.md): type-stability checks, Aqua.jl, allocation regression, AD tests.
+- [clima_comms.md](infrastructure/clima_comms.md): device-agnostic and MPI-distributed code patterns.
+
+### Workflow
+
+- [onboarding.md](workflow/onboarding.md): install Julia, clone a CliMA repo, set up Revise/Infiltrator/JuliaFormatter, first PR loop.
+- [running_on_gpu.md](workflow/running_on_gpu.md): run a model on GPU — install Julia, add `CUDA.jl`, CUDA runtime compatibility, `CLIMACOMMS_DEVICE`, verify the device.
+- [agent_autonomy.md](workflow/agent_autonomy.md): actions that require explicit user approval.
+- [debugging.md](workflow/debugging.md): interactive debugging recipes for numerical instabilities, dispatch, and `Field` plotting.
+- [review.md](workflow/review.md): PR review instructions and checklist.
+- [ci_triage.md](workflow/ci_triage.md): checklist for "passes locally, fails on CI" failure modes.
+- [cross_repo_issue_pr_search.md](workflow/cross_repo_issue_pr_search.md): org-scoped GitHub search to find and filter issues/PRs across CliMA.
+
+## Self-correction
+
+If this index is stale or missing a guide, update it here and in the matching [README.md](README.md#guides) overview.