chore: add AGENTS.md and CONTRIBUTING.md

On-behalf-of: @SAP mirza.kopic@sap.com
Signed-off-by: Mirza Kopić <mirza.kopic@gmail.com>

Author: mirzakopic

AGENTS.md

@@ -0,0 +1,107 @@
+# resource-broker
+
+Kubernetes operator for multi-cluster resource brokering. Kubebuilder v4, multigroup layout. Built on `sigs.k8s.io/multicluster-runtime`.
+
+Read the org-wide [AGENTS.md](https://github.com/platform-mesh/.github/blob/main/AGENTS.md) for general conventions. Read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow.
+
+## Commands
+
+- `make check` — codegen + lint + test + test-e2e (CI gate)
+- `make test` — unit tests
+- `make test TEST_ARGS="-run TestName"` — single unit test
+- `make test-e2e` — e2e tests (uses envtest)
+- `make test-e2e TEST_ARGS="-run TestName"` — single e2e test
+- `make codegen` — regenerate CRDs, RBAC, DeepCopy from API types
+- `make lint` / `make lint-fix` — golangci-lint v2
+- `make build` — build broker binary
+- `make build-operator` — build operator binary
+- `make run` — run broker locally (debug logging)
+- `make run-operator` — run operator locally (debug logging)
+- `make examples` — run all example walkthroughs
+- `make help` — list all targets
+
+## Structure
+
+```
+api/              CRD types, grouped by domain
+  broker/         AcceptAPI, Migration, MigrationConfiguration
+  generic/        Cross-cloud APIs (databases, networking, storage, compute, etc.)
+  example/        Example CRDs (Certificate, VM)
+  operator/       Broker operator CRD
+cmd/              Entrypoints
+  main.go         resource-broker
+  operator/       resource-broker-operator
+pkg/              Core logic
+  broker/         Reconcilers (acceptapi, generic, migration)
+  sync/           Resource copy and condition tracking
+  conditions/     Status condition utilities
+  kubernetes/     Annotation and map helpers
+config/           Kustomize manifests (CRDs, RBAC, deployment)
+test/             E2e tests and test utilities
+examples/         Runnable walkthroughs (certs, kcp-certs, platform-mesh)
+contrib/kcp/      kcp-specific Dockerfile and config
+```
+
+## Architecture
+
+Three cluster roles: coordination, consumer, provider. Two separate binaries: **operator** (single-cluster, manages Broker CRD, deploys broker) and **broker manager** (multi-cluster, runs reconcilers).
+
+### Reconciliation Flow
+
+1. Consumer resource created → consumer watch triggers GenericReconciler
+2. `decorateInConsumer()` adds finalizer + annotations
+3. `providerAcceptsObj()` queries AcceptAPI registry (in-memory map protected by lock)
+4. Resource copied to provider with hashed cluster prefix in name (`SanitizeClusterName()` → 12-char hex) to avoid multi-consumer collisions
+5. Provider watch triggers via `providerEventHandler` which maps back to consumer using annotations
+6. Status synced back to consumer via status subresource, with prefixes stripped by `StatusTransformer`
+7. Related resources (declared in `status.relatedResources`) copied to consumer with owner references
+
+### Provider Churn
+
+If AcceptAPI no longer matches, reconciler sets `new-provider-cluster` annotation, syncs to new provider, waits for readiness, then deletes from old provider.
+
+### Migration
+
+Staged state machine: Unknown → Pending → InitialInProgress → InitialCompleted → CutoverInProgress → CutoverCompleted. Each stage deploys template resources and evaluates CEL expressions against them before progressing.
+
+### Key Annotations (control plane)
+
+- `broker.platform-mesh.io/consumer-cluster`, `consumer-name` — origin tracking
+- `broker.platform-mesh.io/provider-cluster` — current provider
+- `broker.platform-mesh.io/new-provider-cluster` — migration target
+
+### Constants
+
+- Cluster prefixes: `consumer`, `provider`, `coordination` (`pkg/broker/broker.go`)
+- Finalizers: `broker.platform-mesh.io/acceptapi-finalizer`, `broker.platform-mesh.io/generic-finalizer`
+- AcceptAPI filters: ValueIn (enum), Boundary (min/max), Suffix (string suffix) — keys use dot notation for nested spec fields
+
+## Code Conventions
+
+License header on all `.go` files — Apache-2.0, "The Platform Mesh Authors". Enforced by goheader linter.
+
+Import order (enforced by gci):
+1. stdlib
+2. third-party
+3. `k8s.io/`
+4. `sigs.k8s.io/controller-runtime/`
+5. `sigs.k8s.io/multicluster-runtime/`
+6. `github.com/platform-mesh/`
+
+Tests: testify (require/assert). E2e: controller-runtime envtest. All tests must be parallel (paralleltest linter).
+
+Run `make codegen` after any change to `api/` types.
+
+## Git
+
+Conventional Commits: `feat:`, `fix:`, `chore(deps):`, `ci:`, `refactor:`, `test:`, `docs:`
+
+Never add AI attribution to commits or PRs.
+
+## Do Not
+
+- Edit `zz_generated.deepcopy.go` — generated by controller-gen
+- Edit `config/*/crd/*.yaml` directly — generated by `make manifests`
+- Skip the license header — CI enforces it
+- Add tool-specific instruction files (`CLAUDE.md`, `.cursorrules`, etc.) — use this file
+- Commit without running `make codegen` after API type changes

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to resource-broker
+
+## General Remarks
+
+You are welcome to contribute content (code, documentation etc.) to this open source project.
+
+There are some important things to know:
+
+1. You must **comply to the license of this project**, **accept the Developer Certificate of Origin** (see below) before being able to contribute. The acknowledgement to the DCO will usually be requested from you as part of your first pull request to this project.
+2. Please **adhere to our [Code of Conduct](https://github.com/platform-mesh/.github/blob/main/CODE_OF_CONDUCT.md)**.
+3. If you plan to use **generative AI for your contribution**, please see our [guideline for AI-generated code contributions](https://github.com/platform-mesh/.github/blob/main/CONTRIBUTING_USING_GENAI.md).
+4. **Not all proposed contributions can be accepted**. Some features may fit another project better or don't fit the general direction of this project. Of course, this doesn't apply to most bug fixes, but a major feature implementation for instance needs to be discussed with one of the maintainers first. The best way would be to just open an issue to discuss the feature you plan to implement (make it clear that you intend to contribute).
+
+## Developer Certificate of Origin (DCO)
+
+Contributors will be asked to accept a DCO before they submit the first pull request to this project, this happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
+
+## How to Contribute
+
+1. Make sure the change is welcome (see [General Remarks](#general-remarks)).
+2. Fork the repository and create a branch.
+3. Make your changes and verify them locally:
+   - Run `make check` to run code generation, linting, and all tests.
+   - See [DEVELOPEPMENT.md](DEVELOPEPMENT.md) for all available make targets.
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/) format (e.g. `feat:`, `fix:`, `chore:`).
+5. Create a pull request.
+6. Follow the link posted by the CLA assistant to your pull request and accept it, as described above.
+7. Wait for code review and approval, possibly enhancing your change on request.
+
+## Development
+
+Prerequisites: Go (see version in `go.mod`), Docker, kubectl.
+
+Key commands:
+
+- `make check` — full validation (codegen + lint + test + test-e2e)
+- `make test` — unit tests
+- `make test-e2e` — end-to-end tests
+- `make codegen` — regenerate CRDs, RBAC, and DeepCopy after API type changes
+- `make lint-fix` — lint and auto-fix
+- `make run` — run broker locally with debug logging
+
+See [DEVELOPEPMENT.md](DEVELOPEPMENT.md) for the full list.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache-2.0 License](LICENSE).