chore: add agents.md (#190)

Author: CodeReaper

.cspell.json

@@ -6,6 +6,7 @@
   "language": "en",
   "version": "0.2",
   "words": [
+    "agentic",
     "apiextensions",
     "apimachinery",
     "apiserver",
@@ -25,7 +26,9 @@
     "genall",
     "gofmt",
     "jsonschema",
+    "kopium",
     "krusty",
+    "kubeconform",
     "kustomization",
     "kustomizations",
     "kustomizer",

AGENTS.md

@@ -0,0 +1,130 @@
+# AGENTS.md
+
+This file provides guidelines for agents working in this repository.
+
+## Project Overview
+
+This is the CRD Catalog - a tool that aggregates hundreds of popular Kubernetes CRDs (CustomResourceDefinition) including their JSON schema format. The catalog is used for validation (kubeconform), code generation (kopium), and language server support.
+
+## Build, Lint, and Test Commands
+
+### Running Tests
+
+**Full test suite:**
+
+```bash
+make test
+```
+
+This runs on PRs to main via GitHub Actions (`.github/workflows/tests.yaml`). It includes:
+
+- Go unit tests with coverage
+- Schema validation
+- Smoke tests with Docker
+- Makefile linting
+- EditorConfig checks
+
+**Run Go unit tests locally:**
+
+```bash
+go test ./... -timeout 10s -shuffle on -p 1 -tags containers_image_openpgp -skip 'TestCheckLocal'
+```
+
+**Run a single test:**
+
+```bash
+go test ./... -run TestName -timeout 10s
+```
+
+Note: `-skip 'TestCheckLocal'` is required because that test is for manual debugging of uncommitted configuration files and should not run in normal test execution.
+
+### Static Analysis and Formatting
+
+**Format check:**
+
+```bash
+gofmt -l .
+```
+
+**Go vet:**
+
+```bash
+go vet ./...
+```
+
+**Check for mod file changes:**
+
+```bash
+go mod tidy -diff
+```
+
+### Build
+
+```bash
+go build -o build/bin/catalog -buildvcs=false -tags containers_image_openpgp
+```
+
+## Code Style Guidelines
+
+### Go Conventions
+
+- **Formatting**: Use `gofmt` (standard Go formatter). All code should be formatted before committing.
+- **Language**: Go (version managed automatically by GitHub workflows)
+- **Testing**: Uses testify/assert for assertions
+- **Error handling**:
+  - Use sentinel errors with `errors.New` for defined error cases
+  - Use `errors.Join` to combine multiple errors
+- **CLI**: Uses standard `flag` package for command-line argument parsing
+- **Build tags**: Required tag is `containers_image_openpgp`
+- **Comments**: Do NOT add comments unless explicitly requested
+
+### EditorConfig (Non-Go Files)
+
+Follow the settings in `.editorconfig`.
+
+## GitHub Workflows
+
+`.github/dependabot.yml`:
+
+- **dependabot.yml**: Weekly updates for GitHub Actions and Go module dependencies
+
+`.github/workflows/`:
+
+- **tests.yaml**: Runs `make test` on PRs to main, auto-merges bot PRs (dependabot, crd-automation)
+- **scheduled-jobs.yaml**: Runs on a schedule every few hours:
+  - `make update` - fetches CRD schemas from Helm charts
+  - `make comparison` - compares with datreeio/CRDs-catalog
+  - `make tags` - synchronizes Kubernetes version tags
+- **upgrade-go.yaml**: Weekly check for Go updates, automatically upgrades go.mod and .tool-versions via PR
+
+## Project Structure
+
+```
+/schema          # Generated OpenAPI schema files
+/definitions     # Generated definition files (for kopium)
+/configuration.yaml  # CRD sources configuration
+/registry.yaml   # Tracks source versions
+/internal/       # Go source code
+  /command/      # CLI commands (compare, update, verify)
+/make.d/         # Makefile includes
+/test/           # Test fixtures and scripts
+```
+
+## Configuration
+
+The main configuration file is `configuration.yaml`. It defines CRD sources (Helm charts, URLs, etc.) that are fetched to generate the schema and definition files.
+
+The configuration file can be validated against the JSON schema at `internal/configuration/schema.json` using:
+
+```bash
+go run . verify --schema internal/configuration/schema.json --file configuration.yaml
+```
+
+## Important Notes
+
+- Do NOT commit changes to `/schema`, `/definitions`, `registry.yaml` directly - these are generated by the `make update` workflow
+- The `.tool-versions` file is managed automatically by GitHub workflows
+
+## Maintaining AGENTS.md
+
+This file documents project conventions for agentic coding tools. Update this file to reflect changes when adding new commands, changing build processes, updating dependencies, or modifying code style conventions. Agents operating in this repository should follow the guidelines outlined here.