From d62f94c173aa8298a6f92641081f2bf4a13bf19b Mon Sep 17 00:00:00 2001 From: Jaison Paul Date: Mon, 9 Mar 2026 22:54:45 -0400 Subject: [PATCH 1/3] docs: rename CLAUDE.md to AGENTS.md Rename to a tool-agnostic filename that works across all AI coding agents, not just Claude Code. Signed-off-by: Jaison Paul --- CLAUDE.md => AGENTS.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename CLAUDE.md => AGENTS.md (100%) diff --git a/CLAUDE.md b/AGENTS.md similarity index 100% rename from CLAUDE.md rename to AGENTS.md From 97e8815bdc3a8e1ad54ed238bc0bdb82eed65b42 Mon Sep 17 00:00:00 2001 From: Jaison Paul Date: Mon, 9 Mar 2026 22:55:22 -0400 Subject: [PATCH 2/3] docs: expand AGENTS.md with code reuse, naming, and architecture sections - Add code reuse section to discourage duplicating functions/utilities - Add naming conventions section requiring descriptive variable and function names across all languages - Expand repo structure with docker, contrib, design, docs, scripts, test - Add per-language development details (Go modules, Python tooling, UI stack) - Add CI/CD pipeline breakdown and architectural patterns (MCP, memory, SDK) - Fix make lint description to clarify it only covers Go + Python - Add separate UI lint command (npm -C ui run lint) Signed-off-by: Jaison Paul --- AGENTS.md | 285 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 174 insertions(+), 111 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e85c54d21..86dd76c97 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,29 +1,15 @@ -# CLAUDE.md - Kagent Development Guide +# AGENTS.md - Kagent Repository Guide for AI Agents -This document provides essential guidance for AI agents working in the kagent repository. - ---- - -## Development Workflow Skill - -**For detailed development workflows, use the `kagent-dev` skill.** The skill provides comprehensive guidance on: - -- Adding CRD fields (step-by-step with examples) -- Running and debugging E2E tests -- PR review workflows -- Local development setup -- CI failure troubleshooting -- Common development patterns - -The skill includes detailed reference materials on CRD workflows, translator patterns, E2E debugging, and CI failures. +This document provides instructions and context for AI coding agents working in the kagent repository. --- ## Project Overview -**Kagent** is a Kubernetes-native framework for building, deploying, and managing AI agents. +**Kagent** is a Kubernetes-native framework for building, deploying, and managing AI agents. It is in **alpha stage (v0.x.x)**. **Architecture:** + ``` ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Controller │ │ HTTP Server │ │ UI │ @@ -37,7 +23,9 @@ The skill includes detailed reference materials on CRD workflows, translator pat └─────────────┘ └──────────────┘ ``` -**Current Version:** v0.x.x (Alpha stage) +- **Go** — Kubernetes controllers, HTTP server, CLI, database layer, Go ADK +- **Python** — Agent runtime, AI/ML logic, LLM integrations, Python ADK +- **TypeScript** — Next.js web UI only --- @@ -45,65 +33,83 @@ The skill includes detailed reference materials on CRD workflows, translator pat ``` kagent/ -├── go/ # Go workspace (go.work) -│ ├── api/ # Shared types: CRDs, ADK types, DB models, HTTP client -│ ├── core/ # Infrastructure: controllers, HTTP server, CLI -│ └── adk/ # Go Agent Development Kit -├── python/ # Agent runtime and ADK -│ ├── packages/ # UV workspace packages (kagent-adk, etc.) -│ └── samples/ # Example agents -├── ui/ # Next.js web interface -├── helm/ # Kubernetes deployment charts -│ ├── kagent-crds/ # CRD chart (install first) -│ └── kagent/ # Main application chart -└── .claude/skills/kagent-dev/ # Development skill +├── go/ # Go workspace (go.work) +│ ├── api/ # Shared types: CRDs (v1alpha2), DB models, HTTP client SDK +│ ├── core/ # Kubernetes controllers, HTTP server, CLI +│ │ └── test/e2e/ # End-to-end tests (SQLite + PostgreSQL) +│ └── adk/ # Go Agent Development Kit +├── python/ # Python workspace (UV) +│ ├── packages/ # kagent-adk, kagent-core, kagent-skills, etc. +│ └── samples/ # Example agents +├── ui/ # Next.js web interface +├── helm/ # Kubernetes deployment charts +│ ├── kagent-crds/ # CRD chart (install first) +│ └── kagent/ # Main application chart +├── docker/ # Dockerfiles for all images +├── contrib/ # Community addons, tools, integrations +├── design/ # Architecture enhancement proposals (EP-*.md) +├── docs/ # Documentation +├── examples/ # Sample configurations +├── scripts/ # Build and deployment scripts +├── test/ # Integration tests +├── .github/workflows/ # CI/CD pipelines +├── Makefile # Top-level build orchestration +├── DEVELOPMENT.md # Detailed development setup +└── CONTRIBUTING.md # Contribution standards ``` --- ## Language Guidelines -### When to Use Each Language +| Language | Use For | Do Not Use For | +|----------------|------------------------------------------------------|--------------------------------------| +| **Go** | K8s controllers, CLI, core APIs, HTTP server, DB | Agent runtime, LLM integrations, UI | +| **Python** | Agent runtime, ADK, LLM integrations, AI/ML logic | K8s controllers, CLI, infrastructure | +| **TypeScript** | Web UI components and API clients only | Backend logic, controllers, agents | -| Language | Use For | Don't Use For | -|----------|---------|---------------| -| **Go** | K8s controllers, CLI tools, core APIs, HTTP server, database layer | Agent runtime, LLM integrations, UI | -| **Python** | Agent runtime, ADK, LLM integrations, AI/ML logic | Kubernetes controllers, CLI, infrastructure | -| **TypeScript** | Web UI components and API clients only | Backend logic, controllers, agents | +--- -**Rule of thumb:** Infrastructure in Go, AI/Agent logic in Python, User interface in TypeScript. +## Build & Test Commands + +| Task | Command | +|--------------------------|----------------------------------------| +| Build all images | `make build` | +| Build CLI | `make build-cli` | +| Run all tests | `make test` | +| Run Go E2E tests | `make -C go e2e` | +| Lint Go + Python | `make lint` | +| Lint Go only | `make -C go lint` | +| Lint UI | `npm -C ui run lint` | +| Generate CRD code | `make -C go generate` | +| Create Kind cluster | `make create-kind-cluster` | +| Deploy kagent | `make helm-install` | +| Helm template tests | `make helm-test` | +| CVE scan | `make audit` | +| Access UI | `kubectl port-forward -n kagent svc/kagent-ui 3000:8080` | + +Before submitting changes, run `make lint` for Go/Python changes, and for UI changes run `npm -C ui run lint` and the relevant UI tests. --- -## Core Conventions +## Go Development -### Error Handling +### Module Layout -**Go:** -```go -// Always wrap errors with context using %w -if err != nil { - return fmt.Errorf("failed to create agent %s: %w", name, err) -} -``` +The Go code lives under `go/` with three modules managed by `go.work`: -**Controllers:** -```go -// Return error to requeue with backoff -if err != nil { - return ctrl.Result{}, fmt.Errorf("reconciliation failed: %w", err) -} -``` +- **`go/api`** — Foundation layer. CRD types (`v1alpha2`), database models, HTTP client SDK, shared utilities. +- **`go/core`** — Infrastructure layer. Kubernetes controller (`cmd/controller`), HTTP server, MCP integration, metrics, E2E tests. +- **`go/adk`** — Agent Development Kit. Agent runner, session management, skills, models, memory, telemetry. -### Testing +### Conventions -**Required for all PRs:** -- ✅ Unit tests for new functions/methods -- ✅ E2E tests for new CRD fields or API endpoints -- ✅ Mock external services (LLMs, K8s API) in unit tests -- ✅ All tests passing in CI pipeline +- Wrap errors with context: `fmt.Errorf("failed to create agent %s: %w", name, err)` +- Controllers should return errors to requeue with backoff. +- Run `gofmt -w` on changed files before committing. +- Run `golangci-lint run` before submitting (CI enforces this). +- Use table-driven tests: -**Go testing pattern (table-driven):** ```go func TestSomething(t *testing.T) { tests := []struct { @@ -115,7 +121,6 @@ func TestSomething(t *testing.T) { {name: "valid input", input: "foo", want: "bar", wantErr: false}, {name: "invalid input", input: "", want: "", wantErr: true}, } - for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { got, err := Something(tt.input) @@ -130,85 +135,143 @@ func TestSomething(t *testing.T) { } ``` -### Commit Messages +- Go tests run with `-race` flag in CI. +- E2E tests run against both SQLite and PostgreSQL. + +--- + +## Python Development + +- Python 3.10+ required. +- Uses **UV** for dependency management across workspace packages. +- **Ruff** for linting and formatting (120-char line limit). +- **Pytest** for testing (async auto mode). +- CI tests across Python 3.10-3.13. +- Key packages: `kagent-adk`, `kagent-core`, `kagent-skills`, `kagent-crewai`, `kagent-langgraph`, `kagent-openai`. + +--- + +## UI Development + +- **Next.js** with React, TypeScript, Tailwind CSS, Radix UI. +- **Zod** for validation, **Zustand** for state management, **React Hook Form** for forms. +- Do not use `any` type in TypeScript. +- ESLint for linting, Jest for unit tests, Cypress for E2E tests. + +--- + +## API Versioning + +- **v1alpha2** — Current. All new features go here. +- **v1alpha1** — Legacy/deprecated. Do not modify unless fixing critical bugs. + +Key CRDs: `Agent`, `ModelConfig`, `ModelProviderConfig`, `RemoteMCPServer`. -Use **Conventional Commits** format: +Breaking changes are acceptable in alpha versions. + +--- + +## CI/CD Pipeline + +The main CI workflow (`.github/workflows/ci.yaml`) runs on pushes/PRs to `main` and release branches: + +1. **Go** — Unit tests with race detection, E2E tests (SQLite + PostgreSQL), golangci-lint +2. **Python** — Tests on 3.10-3.13, ruff linting, format validation +3. **UI** — ESLint, Jest unit tests +4. **Helm** — Chart unit tests, manifest verification +5. **Docker** — Multi-platform builds (amd64, arm64) for controller, ui, app, cli, golang-adk, skills-init + +Additional workflows: image scanning, release tagging, stale issue management. + +--- + +## Commit Messages + +Use **Conventional Commits**: ``` : [optional body] + +Signed-off-by: Name ``` -**Types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci` +Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci` -**Examples:** -``` -feat: add support for custom service account in agent CRD -fix: enable usage metadata in streaming OpenAI responses -docs: update CLAUDE.md with testing requirements -``` +All commits require `Signed-off-by` trailer (DCO). Use `git commit -s` or run `make init-git-hooks`. --- -## API Versioning +## Testing Requirements -- **v1alpha2** (current) - All new features go here -- **v1alpha1** (legacy/deprecated) - Minimal maintenance only +All PRs must include: -Breaking changes are acceptable in alpha versions. +- Unit tests for new functions/methods +- E2E tests for new CRD fields or API endpoints +- Mocked external services (LLMs, K8s API) in unit tests +- All tests passing in CI --- -## Best Practices +## Key Architectural Patterns + +### MCP Integration +- Reference-based architecture (no embedded details in CRDs) +- Supports MCPServer CRD, Kubernetes Services, and RemoteMCPServer +- Protocols: SSE and STREAMABLE_HTTP +- Built-in tools: Kubernetes, Istio, Helm, Argo, Prometheus, Grafana, Cilium + +### Memory System +- PostgreSQL + pgvector for production, Turso/libSQL for development +- 768-dimensional embeddings with cosine similarity search (threshold 0.3) +- Dual save: explicit (via tools) + implicit (auto-save every 5 turns) +- 15-day memory expiration with intelligent retention -### Do's ✅ +### HTTP Client SDK +- Located in `go/api/client/` +- Covers Agent, Session, Tool, Memory, Model, ModelConfig, ModelProviderConfig operations -- Read existing code before making changes -- Follow the language guidelines (Go for infra, Python for agents, TS for UI) -- Write table-driven tests in Go -- Wrap errors with context using `%w` -- Use conventional commit messages -- Mock external services in unit tests -- Update documentation for user-facing changes -- Run `make lint` before submitting +--- -### Don'ts ❌ +## Code Reuse -- Don't add features beyond what's requested (avoid over-engineering) -- Don't modify v1alpha1 unless fixing critical bugs (focus on v1alpha2) -- Don't vendor dependencies (use go.mod) -- Don't commit without testing locally first -- Don't use `any` type in TypeScript -- Don't skip E2E tests for API/CRD changes -- Don't create new MCP servers in the main kagent repo +- Before writing new code, search the codebase for existing functions, utilities, and patterns that already solve the problem. +- Do not duplicate logic. If similar functionality exists, refactor it into a shared helper or reuse the existing implementation. +- Shared Go utilities belong in `go/api/` (types, models, client SDK) — not duplicated across `go/core/` and `go/adk/`. +- Shared Python utilities belong in `kagent-core` — not duplicated across other packages. +- If you find duplicated code while working on a change, consolidate it as part of your PR when the scope is reasonable. --- -## Quick Reference +## Naming Conventions -| Task | Command | -|------|---------| -| Create Kind cluster | `make create-kind-cluster` | -| Deploy kagent | `make helm-install` | -| Build all | `make build` | -| Run all tests | `make test` | -| Run E2E tests | `make -C go e2e` | -| Lint code | `make -C go lint` | -| Generate CRD code | `make -C go generate` | -| Access UI | `kubectl port-forward -n kagent svc/kagent-ui 3000:8080` | +- Use **descriptive variable and function names** across all languages. Names should clearly convey purpose and intent. +- Avoid abbreviations and single-letter names (except loop counters like `i`, `j`). Use `agentConfig` not `ac`, `modelProvider` not `mp`, `sessionID` not `sID`. +- Function names should describe what they do: `createAgentFromSpec` not `makeAgent`, `validateModelConfig` not `checkCfg`. +- Go: Follow standard Go naming (camelCase for unexported, PascalCase for exported). Receiver names can be short (1-2 chars) per Go convention. +- Python: Use snake_case for functions/variables, PascalCase for classes. +- TypeScript: Use camelCase for functions/variables, PascalCase for components and types. --- -## Additional Resources +## What Not to Do -- **Development setup:** See [DEVELOPMENT.md](DEVELOPMENT.md) -- **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md) -- **Architecture:** See [docs/architecture/](docs/architecture/) -- **Examples:** Check `examples/` and `python/samples/` +- Do not add features beyond what is requested (avoid over-engineering). +- Do not modify v1alpha1 unless fixing critical bugs. +- Do not vendor dependencies (use go.mod). +- Do not commit without running tests locally. +- Do not use `any` type in TypeScript. +- Do not skip E2E tests for API/CRD changes. +- Do not create new MCP servers in the main kagent repo. +- Do not duplicate existing functions or utilities — reuse what already exists. --- -**Project Version:** v0.x.x (Alpha) +## Additional Resources -For questions or suggestions about this guide, please open an issue or PR. +- [DEVELOPMENT.md](DEVELOPMENT.md) — Detailed local development setup +- [CONTRIBUTING.md](CONTRIBUTING.md) — Contribution process and standards +- [docs/architecture/](docs/architecture/) — Architecture documentation +- [design/](design/) — Enhancement proposals (EP-*.md) +- [examples/](examples/) and [python/samples/](python/samples/) — Sample configurations From 2dcb52671c77e29ada00c210ae5b3eeb00372d68 Mon Sep 17 00:00:00 2001 From: Jaison Paul Date: Wed, 11 Mar 2026 18:52:32 -0400 Subject: [PATCH 3/3] docs: add CLAUDE.md referencing AGENTS.md Ensures Claude Code automatically loads AGENTS.md instructions by adding a CLAUDE.md pointer file. Signed-off-by: Jaison Paul --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..a7185235c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +Follow all instructions in [AGENTS.md](AGENTS.md).