Skip to content

Adding agents.md file to H2I repository - #950

Open
genevievestarke wants to merge 2 commits into
NatLabRockies:developfrom
genevievestarke:agents_md
Open

genevievestarke wants to merge 2 commits into
NatLabRockies:developfrom
genevievestarke:agents_md

Conversation

@genevievestarke

Copy link
Copy Markdown
Collaborator

Adding agents.md file to H2I repository

This PR puts forth an agents.md file for the H2I repository to establish repository norms across the code. The information for this file was taken from the H2I documentation and edited to be what I thought would be good to define at a general level.

Type of Contribution

  • Feature Enhancement
    • Framework
    • New Model
    • Updated Model
    • Tools/Utilities
    • Other (please describe):
  • Bug Fix
  • Documentation Update
  • CI Changes
  • Other (please describe):

Draft PR Checklist

  • Open draft PR
  • Describe the feature that will be added
  • Fill out TODO list steps
  • Describe requested feedback from reviewers on draft PR
  • Complete Section 8: New Model Checklist (if applicable)

TODO

  • Step 1
  • Step 2

Type of Reviewer Feedback Requested (on Draft PR)

Structural feedback:

Implementation feedback:
Some general questions:

  1. Do we want to include a testing section in the agents.md file? There is one included currently
  2. The file currently references Python 3.13. Do we want to do this or just leave this out?

Other feedback:

General PR Checklist

  • PR description thoroughly describes the new feature, bug fix, etc.
  • New model checklist has been completed (new models only)
  • Tests
    • All tests pass locally
    • Added tests for new functionality or bug fixes
    • Modified tests have been outlined in the impacted areas section
  • Documentation
    • Docstrings are up-to-date
    • Related docs/ files are up-to-date, or added when necessary
    • Documentation has been rebuilt successfully
    • Examples have been updated (if applicable)
    • No changes required
  • CHANGELOG.md
    • At least one complete sentence has been provided to describe the changes made in this PR
    • After the above, a hyperlink has been provided to the PR using the following format:
      "A complete thought. [PR XYZ]((https://github.com/NatLabRockies/H2Integrate/pull/XYZ)", where
      XYZ should be replaced with the actual number.

Related Issues

[N/A or appropriately link related issues]

Impacted Areas of the Software

New Files

  • path/to/file.extension
    • method1: What and why something was changed in one sentence or less.

Modified Files

  • path/to/file.extension
    • method1: What and why something was changed in one sentence or less.

Release checklist

  • Update the version in h2integrate/__init__.py
  • Verify docs builds correctly
  • Create a tag on the main branch in the NatLabRockies/H2Integrate repository and push
  • Ensure the Test PyPI build is successful
  • Create a release on the main branch

@johnjasa johnjasa added framework infrastructure Anything relating to CI, project management, or non-code changes and removed framework labels Oct 28, 2026

@RHammond2 RHammond2 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added a few comments, though based on today's meeting I believe there will be some further revisions, and didn't do a complete review. In general, this could be a good opportunity to split up some of our contributing guidelines and use more actionable language within them, and reference those documents here.

Comment thread AGENTS.md Outdated

## Python style and checks

- Target Python 3.13 and a maximum line length of 100 characters. Follow PEP 8 and the local Ruff

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We technically target the minimum Python to ensure compatibility with lower-versioned environments, which is 3.11 here.

Comment thread AGENTS.md
- Call `super().setup()` where required by the base class so standard OpenMDAO inputs and outputs
are registered. Preserve units, port names, output contracts, and control behavior.

## Python style and checks

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would just offload this section to point towards our contributor's guidelines (similar to pandas or scikit-learn) and listing the specific command that should be run (below).

  • Run pre-commit run --from-ref=upstream/develop --to-ref=HEAD --all-files

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you suggesting we add the specific command to the docs and refer the agents.md file there, or directly in the agents.md file?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good question. Maybe in here for now since this is the only agent-specific infrastructure. I think some of our code contributing guides will need to be revamped in conjunction with our AI strategy, but that may already be underway and I'm unaware.

Comment thread AGENTS.md Outdated
Comment on lines +16 to +17
- Follow existing package/module organization and reuse the relevant base class, shared fixtures,
configuration patterns, and helpers rather than introducing parallel abstractions.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should likely expand on this to fully delineate the package structure.

Comment thread AGENTS.md Outdated
Comment on lines +11 to +12
- Use descriptive `lowercase_with_underscores` names and add type hints to function parameters and
return values. Use NumPy arrays for array data rather than Python lists.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe ruff will flag bad variable names, and this is Python, so snake case variables is the expectation. If we still need this, it's better suited for the code style/conventions section.

Comment thread AGENTS.md
- Use an attrs configuration class (`@define(kw_only=True)`) based on the appropriate existing
config class. Name model-specific config classes `{ModelName}Config`, validate inputs with the
existing config mechanisms, and instantiate the config in `setup()`.
- Call `super().setup()` where required by the base class so standard OpenMDAO inputs and outputs

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also super().initialize() where required by the base class so that standard OpenMDAO options are registered.

Comment thread AGENTS.md
- Update relevant user/developer documentation and docstrings when behavior, configuration,
model interfaces, or examples change. Keep explanations clear and concise, and keep examples
executable and consistent with the current API.
- Use Google-style docstrings for functions, methods, and classes. Describe purpose, important

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For functions and methods, include the Args and Returns sections in the doc-strings.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change Args to Attributes based on #999

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added!

@jaredthomas68

Copy link
Copy Markdown
Collaborator

Posting connection to my related comment and attached agents.md file in issue #976 (#976 (comment))

@genevievestarke genevievestarke added the ready for review This PR is ready for input from folks label Nov 13, 2026
@genevievestarke

Copy link
Copy Markdown
Collaborator Author

This PR is now updated from feedback! I took a longer approach for the file for now, although the pandas and scikit examples are very short and point to the documentation. I personally like the longer version as it's a nice place to gather the essentials of the code into one place, but it might also be hard to keep it up to date moving forwards.

Let me know if you prefer a longer, more specific agents.md file, or a shorter one!

Comment thread AGENTS.md
configuration, templates, or generators instead.
- Defer documentation updates until the user confirms code work is complete, approves all code changes, and all
required tests pass. Only then update affected documentation. Do not build the documentation unless the user explicitly requests it.
- Append "(AI)" to inline comments written by an agent (not docstrings)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this part!

@elenya-grant elenya-grant left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this looks good to me Gen! Thank you!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

infrastructure Anything relating to CI, project management, or non-code changes ready for review This PR is ready for input from folks

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants