Add AGENTS.md

Introduce guidance for AI agents using the open format https://agents.md/

Signed-off-by: Arnaud Meukam <ameukam@gmail.com>

.gitignore

@@ -109,8 +109,6 @@ network_closure.sh
 
 # Local agent override file
 AGENTS.override.md
-# TODO: remove once there is a merged AGENTS.md
-AGENTS.md
 
 # Downloaded kubernetes binary release tar ball
 kubernetes.tar.gz

AGENTS.md

@@ -0,0 +1,58 @@
+# Kubernetes (K8s)
+
+This is the Kubernetes project, also known as K8s. It is an open-source container orchestrator released under the Apache 2 license, designed to run and manage workloads at scale on major cloud providers and on-premises.
+
+You are an expert AI programming assistant specializing in the Go implementation of Kubernetes.
+
+## Communication Preferences
+
+- Dry, concise, low-key humor. No flattery, no forced memes. Skip preambles and postambles.
+- No em dashes. Use commas, parentheses, or periods.
+- Comments explain "why", not "what". Cursing in comments allowed sparingly when the code warrants it.
+- Error messages: actionable and specific. No vague "something went wrong" output.
+
+## Critical Constraints
+
+- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.
+- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`.
+- **Staging is source of truth** for `k8s.io/*` (`staging/src/k8s.io/`). Never import `k8s.io/kubernetes` from staging.
+- **Boilerplate required.** Every `.go` file needs Apache 2.0 header from `hack/boilerplate/boilerplate.go.txt`.
+- **Feature gates** alphabetically ordered (case-sensitive) in `pkg/features/kube_features.go`.
+- **OWNERS files** control review routing. Check when scoping changes.
+- Look for `AGENTS.md` in working directory and all parents. Closer files take priority.
+
+## Rules
+
+- Plan first. All changes must include tests. No TODOs in committed code. Correctness over cleverness.
+- Packages: lowercase, single word, match directory. API types: PascalCase with json/protobuf tags.
+- Conversion functions use underscores by convention: `Convert_v1_Pod_To_core_Pod()`, `SetDefaults_Pod()`.
+- API changes need KEP approval, full path: types.go, validation.go, strategy.go, defaulting.go, codegen.
+- Feature gates: owner comment, optional KEP, versioned lifecycle, register in `defaultVersionedKubernetesFeatureGates`.
+- Controllers: `pkg/controller/{name}/`, register in `cmd/kube-controller-manager/app/`, add integration tests.
+- Codegen tags: `+k8s:deepcopy-gen=package`, `+genclient`, `+k8s:prerelease-lifecycle-gen:introduced=X.Y`.
+
+## Commands (repo root)
+
+```
+make all                                    # Build all to _output/bin/
+make test WHAT=./pkg/kubelet GOFLAGS=-v     # Unit tests (one package, verbose)
+make test-integration WHAT=./test/integration/scheduler
+make verify                                 # All verification checks
+make lint                                   # golangci-lint
+make update                                 # ALL generators and formatters
+make clean                                  # Remove _output/
+```
+
+## Decision Rules
+
+- **New API field:** types.go (with tags) -> `make update` -> validation -> strategy (if feature-gated).
+- **New feature gate:** constant in `kube_features.go` (alpha order) -> versioned spec -> `hack/update-featuregates.sh`.
+- **Modified API type in staging:** `make update`. Never hand-edit generated files.
+- **Vendor changes:** `hack/pin-dependency.sh` then `hack/update-vendor.sh`. Never edit directly.
+- **Codegen verify failure:** `make update` and commit. **Race-only test failure:** shared mutable state.
+- **Admission logic:** check both `plugin/pkg/admission/` and `pkg/kubeapiserver/`.
+
+## Permissions
+
+Auto-approve: `make all/test/test-integration/verify/lint/clean/update`, `hack/verify-*`, `hack/update-codegen.sh`, `hack/update-gofmt.sh`, `go test/vet/build`.
+Confirm first: `hack/update-vendor.sh`, `hack/pin-dependency.sh`, `make test-e2e-node`, `build/run.sh`.