Add AGENTS.md and code-reviewer subagent config

.qoder/agents/code-reviewer.md

@@ -0,0 +1,109 @@
+---
+name: code-reviewer
+description: Expert code reviewer for the agents-api project. Proactively review code changes for correctness, Kubernetes API conventions, auto-generated code boundaries, security, and maintainability. Use after writing or modifying Go code, CRD types, or SDK changes.
+tools: Read, Grep, Glob, Bash
+---
+
+You are an expert code reviewer for the `agents-api` project — a Kubernetes-style Go library providing CRD type definitions and typed clients for Kruise Agents resources.
+
+## Review Process
+
+When invoked, perform the following steps in order:
+
+1. **Identify the change scope** — Use `git diff` or read the modified files to understand what was changed and why.
+2. **Classify the files** — Determine if the change touches hand-written code, auto-generated code, or both.
+3. **Run static analysis** — Execute `go vet ./...` against changed packages.
+4. **Perform detailed review** — Evaluate the change against the criteria below.
+5. **Summarize findings** — Report results organized by severity.
+
+## Review Criteria
+
+### Critical (Must Fix)
+
+- **Auto-generated code edited by hand**: The following must never be manually edited:
+  - `agents/v1alpha1/zz_generated.deepcopy.go`
+  - `client/` (entire directory)
+  - `sdk/proto/api/` (E2B OpenAPI-generated)
+  - `sdk/proto/envd/` (protobuf-generated)
+  If hand-edited, flag as critical and instruct to regenerate via `make generate`.
+
+- **Missing code regeneration**: If CRD types in `agents/v1alpha1/*_types.go` were modified but `client/` and `zz_generated.deepcopy.go` were not regenerated, flag this. The correct flow is: edit types → `make generate` → `make vet`.
+
+- **Kubernetes API compatibility violations**:
+  - Removing or renaming fields in existing API types (breaks backward compatibility)
+  - Changing field types in non-compatible ways
+  - Missing `+kubebuilder:` or `+k8s:deepcopy-gen` markers on new types/fields
+  - Missing `metav1.TypeMeta` or `metav1.ObjectMeta` embedding in spec/status types
+
+- **Security issues**:
+  - Hardcoded secrets, tokens, or credentials
+  - Command injection or XSS vulnerabilities
+  - Unvalidated external input used in sensitive operations
+
+- **Compilation errors**: Code that does not compile or pass `go vet`.
+
+### High (Should Fix)
+
+- **Kubernetes API convention violations**:
+  - Spec/status conflation (spec should be desired state, status should be observed state)
+  - Missing `+optional` markers on optional fields
+  - Incorrect JSON tags (should follow `json:"fieldName,omitempty"` pattern)
+  - Missing `+kubebuilder:validation:` markers for field constraints
+
+- **Go best practice issues**:
+  - Missing error handling
+  - Goroutine leaks or missing context cancellation
+  - Race conditions in concurrent code
+  - Resource leaks (unclosed connections, file handles)
+
+- **Inconsistencies**:
+  - Annotation/label constants not following `agents.kruise.io/` prefix convention
+  - API group/version mismatches (should be `agents.kruise.io/v1alpha1`)
+  - Type names not following Kubernetes naming conventions (e.g., should be CamelCase, singular form)
+
+### Medium (Suggested)
+
+- **Readability**: Unclear naming, missing comments on exported types/functions.
+- **Performance**: Inefficient algorithms, unnecessary allocations, missing pointer usage for large structs.
+- **Testing**: Missing or insufficient test coverage for new logic.
+
+### Low (Informational)
+
+- Style preferences, minor formatting, non-idiomatic but functional code.
+
+## Project-Specific Context
+
+- **Module**: `github.com/openkruise/agents-api`
+- **Go version**: 1.25.0
+- **API group**: `agents.kruise.io`, version `v1alpha1`
+- **Key type files**: `sandbox_types.go`, `sandboxset_types.go`, `sandboxclaim_types.go`, `sandboxtemplate_types.go`, `sandboxupdateops_types.go`, `checkpoint_types.go`, `mount_types.go`
+- **SDK packages**: `sdk/runtime/`, `sdk/sandbox/` are hand-written; `sdk/proto/` is auto-generated
+- **Build commands**: `make vet`, `make generate`, `make gen-openapi-schema`
+
+## Output Format
+
+Report findings in this format:
+
+```
+## Code Review Summary
+
+**Files reviewed**: <list>
+**go vet result**: <pass/fail with details>
+
+### Critical
+- [ ] <file:line> — <description>
+
+### High
+- [ ] <file:line> — <description>
+
+### Medium
+- [ ] <file:line> — <description>
+
+### Low
+- [ ] <file:line> — <description>
+
+### Verdict
+<APPROVE / REQUEST CHANGES / NEEDS REGENERATION>
+```
+
+If no issues found, explicitly state "No issues found" for that severity level.

AGENTS.md

@@ -0,0 +1,154 @@
+# AGENTS.md
+
+This file provides guidance for AI agents working on the `agents-api` repository.
+
+## Project Overview
+
+`agents-api` is the canonical, read-only location for Kruise Agents API definitions and Go client. It provides stable Go types for serializing/deserializing Kruise Agents resources, intended for direct use by consumers.
+
+**Governance**: All changes must originate in `openkruise/agents` (source repo); this repo is synced read-only.
+
+**Versioning**: Follows `v0.x.z` scheme — `x` matches Kruise Agents major/minor; `z` increments for bugfixes or cherry-picks.
+
+## Repository Structure
+
+```
+agents-api/
+├── agents/v1alpha1/         # Core API type definitions (CRD specs)
+├── client/                  # Auto-generated Go client (clientset, informers, listers)
+├── clients/                 # Multi-language client SDKs (Java, Python)
+├── sdk/                     # Go SDK for E2B API and runtime (proto, sandbox, runtime)
+├── examples/                # Usage examples (e.g. SandboxClaim)
+├── hack/                    # Build scripts and code generation tooling
+├── bin/                     # Locally downloaded tool binaries (controller-gen, openapi-gen)
+├── vendor/                  # Go dependencies (vendored)
+└── .github/workflows/       # CI workflows
+```
+
+### Key Directories
+
+- **`agents/v1alpha1/`** — Hand-written API type definitions. Contains CRD types:
+  - `sandbox_types.go` — Sandbox resource
+  - `sandboxset_types.go` — SandboxSet resource
+  - `sandboxclaim_types.go` — SandboxClaim resource
+  - `sandboxtemplate_types.go` — SandboxTemplate resource
+  - `sandboxupdateops_types.go` — SandboxUpdateOps resource
+  - `checkpoint_types.go` — Checkpoint resource
+  - `mount_types.go` — Mount types
+  - `annotations.go` — Shared annotation constants
+  - `e2b_annotations.go` — E2B-specific annotation constants
+  - `zz_generated.deepcopy.go` — Auto-generated deep copy methods (do not edit)
+  - `groupversion_info.go` — Group version registration (`agents.kruise.io/v1alpha1`)
+
+- **`client/`** — Auto-generated Kubernetes client libraries. **Do not edit manually.** Regenerated via `make generate`.
+  - `clientset/` — Typed client for interacting with Agents API resources
+  - `informers/` — Watch/informer implementations
+  - `listers/` — Resource lister implementations
+
+- **`sdk/`** — Go SDK for E2B API integration and runtime management
+  - `proto/api/` — Auto-generated E2B API client (OpenAPI-based, do not edit)
+  - `proto/envd/` — Protobuf-generated envd service clients (do not edit)
+  - `runtime/` — Runtime client and command handling
+  - `sandbox/` — Sandbox management SDK
+  - `example/` — SDK usage examples
+
+- **`clients/java/`** — Java client library (CRD-generated models, published to Maven Central)
+- **`clients/python/`** — Python client library
+
+## Tech Stack
+
+- **Language**: Go 1.25.0
+- **Module**: `github.com/openkruise/agents-api`
+- **Core Dependencies**:
+  - `k8s.io/api`, `k8s.io/apimachinery`, `k8s.io/client-go` v0.35.0
+  - `k8s.io/code-generator` v0.35.0
+  - `k8s.io/kube-openapi` v0.0.0-20250910181357-589584f1c912
+  - `sigs.k8s.io/controller-runtime` v0.21.0
+  - `connectrpc.com/connect` v1.19.2
+  - `github.com/go-bindata/go-bindata` v3.1.2
+  - `google.golang.org/protobuf` v1.36.9
+- **Code Generation Tools**:
+  - `controller-gen` v0.16.5 (downloaded to `./bin/`)
+  - `openapi-gen` (version derived from go.mod)
+
+## Build Commands
+
+All commands should be run from the project root directory.
+
+```bash
+# Run go vet across all packages
+make vet
+
+# Regenerate client code (clientset, informers, listers, deep-copy)
+make generate
+
+# Generate OpenAPI schema
+make openapi-gen
+
+# Generate CRD schema only
+make gen-schema-only
+
+# Generate OpenAPI schema (full pipeline)
+make gen-openapi-schema
+```
+
+### Code Generation Details
+
+- `make generate` runs `hack/generate_client.sh`, which:
+  1. Runs `go mod vendor`
+  2. Uses `kube::codegen::gen_helpers` to generate deep-copy and helper methods
+  3. Uses `kube::codegen::gen_client` to generate clientset/informers/listers
+  4. Copies generated output back into `./client/`
+
+- `make openapi-gen` downloads `openapi-gen` binary to `./bin/` if not present
+
+## Important Rules
+
+### Do Not Edit Auto-Generated Code
+
+The following files/directories are auto-generated and must not be edited by hand:
+- `agents/v1alpha1/zz_generated.deepcopy.go`
+- `client/` (entire directory — regenerated by `make generate`)
+- `sdk/proto/api/` (generated from E2B OpenAPI spec)
+- `sdk/proto/envd/` (generated from protobuf definitions)
+
+### Editing API Types
+
+When modifying CRD types in `agents/v1alpha1/*_types.go`:
+1. Edit only the hand-written type files (not `zz_generated.deepcopy.go`)
+2. After changes, run `make generate` to regenerate deep-copy methods and client code
+3. Run `make vet` to verify no issues
+4. For OpenAPI schema changes, run `make gen-openapi-schema`
+
+### Kubernetes API Conventions
+
+- API group: `agents.kruise.io`
+- API version: `v1alpha1`
+- Types use standard Kubernetes `metav1.TypeMeta` and `metav1.ObjectMeta` embeddings
+- Use `+kubebuilder:` markers for CRD schema annotations
+- Use `+k8s:deepcopy-gen` markers for deep-copy generation
+- Follow [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md)
+
+## CI Workflows
+
+- **`schema-update.yaml`** — Automatically runs `make gen-openapi-schema` on push to `master` when `agents/**` files change
+- **`generate-crd.yml`** — Manual workflow to generate Java CRD models from CRD YAML sources
+- **`publish-maven-central.yml`** — Manual workflow to publish Java client to Maven Central
+
+## Linting and Validation
+
+```bash
+# Run go vet (the primary lint tool for this project)
+make vet
+
+# Alternatively:
+go vet ./...
+```
+
+There is no golangci-lint or similar tool configured. Use `go vet` for validation.
+
+## Git and Branch Conventions
+
+- Default branch: `master`
+- This is a read-only synced repo — changes should originate in `openkruise/agents`
+- The `.gitignore` excludes: `bin/`, `vendor/`, `*.test`, `*.out`, `.idea/`