admin: Add AI coding assistant configuration

.agents/skills/prepare-patch-release/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: prepare-patch-release
+description: Do all the tasks needed for a patch release of the project.argument-hint: [new-version]
+---
+
+Do all the tasks needed for a patch release of the project. These patch
+releases generally happen on the first day of every month.
+
+Arguments: `$ARGUMENTS`
+- First argument (optional): the version of the upcoming release we are
+preparing. If omitted, find the most recent tag on this branch, and the
+new version will update the third portion of the version. It might be
+either a version number (like `3.1.4.0`) or a tag (like `v3.1.4.0`).
+
+Hint: The numeric "version" is a four-part numeric deignation with the pattern
+`MAJOR.MINOR.PATCH.TWEAK`. The "version tag" is usually the numeric version
+with a "v" prepended, for example, `v3.1.4.0`.
+
+## Steps and Checklist
+
+- [ ] Determine the version of the new release.
+- [ ] Update the main @CMakeLists.txt.
+- [ ] Use the "release-notes-update" skill to update @CHANGES.md.
+- [ ] Review the release notes to ensure that the changes do not deprecate any
+      API calls or break API or ABI backward-compatibility, or remove support
+      for any dependency or toolchain versions. If you think these rules are
+      being violated, ask for confirmation.
+- [ ] Review @README.md for changes.
+- [ ] Review @INSTALL.md for changes.
+- [ ] Review @CREDITS.md for changes.
+- [ ] Review @SECURITY.md for changes.
+
+## Steps to determine the versions of the last and new releases.
+
+1. **Determine the previous tag** if not provided by looking at the 
+   most recent git tag in the current branch, and deducing the 4-part
+   version number from that.
+2. The assumed new version for a patch release has the same major and minor
+   numbers, the patch number is incremented by one since the last tag, and the
+   tweak number is "0".
+3. If no optional version was present in the arguments, use the assumed new
+   version.
+4. If a version was supplied in the arguments, double check that it differs
+   from the last tag as explained above. If it does not, ask for verification
+   that the version requested is correct before proceeding.
+
+## Steps to update CMakeLists.txt
+
+1. In the main @CMakeLists.txt, alter the version to that of the new release,
+   if it isn't already the same.
+2. For a patch release, ensure that `${PROJECT_NAME}_SUPPORTED_RELEASE` should
+   be set to ON. In main (not yet a supported release) it shold be OFF. If you
+   find these to not be as expected, ask for confirmation of whether to fix.
+3. For a patch release, `PROJECT_VERSEION_RELEASE_TYPE` should be set to empty
+   (""). In main, it will typically be "dev", "beta", or other designations.
+   If you find these to not be as expected, ask for confirmation of whether to
+   fix.
+
+## Reviewing README.md
+
+If this release added support for any new image file formats, be sure that
+README.md mentions them in its list of image formats supported. 
+
+## Reviewing INSTALL.md
+
+If any of the new commits (as described in the release notes for this version)
+appear to add dependencies, or add support for new versions of dependencies,
+be sure that INSTALL.md is updated to include that dependency (if not already
+listed among the required and optional dependencies), and reflects the latest
+version that we claim to support.
+
+Double check @externalpackages.cmake and ensure that any minimum required
+versions of dependencies that cmake will enforce match the oldest versions
+of those dependencies as documentd in INSTALL.md.
+
+## Reviewing CREDITS.md
+
+The @CREDITS.md file lists all known contributors to the project, sorted alpha
+by first name. In cases where an author's actual name is unknown, we use the
+GitHub userid.
+
+Ensure that any authors referenced in the new release notes for the version we
+are releasing are inserted in the credit list, if they are not already
+present. You don't need to check older versions, we presume those have already
+been included.
+
+## Reviewing SECURITY.md
+
+The @SECURITY.md file lists which versions are currently supported at what
+levels, and lists all previously-fixed SVE's or security advisories. Be sure
+to check this file in older branches (the last two releases, say), and if you
+are preparing a patch release, also check in main and more recent (higher
+numbered) releases for more recently modified SECURITY.md, and be sure that
+this branch gets amended with any information that seems to have been updated
+more recently in those other branches. Check whichever is newer of the local
+and remote copy of that branch, since the local one may have had release notes
+or its version in CMakeLists.txt updated, but not yet pushed to GitHub.
+
+
+## Reference
+
+- Full release procedures: `docs/dev/RELEASING.md`
+- Steps for updating release notes: `release-notes-update/SKILL.md`

.agents/skills/release-notes-update/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: release-notes-update
+description: Generate or update release notes for a patch, minor, or major release, or just to update main. Run git-cliff, organize and edit the output per project conventions, and insert into CHANGES.md.
+argument-hint: [patch|minor|major|main] [prev-tag]
+---
+
+Generate release notes for an OpenImageIO release.
+
+Arguments: `$ARGUMENTS`
+- First argument (optional): release type — `patch` (default), `minor`, `major`, or `main`.
+- Second argument (optional): previous release tag (e.g. `v3.1.2.0`). If omitted, find the most recent tag automatically. If the release type is `main`, instead of a tag, look for the last commit at which the CHANGES.md file was updated.
+
+## Steps
+
+1. **Determine the previous tag** if not provided:
+   ```
+   git describe --tags --abbrev=0
+   ```
+   or look at recent tags: `git tag --sort=-version:refname | head -10`.
+   However, if the "release type" is `main`, instead of a tag, just find
+   the commit at which CHANGES.md was last updated.
+
+2. **Run git-cliff** to get raw commit data:
+   ```
+   git cliff -c src/doc/cliff.toml <prev-tag>..HEAD > /tmp/cliff-out.md
+   ```
+   Read `/tmp/cliff-out.md` to see the raw output.
+
+3. **Read CHANGES.md** to see the current top of the file and understand where to insert.
+
+4. **Format the release notes** according to the release type:
+
+### For patch releases:
+
+Follow the skeleton in `docs/dev/Changes-skeleton-patch.md`:
+
+```
+Release X.Y.Z.W (Month DD, YYYY) -- compared to X.Y.Z.W-1
+---------------------------------------------------------
+- *category*: Description. [#NNNN](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/NNNN) (by author)
+```
+
+Rules:
+- **Remove** the section headings git-cliff generates; patch notes are a flat
+  list.
+- **Add conventional commit prefixes** to any "uncategorized" entries (those
+  lacking a `feat:`, `fix:`, etc. prefix).
+- **Reorder** entries logically: feature enhancements first, then bug fixes,
+  then build/CI fixes, then internal changes, then test improvements, then
+  docs/admin.
+- **Omit** entries that are purely internal and too minor to matter to users.
+  Ask for confirmation about entries you propose to omit.
+- Prefer to use author's actual name if known. If the name cannot be found,
+  the GitHub userid can be used instead.
+- Omit the author if it is the project leader, Larry Gritz, unless he is not
+  the dominant author (at least 75% of commits) in this release.
+- Keep entries to one line each. Be terse but informative.
+- Use the format `*subsystem*:` for the category prefix (e.g., image file
+  format like `*exr*:`, utility like `*oiiotool*:`, class or API category like
+  `*IBA*:`, or topic category such as `*build*:`, `*ci*:`, `*docs*:`).
+- We aim to make patch releases on the first day of each month. If we are
+  within a few days of a month end, list the date as the beginning of the
+  upcoming month. Ask for confirmation that this is the planned release date.
+
+
+### For minor or major releases:
+
+Follow the skeleton in `docs/dev/Changes-skeleton-major.md`. Sections:
+
+```
+Release X.Y.0.0 (Month, YYYY) -- compared to X.Y-1
+--------------------------------------------------
+
+### New minimum dependencies and compatibility changes:
+### ⛰️  Major new features and public API changes:
+  * *New image file format support:*
+  * *oiiotool new features and major improvements*:
+  * *Command line utilities*:
+  * *API changes*
+  * Other notable new feature:
+### 🚀  Performance improvements:
+### 🐛  Fixes and feature enhancements:
+### 🔧  Internals and developer goodies
+### 🏗  Build/test/CI and platform ports:
+  * CMake build system and scripts:
+  * Dependency and platform support:
+  * Testing and Continuous integration (CI) systems:
+### 📚  Notable documentation changes:
+### 🏢  Project Administration
+### 🤝  Contributors
+```
+
+Note that the section outline may already be present, in which case you
+only need to fit items into the existing category outline.
+
+Rules:
+- Group commits into sections; within each section, cluster related items together.
+- When needed, expand terse one-liners into enough prose that users understand what changed and why it matters.
+- For `feat:` commits, make sure the feature is explained sufficiently — don't just copy the commit subject.
+- For `api:` or `api!:` commits, clearly call out what changed in the public API.
+- Include PR links and author attribution for every entry.
+- The notes should "tell the story" of the release, not just be a dump of commit subjects.
+- We aim to make major/minor releases approximately in October 1 of each year. If the anticipted release date is already in the file, don't change it. If it is not present, ask for confirmation of the planned release date.
+
+### For updating release notes in main:
+
+Rules:
+- Generally, follow the rules for "major/minor releases", except as noted in other items below.
+- Don't apply a new skeleton of category listings unless they are not present for the upcoming release.
+
+5. **Insert the formatted notes** into `CHANGES.md` in the appropriate place (as detailed below). Leave the existing content intact.
+- When updating `main` or preparing a `major` or `minor` release, insert the updates in the top section for the upcoming major/minor release. Insert a new set of category sections only if it's not already present.
+- When doing a `patch` release, insert the changes immediately above the last patch release of that branch, so that CHANGES.md lists releases in descending numerical (version) order.
+- When porting a set of release notes from a release branch into main, or from an older (obsolete) release branch to the current release branch, insert it into the right place to maintain overall descending order.
+
+6. **Double check that the notes are adequately descriptive.** (See more
+   detailed description of this step below.)
+
+7. **Forward-port release notes from release branches if needed**
+
+8. **Show a summary** of what was inserted and ask the user to review before finalizing.
+
+## Forward-porting release notes
+
+Release notes may have been generated independently in main, and release
+branches. When updating one branch, we ensure that any changes from older
+branches have been incorporated.
+
+- When preparing `patch` release notes, check the CHANGES.md file in the
+  "dev-X.(Y-1)" branch for the previous minor release family to identify any
+  X.(Y-1).Z patch release notes that are not reflected in the current release
+  notes that we are updating.
+- When updating `main` or doing a `major` or `minor` release, check the
+  CHANGES.md file in both the "dev-X.(Y-1)" and "dev-X.(Y-2)" branches.
+  Check whichever is newer of the local and remote copy of that branch, since
+  the local one may have had release notes or its version in CMakeLists.txt
+  updated, but not yet pushed to GitHub.
+- If any patch releases are present in the older dev branches checked, insert
+  the release notes for those patch releases into the right positions in the
+  current release notes that we are updating.
+- If a change is forward-ported in this manner and the same PR is an update in
+  the current set of changes we are updating as our main task, document that
+  in the current set of notes using the following convention: in the line of
+  the notes, the explanation of the version where it appears should reflect
+  the first version of all branches where it appeared, for example, `(3.2.0.0,
+  3.1.3.0, 3.0.8.0)` to indicate that the patch was added to each of those
+  versions. The versions should be listed in descending order.
+
+## Useful abbreviations for category labels
+
+| Abbrev | Meaning |
+|--------|---------|
+| IB | ImageBuf |
+| IBA | ImageBufAlgo |
+| IC | ImageCache |
+| TS | TextureSystem |
+| oiiotool | the oiiotool command |
+| build | CMake/build system |
+| deps | Changes to accommodate dependency or toolchain changes |
+| ci | CI/GitHub Actions |
+| docs | documentation |
+| int | internal/refactor |
+| test | testsuite or unit tests |
+| HEADER.h | Developer utilities in a public header file |
+
+## Combining PRs into single entries
+
+To be more concise and easier to read, within a release's notes, related
+PRs/commits can be combined into a single bullet-point line, which would look
+like
+```
+- *category*: Combined Description. [#NNNN1](URL) (by author1) [#NNNN2](URL2) (by author2)  [#NNNN2](URL2) (by author2)
+
+```
+if fully combined, or if explained one by one,
+```
+- *category*: Description 1 [#NNNN1](URL) (by author1), amendment 2, [#NNNN2](URL2) (by author2), amendment 3, [#NNNN3](URL3) (by author3)
+```
+Choose the fully combined or explained one by one based on which is more clear
+to the reader.
+
+If the authors are all the same, only have the author designation at the end.
+
+Here are the cases where it's ok to combine commits in this way:
+- If it is clear that multiple PRs are part of the same feature or fix,
+  consisting of an initial commit, and subsequent smaller changes or
+  continuations of the same topic.
+- An initial commit, and a subsequent commit that is obviously a fix to a bug
+  in the initial commit.
+- "CI" changes that all only add new cases to the test matrix.
+- "CI" changes that all only fix spontaneous breakages in the GitHub runners.
+- "Build" changes that are all just minor updates to versions of dependencies
+  that we support or test against.
+
+Some more examples of combined commit messages:
+
+```
+  - feat: Add GPS metadata functionality for TIFF [PR1](PR URL 1) [PR2](PR URL 2) [PR3](PR URL 3) (by author).
+  - ci: New CI variants for MSVS 2026 [PR1](PR URL 1) (by author1), VFX Platform 2027 [PR2](PR URL 2) (by author2).
+  - ci: Various fixes for unexpected changes to GitHub Actions runners [PR1](PR URL 1), [PR2](PR URL 2) (by author)
+  - build: Added support for gcc 15 [PR1](PR URL 1) (by author1), OpenEXR 3.5.1 [PR2](PR URL 2) (by author2), libtiff 4.8 [PR3](PR URL 3) (by author3).
+```
+
+Always ask for confirmation before combining commits in this manner. Confirm
+separately for each proposed combination of a group of multiple original
+commits into a single commit. Give the user the opportunity to revise the
+combined description or request other changes for the grouping.
+
+## Double check that the notes are adequately descriptive
+
+For newly added items for this release, read the short descriptions provided
+by git-cliff, double check them against the full commit messages to be sure
+the one-line summary is adequate. If the summary is misleading, too brief and
+leaving out the fact that an important thing was changed, or not adequately
+capturing the scope of changes, feel free to propose an alternate wording that
+will make it more clear to readers what changed as a result of the PR. Ask for
+confirmation on these and explain why you felt the one-line description wasn't
+enough.
+
+One example of a case where this is needed is if the one line description
+merely mentions a new image processing capability by name, but the full commit
+message makes it clear that a new ImageBufAlgo API call was added, and also a
+new oiiotool command line argument was added, and that couldn't all be
+described in the one-line brief message of the commit.
+
+## Reference
+
+Full release procedures: `docs/dev/RELEASING.md`
+Patch skeleton: `docs/dev/Changes-skeleton-patch.md`
+Major skeleton: `docs/dev/Changes-skeleton-major.md`
+Example good patch notes: https://github.com/AcademySoftwareFoundation/OpenImageIO/releases/tag/v3.0.0.0
+Example good major/minor notes: https://github.com/AcademySoftwareFoundation/OpenImageIO/releases/tag/v3.1.6.1

.claude/.gitignore

@@ -0,0 +1,2 @@
+# Per-user Claude Code settings override (not shared)
+settings.local.json

.claude/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

.codex/.gitignore

@@ -0,0 +1,2 @@
+# Codex session/cache files (per-user)
+*.log

.codex/skills

@@ -0,0 +1 @@
+../.agents/skills

.cursor/.gitignore

@@ -0,0 +1,4 @@
+# Cursor Composer session history (per-user)
+composer/
+# Cursor chat logs (per-user)
+chat/

.cursor/rules/project.mdc

@@ -0,0 +1 @@
+../../AGENTS.md

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

.opencode/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+package.json
+package-lock.json
+bun.lock

.opencode/commands/prepare-patch-release.md

@@ -0,0 +1 @@
+../../.agents/skills/prepare-patch-release/SKILL.md

.opencode/commands/release-notes-update.md

@@ -0,0 +1 @@
+../../.agents/skills/release-notes-update/SKILL.md

.opencode/skills

@@ -0,0 +1 @@
+../.agents/skills