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

[kelos-bot]

🤖 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 (fix: raise NDJSON parser scanner buffer to 10 MB #1190, Drop ValidArgsFunction from 'kelos create workspace' #1180, docs: fix Workspace schema and deprecated bodyContains in example 10 #1179, self-development: document modern webhook filter fields in README #1178, docs: replace deprecated bodyContains and add {{.Schedule}} in integration guide #1176, docs: document kelos completion subcommand and dynamic shell completion #1171, Fix CLI SOURCE column for GitHub/Slack TaskSpawners #1168, Raise kelos-workers and kelos-pr-responder maxConcurrency to 8 #1167, docs: link webhook-concurrency.md and gateway-api-webhook.md from navigation #1166, Warn agents not to poll with self-matching pgrep -f #1165, docs: add cursor credential setup guidance to init and README #1164, Document Task credential secret key format in reference.md #1161, Update codex image to 0.132.0 #1158, Update claude-code image to 2.1.145 #1157, Add user-writable bin directory to agent image PATH #1153, Update opencode image to 1.15.5 #1148, Update cursor image to 2026.05.16-0338208 #1141, docs: fix ttlSecondsAfterFinished indentation in examples 11 and 13 #1140, Fix kelos-fake-strategist README description #1139, fix: Expand tilde in GitHub App privateKeyPath #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

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}