Add AGENTS.md

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.

Signed-off-by: Francesco Pantano <fpantano@redhat.com>

Author: fmount

AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md - heat-operator
+
+## Project overview
+
+heat-operator is a Kubernetes operator that manages
+[OpenStack Heat](https://docs.openstack.org/heat/latest/) (the orchestration
+service: stack lifecycle, HOT templates, autoscaling, resource dependencies)
+on OpenShift/Kubernetes. It is part of the
+[openstack-k8s-operators](https://github.com/openstack-k8s-operators) project.
+
+Key Heat domain concepts: **stacks**, **HOT templates** (Heat Orchestration
+Template), **resources**, **nested stacks**, **autoscaling groups**,
+**wait conditions**, **software deployments**, **DB purge**.
+## Tech stack
+
+| Layer | Technology |
+|-------|------------|
+| Language | Go (modules, multi-module workspace via `go.work`) |
+| Scaffolding | [Kubebuilder v4](https://book.kubebuilder.io/) + [Operator SDK](https://sdk.operatorframework.io/) |
+| CRD generation | controller-gen (DeepCopy, CRDs, RBAC, webhooks) |
+| Config management | Kustomize |
+| Packaging | OLM bundle |
+| Testing | Ginkgo/Gomega + envtest (functional), KUTTL (integration) |
+| Linting | golangci-lint (`.golangci.yaml`) |
+| CI | Zuul (`zuul.d/`), Prow (`.ci-operator.yaml`), GitHub Actions |
+
+## Custom Resources
+
+| Kind | Purpose |
+|------|---------|
+| `Heat` | Top-level CR. Owns the database, keystone service, transport URL, and spawns sub-CRs for each service component. |
+| `HeatAPI` | Manages the Heat API deployment (httpd/WSGI). |
+| `HeatCfnAPI` | Manages the Heat CloudFormation-compatible API deployment. |
+| `HeatEngine` | Manages the engine service deployment (stack operations). |
+
+The `Heat` CR has defaulting and validating admission webhooks.
+Sub-CRs are created and owned by the `Heat` controller -- not intended to
+be created directly by users.
+
+## Directory structure
+
+**Maintenance rule:** when directories are added, removed, or renamed, or when
+their purpose changes, update this table to match.
+
+| Directory | Contents |
+|-----------|----------|
+| `api/v1beta1/` | CRD types (`heat_types.go`, `heatapi_types.go`, `heatcfnapi_types.go`, `heatengine_types.go`), conditions, webhook markers |
+| `cmd/` | `main.go` entry point |
+| `internal/controller/` | Reconcilers: `heat_controller.go`, `heatapi_controller.go`, `heatcfnapi_controller.go`, `heatengine_controller.go` |
+| `internal/heat/` | Heat-level resource builders (db-sync, common helpers) |
+| `internal/heatapi/` | HeatAPI resource builders |
+| `internal/heatcfnapi/` | HeatCfnAPI resource builders |
+| `internal/heatengine/` | HeatEngine resource builders |
+| `internal/webhook/` | Webhook implementation |
+| `templates/` | Config files and scripts mounted into pods via `OPERATOR_TEMPLATES` env var |
+| `config/crd,rbac,manager,webhook/` | Generated Kubernetes manifests (CRDs, RBAC, deployment, webhooks) |
+| `config/samples/` | Example CRs (Kustomize overlays). Includes TLS and topology variants. |
+| `test/functional/` | envtest-based Ginkgo/Gomega tests |
+| `test/kuttl/` | KUTTL integration tests |
+| `hack/` | Helper scripts (CRD schema checker, local webhook runner) |
+| `ci/` | CI job definitions |
+
+## Build commands
+
+After modifying Go code, always run: `make generate manifests fmt vet`.
+
+## Code style guidelines
+
+- Follow standard openstack-k8s-operators conventions and lib-common patterns.
+- Use `lib-common` modules for conditions, endpoints, TLS, storage, and other
+  cross-cutting concerns rather than re-implementing them.
+- CRD types go in `api/v1beta1/`. Controller logic goes in
+  `internal/controller/`. Resource-building helpers go in `internal/heat*`
+  packages matching the CR they support.
+- Config templates are plain files in `templates/` -- they are mounted at
+  runtime via the `OPERATOR_TEMPLATES` environment variable.
+- Webhook logic is split between the kubebuilder markers in `api/v1beta1/` and
+  the implementation in `internal/webhook/`.
+
+## Testing
+
+- Functional tests use the envtest framework with Ginkgo/Gomega and live in
+  `test/functional/`.
+- KUTTL integration tests live in `test/kuttl/`.
+- Run all functional tests: `make test`.
+- When adding a new field or feature, add corresponding test cases in
+  `test/functional/` and update fixture data accordingly.
+
+## Key dependencies
+
+- [lib-common](https://github.com/openstack-k8s-operators/lib-common): shared modules for conditions, endpoints, database, TLS, secrets, etc.
+- [infra-operator](https://github.com/openstack-k8s-operators/infra-operator): RabbitMQ and topology APIs.
+- [mariadb-operator](https://github.com/openstack-k8s-operators/mariadb-operator): database provisioning.
+- [keystone-operator](https://github.com/openstack-k8s-operators/keystone-operator): identity service registration.