Development Guide

This guide covers the repository layout and how to build and test each component. The process for issues, ideas, and pull requests is on the Contributing page; the conventions a change is expected to follow are summarized at the end of this one.

Repositories

Layout of the kubemoot repository

Prerequisites

• Go 1.27+ (operator, Go components)
• Java 25+ with Gradle (agent runtime, indexer, MCP gateway)
• Node.js 26+ (dashboard)
• kubectl and helm (v3.8+, for OCI charts)
• Access to a Kubernetes cluster; kind works for the quickstart

Build and test

Every change ships with tests. Run the suite for the component you touched.

Operator (operator/):

cd operator
make generate manifests   # generate code and CRD manifests
make build                # build the operator
make test                 # unit tests (Go envtest)
make lint                 # golangci-lint

To run the operator against your current kubeconfig context:

make install   # install the CRDs
make run       # run the operator locally

After changing CRDs, run make manifests generate, copy the generated CRDs to the chart, sync the RBAC into the chart templates, and commit the generated zz_generated.deepcopy.go.

Agent runtime and other Java components (agent-runtime/, indexer/, mcp-gateway/):

./gradlew test

Use plain JUnit 5, not @QuarkusTest, so the suite does not require a running Ollama.

Go components (mcp-bridge/, scheduling-mcp/, artifact-access/, code-sandbox/, discussion-gateway/, crew-liaison/, fitness-runner/):

go test ./...

Dashboard (dashboard/):

npm install
npm test          # vitest
npm run lint      # eslint
npm run check     # svelte-check

Quickstart smoke test. For any change to the kubemoot repo, run the quickstart on an empty kind cluster. It installs the operator, a small CPU model, and a two-agent crew, asks the crew a question, and checks that an answer comes back. CI runs the same script against every release’s images.

kind create cluster --name kubemoot
./quickstart/quickstart.sh

Integration tests run against a cluster with Kubemoot installed:

cd k8s/tests
./test-smoke.sh     # fast subset
./test-all.sh       # full suite

See k8s/tests/README.md for what each test covers.

Other repositories

kmctl requires Go 1.27+:

make build      # build the ./kmctl binary
make test       # unit tests with coverage
make test-race  # unit tests with the race detector (needs CGO)
make lint       # golangci-lint
make hooks      # install the pre-commit gate (gofmt and lint)

crews. Each subdirectory is an independently versioned Helm chart. To add a crew, create <your-crew>/ with Chart.yaml, values.yaml, templates/, and a fitness/ directory of scenarios, then add a release workflow modeled on an existing one under .github/workflows/. A merge to main builds a release candidate and pushes it to the maintainers’ registry; the Promote Release workflow publishes the final chart to GHCR and creates the GitHub Release.

Documentation. Each component’s reference docs live in that component’s docs/ directory. The site is built from the kubemoot-docs repo with Hugo; npm install followed by hugo server previews it.

Conventions

A few project rules a reviewer looks for:

• Conventional commits. Commit prefixes drive semantic versioning. Versions come from git tags via the pipeline; never hand-edit a version in a manifest. See Releases.
• Prompts in ADL. All agent prompt text lives in PromptModule resources written in ADL (the Architecture Definition Language), never inline in an Agent spec. See Write Agents & ADL.
• Code quality. Keep functions at cyclomatic complexity 10 or less; refactor rather than adding a case to an already complex function.
• Lifecycle belongs to the operator. Cleanup, garbage collection, and namespace management are handled in the operator with finalizers and owner references, not in client-side tools.

Naming

Using the same kebab-case identifiers in Helm charts, manifests, and the dashboard keeps copy-paste across layers working, and short names keep kubectl get output scannable.

Project direction

Where the project is headed is sketched in the Roadmap.