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
| Repository | What it holds |
|---|---|
| kubemoot | The operator, agent runtime, dashboard, MCP components, and the component docs |
| crews | Packaged crews as Helm charts |
| kmctl | The command-line tool |
| vscode-crewforge | CrewForge for VS Code |
| kubemoot-docs | This site: the Hugo and Docsy shell and the cross-cutting chapters |
Layout of the kubemoot repository
| Component | Path | Language / stack |
|---|---|---|
| Operator | operator/ | Go, controller-runtime, kubebuilder CRDs |
| Agent runtime | agent-runtime/ | Java / Quarkus + LangChain4j (GraalVM Community native) |
| Dashboard | dashboard/ | SvelteKit |
| MCP bridge, scheduling and tool servers | mcp-bridge/, scheduling-mcp/, accelerator-mcp/, workspace-access/, code-sandbox/ | Go |
| MCP gateway | mcp-gateway/ | Java |
| Discussion gateway, crew liaison, fitness runner | discussion-gateway/, crew-liaison/, fitness-runner/ | Go |
| Indexer | indexer/ | Java |
| Query service | query-service/ | Python |
| Quickstart | quickstart/ | Shell |
| Integration tests | k8s/tests/ | Shell |
Prerequisites
- Go 1.27+ (operator, Go components)
- Java 25+ with Gradle (agent runtime, indexer, MCP gateway)
- Node.js 26+ (dashboard)
kubectlandhelm(v3.8+, for OCI charts)- Access to a Kubernetes cluster;
kindworks 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
PromptModuleresources 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
| Item | Convention | Example |
|---|---|---|
| API group | kubemoot.ai | apiVersion: kubemoot.ai/v1alpha1 |
| CRD kinds | Singular, CamelCase | ModelServer, Agent, CrewSchedulingPolicy |
| Short names | Lowercase abbreviations, chosen when the CRD is designed | mdls, mdl, emb, mcp, mcpgw, rag, csp, pm |
| Brand names in prose and UI | CrewForge, Homelab Pilot, Kubemoot | “Install Kubemoot” |
| Names in code and config | Kebab-case identifiers | vscode-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.