Add AGENTS.md

[fmount]

This patch adds AGENTS.md to the repo to ensure any AI agent can follow the conventions defined for this operator. At the same time, it allows to not waste time navigating the repo to find initial information and save tokens.

[centosinfra-prod-github-app]

Build failed (check pipeline). Post recheck (without leading slash)
to rerun all jobs. Make sure the failure cause has been resolved before
you rerun jobs.

https://gateway-cloud-softwarefactory.apps.ocp.cloud.ci.centos.org/zuul/t/rdoproject.org/buildset/897b756baf2a47879b1f95ed33f1c7b4

✔️ openstack-k8s-operators-content-provider SUCCESS in 2h 18m 53s
❌ heat-operator-tempest-multinode FAILURE in 1h 47m 26s

[centosinfra-prod-github-app]

Build failed (check pipeline). Post recheck (without leading slash)
to rerun all jobs. Make sure the failure cause has been resolved before
you rerun jobs.

https://gateway-cloud-softwarefactory.apps.ocp.cloud.ci.centos.org/zuul/t/rdoproject.org/buildset/260bbab465ad4239ba2620d210db9209

❌ openstack-k8s-operators-content-provider FAILURE in 17m 17s
⚠️ heat-operator-tempest-multinode SKIPPED Skipped due to failed job openstack-k8s-operators-content-provider

[rabi]

Thanks for adding this — the intent is right. However, most of the content here restates things an agent can discover on its own by reading files (tree, go.mod, the types under api/v1beta1/), or duplicates what already belongs in the README (project description, domain concepts, tech stack).

Gloaguen et al. (2026), "Evaluating AGENTS.md" (ICML) found that verbose context files reduce task success rates by ~3% while increasing cost by 20%+, because agents follow the extra instructions dutifully but gain nothing from discoverable information. Their conclusion: human-written context files should describe only minimal, non-obvious requirements.

Applying that here, most of this file (project description, Heat domain concepts, tech stack table, directory structure, CR table, dependency list) is either discoverable or belongs in the README. What would actually help an agent is just the non-obvious rules:

# AGENTS.md

- Always run `make generate manifests fmt vet` after modifying Go code.
- Do not hand-edit files under `zz_generated*` or `config/crd/bases/` — they are generated.
- The `Heat` top-level CR owns `HeatAPI`, `HeatCfnAPI`, and `HeatEngine` sub-CRs. Changes to shared config go in `Heat`, not the sub-CRs.
- Unit tests use envtest (`make test`). Integration tests use KUTTL (`make kuttl-test`).
- Stack domain user setup is a distinct reconciliation phase — see `HeatStackDomainReadyCondition`.

Note: the file mentions go.work but doesn't clarify it's generated locally and not checked in. An agent might look for it and be confused when it's not there.

[fmount]

Thanks for adding this — the intent is right. However, most of the content here restates things an agent can discover on its own by reading files (tree, go.mod, the types under api/v1beta1/), or duplicates what already belongs in the README (project description, domain concepts, tech stack).

Thanks @rabi, the idea of AGENTS.md here is to have an initial template that can be refined by each team and avoid spending time on initial find(s) and grep(s) of files to speedup the process a bit. You won't gain much but having some info here avoid discovering the peer projects within the org or take decisions about the tech stack that must be used.
If most of the info are present in the README.md I can point to that file, and we can keep this file as small as possible, and use it as the first layer of routing for an AI agent.

Gloaguen et al. (2026), "Evaluating AGENTS.md" (ICML) found that verbose context files reduce task success rates by ~3% while increasing cost by 20%+, because agents follow the extra instructions dutifully but gain nothing from discoverable information. Their conclusion: human-written context files should describe only minimal, non-obvious requirements.

I didn't review this paper and I can't speak for real, but I think staying within 100 or 150 loc is good enough for a small agents.md that can route info. What are in your opinion the obvious information that we should remove?

Applying that here, most of this file (project description, Heat domain concepts, tech stack table, directory structure, CR table, dependency list) is either discoverable or belongs in the README. What would actually help an agent is just the non-obvious rules:

# AGENTS.md

- Always run `make generate manifests fmt vet` after modifying Go code.
- Do not hand-edit files under `zz_generated*` or `config/crd/bases/` — they are generated.
- The `Heat` top-level CR owns `HeatAPI`, `HeatCfnAPI`, and `HeatEngine` sub-CRs. Changes to shared config go in `Heat`, not the sub-CRs.
- Unit tests use envtest (`make test`). Integration tests use KUTTL (`make kuttl-test`).
- Stack domain user setup is a distinct reconciliation phase — see `HeatStackDomainReadyCondition`.

Note: the file mentions go.work but doesn't clarify it's generated locally and not checked in. An agent might look for it and be confused when it's not there.

ack, makes sense to explicitly state this is a local file.

[centosinfra-prod-github-app]

Build failed (check pipeline). Post recheck (without leading slash)
to rerun all jobs. Make sure the failure cause has been resolved before
you rerun jobs.

https://gateway-cloud-softwarefactory.apps.ocp.cloud.ci.centos.org/zuul/t/rdoproject.org/buildset/ef60983bd0244b22aa3c2d885ec5ce04

✔️ openstack-k8s-operators-content-provider SUCCESS in 1h 56m 21s
❌ heat-operator-tempest-multinode FAILURE in 1h 36m 15s

[fmount]

recheck

[slagle]

lgtm, we can refine as we go

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: fmount, slagle

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [slagle]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment