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,88 @@
+# AGENTS.md - openstack-baremetal-operator
+
+## Project overview
+
+openstack-baremetal-operator is a Kubernetes operator that manages
+bare metal provisioning infrastructure for
+[OpenStack](https://docs.openstack.org/) on OpenShift/Kubernetes. It handles
+provisioning physical servers (PXE boot, RHEL image serving) and matching
+hardware requirements (CPU count/MHz, memory, disk size/SSD) for OpenStack
+services. It is part of the
+[openstack-k8s-operators](https://github.com/openstack-k8s-operators) project.
+
+Key domain concepts: **bare metal sets** (groups of provisioned hosts),
+**provision servers** (HTTP image serving), **hardware requirements**
+(CPU count, CPU MHz, memory, disk size, SSD), **IPMI**, **BMC** (Baseboard
+Management Controller), **Metal3** (bare metal host management).
+
+## 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) |
+| Linting | golangci-lint (`.golangci.yaml`) |
+| CI | Zuul (`zuul.d/`), Prow (`.ci-operator.yaml`), GitHub Actions |
+
+## Custom Resources
+
+| Kind | Purpose |
+|------|---------|
+| `OpenStackBaremetalSet` | Manages a set of bare metal hosts provisioned for OpenStack services. Matches hardware requirements and provisions via Metal3. |
+| `OpenStackProvisionServer` | Manages an HTTP server for serving RHEL images to bare metal nodes during provisioning. |
+
+Both CRs have defaulting and validating admission webhooks.
+
+## Directory structure
+
+| Directory | Contents |
+|-----------|----------|
+| `api/v1beta1/` | CRD types (`openstackbaremetalset_types.go`, `openstackprovisionserver_types.go`), conditions, webhook markers |
+| `cmd/` | `main.go` entry point |
+| `internal/controller/` | Reconcilers: `openstackbaremetalset_controller.go`, `openstackprovisionserver_controller.go` |
+| `internal/openstackbaremetalset/` | BaremetalSet resource builders (bare metal host management, set helpers) |
+| `internal/openstackprovisionserver/` | ProvisionServer resource builders (deployment, volumes, init containers, jobs) |
+| `internal/webhook/` | Webhook implementation |
+| `templates/` | Config files and scripts mounted into pods via `OPERATOR_TEMPLATES` env var. Subdirs: `openstackbaremetalset/`, `openstackprovisionserver/` |
+| `config/crd,rbac,manager,webhook/` | Generated Kubernetes manifests (CRDs, RBAC, deployment, webhooks) |
+| `config/samples/` | Example CRs |
+| `containers/` | Container image build files (agent) |
+| `tests/functional/` | envtest-based Ginkgo/Gomega tests |
+| `hack/` | Helper scripts |
+
+## 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/openstackbaremetalset/` and `internal/openstackprovisionserver/`
+  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
+  `tests/functional/` (note: `tests/` not `test/`).
+- There are no KUTTL integration tests in this operator.
+- Run all functional tests: `make test`.
+- When adding a new field or feature, add corresponding test cases in
+  `tests/functional/`.
+
+## Key dependencies
+
+- [lib-common](https://github.com/openstack-k8s-operators/lib-common): shared modules for conditions, endpoints, TLS, secrets, etc.
+- [Metal3 baremetal-operator](https://github.com/metal3-io/baremetal-operator): manages `BareMetalHost` CRDs for bare metal host lifecycle.
+- [Cluster Baremetal Operator](https://github.com/openshift/cluster-baremetal-operator): manages the `Provisioning` CRD for Metal3 provisioning infrastructure on OpenShift.