self-development: add CRD, e2e, agent-image, and Dockerfile-pin conventions from recent reviews

KE
5mo ago
+24-0

🤖 Kelos Agent @gjkim42

What type of PR is this?

/kind cleanup

What this PR does / why we need it:

Adds eight new agent conventions to AGENTS.md (with CLAUDE.md symlink) and the inline agentsMD copies in self-development/agentconfig.yaml and self-development/kelos-workers.yaml. Each rule is backed by specific review findings on kelos-bot–generated PRs from the past 7 days.

Original motivating PRs (initial commit):

PR #1154 (feat: Support env.valueFrom in MCP server config). The Kelos API Reviewer flagged three independent issues:

  1. CRD admission validation must match runtime checks. The PR's controller rejects valueFrom.fieldRef/resourceFieldRef/fileKeyRef at reconcile time, but the generated CRD (which embeds the full corev1.EnvVar schema) lets admission accept them. Reviewer's verdict: "once a CRD ships, what its schema accepts is effectively part of the contract — please tighten this at admission rather than at reconcile", suggesting +kubebuilder:validation:XValidation CEL rules or a narrowed Kelos-specific type. Cubic flagged a closely related issue: "valueFrom is not validated as exclusive, so unsupported fieldRef/resourceFieldRef can slip through". ➜ Codified.

  2. Mirror upstream Kubernetes semantics when reusing upstream types. The PR's resolver emits an entry with empty Value when valueFrom.secretKeyRef.optional: true and the secret/key is missing. Reviewer pointed out that kubelet, for a pod EnvVar with Optional=true and a missing key, does not set the variable on the container — surfacing FOO="" is "a non-obvious foot-gun". ➜ Codified.

  3. Breaking CRD storage-shape changes need explicit upgrade notes in release-note. The PR changes mcpServers[].env from map[string]string to []corev1.EnvVar (object → array). Reviewer: "This is a hard break for stored v1alpha1 AgentConfig objects… but the release-note only mentions the YAML shape change. Suggest extending the release note (or adding an upgrade note) to call out that existing in-cluster AgentConfig objects with mcpServers[].env set need to be re-applied after the upgrade." ➜ Codified.

PR #1175 (Drop removed --enable skills flag from codex entrypoint). Reviewer feedback from gjkim42: "this should not be a codex specific e2e test" (on test/e2e/skills_test.go). The agent initially added a codex-only e2e test for a Task with an AgentConfig that has a plugin; after the request, the agent rewrote it to parameterize across agentConfigs. ➜ Codified as a convention to always parameterize e2e tests for shared agent functionality across all supported agent types.

PR #1177 (docs: refresh model ID examples and document shorthand format). Reviewer feedback from gjkim42: "why don't we use a shorthand?". The original docs showed only versioned IDs like claude-sonnet-4-20250514; the agent revised to show shorthand (sonnet, opus) alongside the versioned form. ➜ Codified as a convention to prefer agent-native model shorthands in docs/examples.

Additional motivating PRs (follow-up commit):

PR #1194 (Wire Antigravity CLI as a first-class agent type — OPEN). The PR adds an antigravity/ image directory plus a kind-load step but does not extend the Task.spec.type / TaskTemplate.type +kubebuilder:validation:Enum, JobBuilder (internal/controller/job_builder.go), the apiKeyEnvVar/oauthEnvVar credential mapping, docs/agent-image-interface.md, or any e2e exercising the new type. The Kelos API Reviewer flagged: "the new agent is not reachable through the existing CRD API — that itself is an API gap worth resolving (or explicitly deferring) before merge." The same PR also drew two reproducibility findings:

  1. Cubic [P2] on antigravity/Dockerfile:41: "The agy install step is unpinned, so rebuilds can silently pick up new upstream versions and produce non-reproducible images."
  2. Kelos reviewer [P3] on the same line: "bash <(curl https://antigravity.google/cli/install.sh) fetches the latest agy build with no version arg and no checksum verification, so two rebuilds of the same Dockerfile commit can yield different agy binaries… matching the GEMINI_CLI_VERSION/OPENCODE_VERSION/CURSOR_CLI_VERSION pattern in the sibling images."

➜ Codified two conventions: end-to-end wiring required when adding a new agent runtime image, and pinning third-party CLI installs in agent-image Dockerfiles.

PR #1189 (Stream agent output through kelos-capture instead of writing to /tmp — OPEN). Both cubic [P2] and the Kelos reviewer [P2] flagged the same issue on internal/capture/usage.go:46: "Final flush error gets dropped. Buffered write can fail at EOF and function still returns success. Check and return bw.Flush() error." / "defer bw.Flush() discards the flush error… if it fails (e.g., transient stdout/pod-log writer failure), StreamUsage returns nil and the trailing buffered bytes silently disappear from pod logs. Capture the flush error explicitly so it surfaces, e.g. via a named return and defer func() { if ferr := bw.Flush(); err == nil { err = ferr } }()." ➜ Codified as a convention to propagate deferred Close()/Flush() errors via a named return.

Which issue(s) this PR is related to:

N/A

Special notes for your reviewer:

  • Only AGENTS.md is a real file; CLAUDE.md is a symlink to it, so a single edit covers both surfaces.
  • The same bullets are added to the inline agentsMD in self-development/agentconfig.yaml and self-development/kelos-workers.yaml, which is the existing pattern for keeping agentsMD in sync with AGENTS.md.
  • Other recent merged kelos-generated PRs from the last 7 days (#1190, #1180, #1179, #1178, #1176, #1171, #1168, #1167, #1166, #1165, #1164, #1161, #1158, #1157, #1153, #1148, #1141, #1140, #1139, #1135) received only "No issues found" reviews, paid-trial-expired notices, or feedback already covered by existing conventions, so no additional rules were added for them.

Does this PR introduce a user-facing change?

NONE

🤖 Generated with Claude Code