docs: add AGENTS.md contributor and agent guide - #180
Merged
Conversation
Add a root AGENTS.md following the agents.md convention, read by Claude Code, Codex, Cursor, Aider, and other agent tooling as well as by humans. It documents the operator's shape for anyone (human or agent) landing in the repo: the single NebariApp CRD, the Core/TLS/Routing/Auth reconciler pipeline and its reverse-order cleanup, namespace opt-in, the make targets for build/test/lint/codegen, the rule that generated files and RBAC come from markers plus make (never hand-edits), status-condition conventions, and the pre-commit checklist. Mirrors the structure of the sibling nebari-infrastructure-core AGENTS.md.
viniciusdc
commented
Aug 14, 2026
Co-authored-by: Vinicius D. Cerutti <51954708+viniciusdc@users.noreply.github.com>
Make the make-targets section of AGENTS.md machine-generated so it cannot silently drift from the Makefile, and fill the two gaps in the guide. - hack/gen-agents.sh regenerates the block between the 'BEGIN/END GENERATED: make-targets' markers from the Makefile's own ##@ section headers and '## ' help comments (the data 'make help' prints). Wired to a 'make agents' target. - build-pr.yml runs 'make agents' and 'git diff --exit-code AGENTS.md' in the lint job, so a stale table fails CI -- the same drift-gate already used for 'make manifests' and 'make docs'. Regenerating on this branch immediately surfaced targets the hand-written draft missed (helm-test, helm-lint-library, helm-test-generate-golden). - Add a Releases section describing the tag-triggered release.yml pipeline (tests -> manifests -> goreleaser images+binaries -> helm chart -> sync to helm-repository), and record that versioning is EffVer from v0.1.0, not SemVer. - Add a 'Who applies the NebariApp CRD' section pointing at software-pack-template (example collection), data-science-pack, and nebi-pack (live consumers). - A 'Keeping This File Current' section documents which parts are generated vs hand-authored.
viniciusdc
commented
Aug 14, 2026
Correct typos and improve clarity in AGENTS.md.
…before-PR guidance - Fix the typos in the 'Who applies the NebariApp CRD' intro sentence. - Add a Testing section describing the three suites: envtest-backed unit tests next to each reconciler/util, the Ginkgo e2e suite under test/e2e (real cluster, -tags=e2e, testdata fixtures), and the nebari-app Helm golden tests (make helm-test / helm-test-generate-golden). States the 'never disable a test to go green' rule. - Rework the Documentation section into a directive: read the relevant design docs and decision records BEFORE opening a PR, and update a record in the same PR when a change contradicts it. Enumerate the actual docs/decisions, docs/design, docs/plans, and docs/reconcilers files so they are discoverable, and ask contributors to link new docs here.
Add a light/dark SVG pair for the reconcile pipeline and embed it under 'The Reconciler Pipeline' via a <picture> element that swaps on prefers-color-scheme, above the existing text flow (kept as the precise fallback). Nebari-teal rail with numbered stations for the four ordered reconcilers (Core, TLS, Routing, Auth) between the NebariApp CR input and the Ready terminal; an elbow loop shows the continuous requeue and a dashed line the reverse-order finalizer cleanup.
Updated comment to reflect correct command for refreshing.
… formatting change
azure/setup-helm's 'version: latest' now resolves to Helm 4, but the nebari-app library golden tests were generated with Helm 3. Helm 4 emits a trailing newline for multi-document template output, so the 'multi' case fails with a spurious golden mismatch (38a39) even though the templates are unchanged. Pin both setup-helm steps in this workflow to v3.19.0 so chart rendering is deterministic and matches the committed goldens. test-chart.yml and release.yml default to the same 'latest' and should be pinned too in a follow-up.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a root
AGENTS.mdfollowing the agents.md convention - read by Claude Code, Codex, Cursor, Aider, and other agent tooling, and a fast-orientation guide for humans. The operator had noAGENTS.md/CLAUDE.md, so newcomers reverse-engineered the layout each time. Structured after the siblingnebari-infrastructure-coreAGENTS.md.Parts of the file are generated so they cannot silently drift from the code they describe; the rest is hand-authored.
Contents
NebariAppCR -> routing, TLS, auth, landing-page registration) and its place in NIC.NebariAppCRD - the downstream consumers:software-pack-template(the canonical example collection: raw YAML / Helm / Kustomize / wrap-existing-chart + CRD reference),data-science-pack, andnebi-pack(live consumers shipping atemplates/nebariapp.yaml).maketarget (see below).reconcilers.nebari.dev/v1), the Core -> TLS -> Routing -> Auth pipeline with reverse-order cleanup, platform assumptions.release.ymlpipeline (tests -> manifests -> GoReleaser images+binaries -> Helm chart -> sync tohelm-repository), and that versioning is EffVer fromv0.1.0(ADR-003), not SemVer.Generated make-targets (no-drift)
The make-targets tables live between
<!-- BEGIN/END GENERATED: make-targets -->markers and are produced byhack/gen-agents.shfrom the Makefile's own##@section headers and##help comments - the same datamake helpprints. Runmake agentsto refresh.build-pr.yml's lint job runsmake agentsthengit diff --exit-code AGENTS.md, so a stale table fails CI - the identical drift-gate already used formake manifestsandmake docs. Regenerating on this branch immediately surfaced targets a hand-written list had missed (helm-test,helm-lint-library,helm-test-generate-golden), which is exactly the drift this closes.Only the make-targets block is generated. Everything else is prose; a
Keeping This File Currentsection spells out which is which and how to add a new generated block later.Note for reviewers
This PR touches
.github/workflows/build-pr.yml(adds the AGENTS.md drift-check to thelintjob). #179 also edits that file (thechangesjob +build-multiarchgate). The two changes are in different regions and should auto-merge; if not, they are trivial to reconcile.docs/maintainers/release-process.mdstill says "semantic versioning"; AGENTS.md notes it is due an update to EffVer. Not changed here to keep this PR docs-additive.Test plan
make agentsis idempotent and, run against the committed tree, produces no diff (the CI gate passes).hack/gen-agents.shpassesbash -n;build-pr.ymlparses as valid YAML.