Development Guide

Set up a development environment: repository layout, prerequisites, and how to build and test each component.

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

RepositoryWhat it holds
kubemootThe operator, agent runtime, dashboard, MCP components, and the component docs
crewsPackaged crews as Helm charts
kmctlThe command-line tool
vscode-crewforgeCrewForge for VS Code
kubemoot-docsThis site: the Hugo and Docsy shell and the cross-cutting chapters

Layout of the kubemoot repository

ComponentPathLanguage / stack
Operatoroperator/Go, controller-runtime, kubebuilder CRDs
Agent runtimeagent-runtime/Java / Quarkus + LangChain4j (GraalVM Community native)
Dashboarddashboard/SvelteKit
MCP bridge, scheduling and tool serversmcp-bridge/, scheduling-mcp/, accelerator-mcp/, workspace-access/, code-sandbox/Go
MCP gatewaymcp-gateway/Java
Discussion gateway, crew liaison, fitness runnerdiscussion-gateway/, crew-liaison/, fitness-runner/Go
Indexerindexer/Java
Query servicequery-service/Python
Quickstartquickstart/Shell
Integration testsk8s/tests/Shell

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; needs helm on PATH to render the chart's use-grant policies)
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 the API types or RBAC markers, run make manifests generate (it also copies the CRDs and the manager role into the chart) and commit the generated files. CI regenerates them and fails when they differ from what is committed.

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

./gradlew build   # tests plus Checkstyle (cyclomatic complexity <= 10)

Checkstyle reads the shared ruleset in config/checkstyle/checkstyle.xml. Use plain JUnit 5, not @QuarkusTest, so the suite does not require a running Ollama.

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

go test ./...
../.github/scripts/golangci-lint.sh   # golangci-lint

Every Go module, the operator included, lints with the shared .golangci.yml at the repository root (cyclomatic complexity <= 10, duplication, and the rest) at the GOLANGCI_LINT_VERSION pinned in operator/Makefile.

A module’s go directive must not be newer than the golang: builder in the Dockerfile that compiles it, because the image builds with GOTOOLCHAIN=local. CI runs .github/scripts/check-go-builder-version.sh on every pull request that changes a go.mod or a Dockerfile, so a Dependabot bump of one without the other fails the pull request instead of the release workflow. The daily Release Status workflow also fails, and lists the workflow, when the latest run on main of any component release workflow failed.

Native image check (agent-runtime): the native binary is built and run without a cluster. The CI job native-check starts .github/scripts/stub-mcp-server.py (two tools over the HTTP+SSE transport) and the binary with KUBEMOOT_NATIVE_SELFTEST=true, which runs the paths native compilation can break (result type detection with Jackson and SnakeYAML, readTree, a record listed in the reflection configuration) and logs NATIVE_SELFTEST_OK or exits 1; the check then reads /tools and expects the stub’s two tools. It runs on a pull request that changes the agent-runtime dependencies, the native configuration, ResultType, NativeSelfTest or the check itself, and on a manual dispatch of CI Agent Runtime with native_check. To run it locally against a built binary: .github/scripts/run-native-check.sh agent-runtime/build/agent-runtime-*-runner.

Query service (query-service/):

pip install --require-hashes -r requirements.txt -r requirements-lint.txt
ruff check .
python -m unittest discover -s . -p 'test_*.py'

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, and Publish Release runs it end to end on the release candidate before it publishes anything: a candidate that fails the quickstart is not published.

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

The smoke test also asks a question. It asks a Ready crew that holds discussions: one whose coordinator Agent (discussRole: coordinator) lists the general channel in discussChannels. A crew without that never orchestrates a thread, so it can not answer. Set SMOKE_CREW=<namespace>/<crew> to choose the crew (the Integration Test workflow takes it as the optional smoke_crew input). With no such crew and no SMOKE_CREW the check skips with “no Ready crew holds discussions”. The test publishes one short question on the crew’s bus subject and one on its request queue, and waits for the coordinator’s synthesis on each thread. A crew that stays silent fails the test with the thread id and the last message seen, and the test then sends the Stop message the dashboard sends so the thread does not stay active. The wait ends when the answer arrives; ASK_TIMEOUT (480 seconds by default) is a safety net. The post-deploy Integration Test runs this after every operator chart release, so a Ready crew that never answers can not pass.

The smoke test also checks a ModelServer of any engine. It takes the first Ready ModelServer, vLLM or Ollama (one without a secretRef first), and checks what every engine supports: the operator published the server as Ready, and the server answers its models list at <endpoint>/v1/models. For a vLLM server the endpoint is the first one it serves. The check creates nothing. It fails when the ModelServers cannot be listed, or exist and none is Ready, and skips when the namespace has none. A server with a secretRef is checked for Ready only; its models list is not requested, since the check sends no credentials.

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 Publish Release workflow runs the quickstart on that candidate, then publishes the final chart to GHCR, creates the GitHub Release, and asks the crews, kmctl and CrewForge to build candidates against the new release (a dry run lists what it would ask and asks nothing). Its run summary lists the release status of the six public repositories, and warns about any that hold unpublished breaking changes until their own Publish Release runs. A daily workflow runs the same check and opens one issue when a public repository has held an unpublished breaking change for more than a day; it closes the issue when none does.

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

ItemConventionExample
API groupkubemoot.aiapiVersion: kubemoot.ai/v1alpha1
CRD kindsSingular, CamelCaseModelServer, Agent, CrewSchedulingPolicy
Short namesLowercase abbreviations, chosen when the CRD is designedmdls, mdl, emb, mcp, mcpgw, rag, csp, pm
Brand names in prose and UICrewForge, Homelab Pilot, Kubemoot“Install Kubemoot”
Names in code and configKebab-case identifiersvscode-crewforge, homelab-pilot, kubemoot

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.