Merge pull request #2763 from Nordix/tuomo/add-copilot-instructions

📖 add AGENTS.md

Author: metal3-io-bot

.gitignore

@@ -64,3 +64,6 @@ config/overlays/temp
 
 # VS Code settings
 .vscode/
+
+# ai stuff
+.claude

AGENTS.md

@@ -0,0 +1,106 @@
+# Metal3 Baremetal Operator (BMO) - AI Agent Instructions
+
+Instructions for AI coding agents. For project overview, see [README.md](README.md).
+For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Repository Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `apis/metal3.io/v1alpha1/` | CRD types (BareMetalHost, HostFirmwareSettings, etc.) - separate Go module |
+| `internal/controller/metal3.io/` | Reconciliation logic with state machine |
+| `internal/webhooks/metal3.io/` | Validation/defaulting webhooks |
+| `pkg/provisioner/` | Provisioner interface (ironic, fixture, demo) |
+| `pkg/hardwareutils/` | BMC protocol handling - separate Go module |
+| `config/` | Kustomize manifests (CRDs, RBAC, webhooks) - auto-generated by `make manifests`, rarely edit directly |
+| `hack/` | CI scripts (prefer Make targets locally) |
+| `test/e2e/` | E2E tests with libvirt VMs |
+
+## Testing Standards
+
+CI uses GitHub Actions (`.github/workflows/`) and [Prow](https://github.com/metal3-io/project-infra/blob/main/prow/config/jobs/metal3-io/baremetal-operator.yaml).
+Run these locally before submitting PRs:
+
+**Make targets:**
+
+| Command | Purpose |
+|---------|---------|
+| `make test` | Full verification (generate + lint + unit) |
+| `make generate` | Regenerate Go code (deepcopy functions) |
+| `make manifests` | Regenerate CRDs, RBAC, webhooks |
+| `make unit` | Unit tests (requires envtest - do not use `go test` directly) |
+| `make lint` | Go linting via golangci-lint (all modules) |
+| `make mod` | Verify go.mod is tidy |
+
+**Hack scripts** (auto-containerized, match CI exactly):
+
+| Script | Purpose |
+|--------|---------|
+| `./hack/shellcheck.sh` | Shell script linting (shellcheck) |
+| `./hack/markdownlint.sh` | Markdown linting (config: `.markdownlint-cli2.yaml`) |
+| `./hack/manifestlint.sh` | Kubernetes manifest validation (kubeconform) |
+
+## Code Conventions
+
+- **Go**: Linting rules in `.golangci.yaml`, license headers in `hack/boilerplate.go.txt`
+- **Shell**: Use `set -o errexit -o nounset -o pipefail`
+- **Markdown**: 3-space indent for lists (`.markdownlint-cli2.yaml`)
+
+## Key Workflows
+
+### Modifying APIs
+
+1. Edit `apis/metal3.io/v1alpha1/*_types.go`
+1. Run `make generate manifests`
+1. Update webhooks in `internal/webhooks/` if validation changes
+1. Run `make test`
+
+## E2E Testing
+
+BMO has standalone E2E tests using libvirt VMs and BMC emulators:
+
+| Command | Purpose |
+|---------|---------|
+| `./hack/ci-e2e.sh` | Full E2E suite (requires libvirt, docker) |
+| `GINKGO_FOCUS="inspection" ./hack/ci-e2e.sh` | Run specific test |
+| `BMC_PROTOCOL=ipmi ./hack/ci-e2e.sh` | Test with IPMI protocol |
+
+Key files: `test/e2e/config/ironic.yaml`, `test/e2e/config/fixture.yaml`
+
+## Code Review Guidelines
+
+When reviewing pull requests:
+
+1. **Security** - Hardcoded secrets, unpinned dependencies, missing input validation
+1. **Test coverage** - New functionality should have tests
+1. **Consistency** - Match existing patterns in the codebase
+1. **Breaking changes** - Flag API/behavior changes affecting users
+
+Focus on: `internal/controller/`, `pkg/provisioner/`, `apis/`, `internal/webhooks/`.
+
+## AI Agent Guidelines
+
+### Before Changes
+
+1. Run `make unit` to verify baseline
+1. Check patterns in similar existing files
+
+### When Making Changes
+
+1. Make minimal, surgical edits
+1. Run `make generate manifests` after API changes
+1. Run `make test` before committing
+1. Add tests for new functionality
+
+### Security Requirements
+
+- Pin external dependencies by SHA (containers, GitHub Actions, binaries)
+- No hardcoded credentials
+- Validate all inputs
+
+## Related Documentation
+
+- [API Documentation](docs/api.md)
+- [State Machine](docs/baremetalhost-states.md)
+- [Release Process](docs/releasing.md)
+- [Metal3 Book](https://book.metal3.io/bmo/introduction)

CLAUDE.md

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