chore(ai): initiale AGENTS.md file (#902)

* chore(ai): initiale AGENTS.md file

* chore: restructure AGENTS.md to provide behavioral guidelines for LLM coding practices

* chore(ai): structure AGENTS.md guidance per monorepo area

- Condense generic preamble in root AGENTS.md; fix factual errors
  (golangci-lint is CI-only, *_types.go, commit scopes, monorepo map)
- Add scoped AGENTS.md for api/v1alpha1 (CRD codegen) and deploy (Helm)
- Refine controllers and ui guidance to match real stack
- Add CLAUDE.md symlinks so each area has a single maintained file

---------

Co-authored-by: Guillaume Leccese <guillaume.leccese@theodo.com>
Co-authored-by: Nicolas Levée <nicolas.levee@theodo.com>

Author: 3 people

.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(**/zz_generated.deepcopy.go)",
+      "Read(**/zz_generated.register.go)",
+      "Read(**/yarn.lock)",
+      "Read(**/go.sum)",
+      "Read(config/crd/bases/**)",
+      "Read(config/webhook/**)",
+      "Read(manifests/**)",
+      "Read(ui/node_modules/**)"
+    ]
+  }
+}

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md — Burrito
+
+Monorepo for **Burrito**: a Kubernetes operator that automates Terraform (TACoS).
+This file is the canonical guidance for AI agents. `CLAUDE.md` is a symlink to it.
+Nested `AGENTS.md` files add directory-specific rules — read them when working in their scope.
+
+## Working Principles
+
+- **Think first.** State assumptions; if multiple interpretations exist, surface them instead of picking silently. If something is unclear, ask.
+- **Simplicity.** Minimum code that solves the problem. No speculative features, abstractions, or config that wasn't requested.
+- **Surgical changes.** Touch only what the task requires. Match existing style. Don't refactor or reformat unrelated code; flag dead code rather than deleting it.
+- **Verify.** Turn tasks into checkable goals and run the relevant build/test/lint command before claiming done.
+
+## Monorepo Map
+
+- `api/v1alpha1/` — CRD Go types (see nested AGENTS.md). **Codegen-sensitive.**
+- `internal/controllers/` — reconciliation logic, one package per resource (see nested AGENTS.md).
+- `ui/` — React/Vite/TS dashboard (see nested AGENTS.md).
+- `deploy/charts/burrito/` — Helm chart (see nested AGENTS.md).
+- `cmd/` — binary entrypoints. `hack/` — dev/build scripts. `manifests/` & `config/crd/bases/` — generated manifests. `testdata/` — fixtures. `docs/` — documentation.
+
+## Never Touch (generated / vendored)
+
+Do not read, edit, or use as reference:
+
+- `*zz_generated.deepcopy.go` (produced by `controller-gen`).
+- Lock files: `go.sum`, `ui/yarn.lock`.
+- Generated manifests in `config/crd/bases/` and `manifests/`.
+
+To change CRDs: edit `api/v1alpha1/*_types.go`, then run `make manifests` (and `make generate`).
+
+## Build & Validation
+
+- **Go:** `make build` · `make test` (spins up envtest + docker-compose — heavy) · `make vet`
+- **Lint (Go):** `golangci-lint run ./...` — there is no `make` target; it runs in CI ([.github/workflows/ci.yaml](.github/workflows/ci.yaml)).
+- **After API changes:** `make manifests && make generate`
+- **UI:** `yarn --cwd ui lint` · `yarn --cwd ui build` · `yarn --cwd ui format-check`
+
+## Go Style
+
+- Always check errors explicitly. Never `_ = err` or silently ignored returns.
+- No `panic()` in reconcilers — see `internal/controllers/AGENTS.md`.
+
+## Commits — Conventional Commits
+
+Format: `<type>(<scope>): <description>`.
+
+- **Types:** `feat`, `fix`, `chore`, `docs`, `test`, `refactor`.
+- **Scopes** (use the closest fit): `controller`, `api`, `ui`, `helm`, `ci`, `deps`, `docker`. Scope is optional when none applies.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

api/v1alpha1/AGENTS.md

@@ -0,0 +1,18 @@
+# Scope: CRD API Types (`api/v1alpha1/`)
+
+Source of truth for Burrito's Custom Resource Definitions. **Codegen-sensitive directory.**
+
+Type files (edit these): `terraformlayer_types.go`, `terraformrun_types.go`,
+`terraformrepository_types.go`, `terraformpullrequest_types.go`, `common.go`.
+`groupversion_info.go` registers the scheme.
+
+## Rules
+
+- To change an API, edit only the Go structs in `*_types.go`. Keep `+kubebuilder:` marker
+  comments accurate — they drive CRD generation and validation.
+- **Never hand-edit `zz_generated.deepcopy.go`.** It is generated by `controller-gen`.
+- After any change to types or markers, run `make manifests && make generate`, and tell the
+  user to commit the regenerated output. Do not edit `config/crd/bases/` or `manifests/` directly.
+- Treat the CRD shape as a contract: the `ui/` TypeScript interfaces mirror these structs —
+  flag breaking field changes.
+- Tests live alongside types (`common_test.go`); keep them passing with `make test`.

api/v1alpha1/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

deploy/AGENTS.md

@@ -0,0 +1,15 @@
+# Scope: Helm Chart (`deploy/`)
+
+The Burrito Helm chart lives in `deploy/charts/burrito/` (templates under `templates/`).
+
+## Rules
+
+- Keep `values.yaml` the single source of defaults; expose new behavior through values rather
+  than hardcoding it in templates. Document every new value.
+- Templates must stay in sync with the CRDs in `api/v1alpha1` and the controller's expected
+  config. If a chart change requires updated CRD manifests, regenerate them with `make manifests`
+  (don't hand-edit generated CRD YAML).
+- Bump `Chart.yaml` `version` (chart) / `appVersion` (image) appropriately when changing the chart.
+- Validate before declaring done: `helm lint deploy/charts/burrito` and
+  `helm template deploy/charts/burrito` render without errors.
+- Use scope `helm` for commits touching this directory.

deploy/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

internal/controllers/AGENTS.md

@@ -0,0 +1,17 @@
+# Scope: Kubernetes Controllers (`internal/controllers/`)
+
+Go core engine, built on `controller-runtime` / Kubebuilder. One reconciler package per
+custom resource: `terraformlayer/`, `terraformrun/`, `terraformrepository/`,
+`terraformpullrequest/`. `metrics/` holds Prometheus instrumentation. `manager.go` wires them.
+
+## Rules & Gotchas
+
+- Follow standard `controller-runtime` reconciliation patterns and the Kubebuilder layout.
+- Reconcilers must be **idempotent** — they can run on the same object repeatedly.
+- Never block the reconcile loop. For retries/transient failures, return a requeue
+  (`ctrl.Result{RequeueAfter: ...}`), do not sleep.
+- **Never `panic()`.** Return an error or a requeue.
+- Always check errors explicitly — no `_ = err`.
+- Use structured logging via the `logr.Logger` carried in `ctx` (`log.FromContext(ctx)`).
+- Propagate `ctx` and set timeouts on every external call (GitHub, GitLab, Terraform).
+- CRD shapes live in `api/v1alpha1`; never edit generated deepcopy code. After API changes run `make manifests && make generate`.

internal/controllers/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md