---
title: Build, Test & Lint
description: "The root Makefile workflow — building the Go modules, running race tests, the local CI gate, and golangci-lint setup."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

The root `Makefile` drives every sibling Go module. Each module is independently `go build`/`go test`able with its own `go.mod`.

## Toolchain

<Columns cols={2}>
  <Card title="Go 1.22+" icon="golang">
    Every `go.mod` pins `go 1.21`; 1.22+ is recommended for local dev.
  </Card>
  <Card title="GNU make 4.x" icon="hammer">
    Drives build, install, test, vet, and the CI gate.
  </Card>
  <Card title="Node 20+, Python 3.11+, uv" icon="boxes-stacked">
    Needed for the MCP-server-driven flows.
  </Card>
  <Card title="Docker 24+ (buildx)" icon="docker">
    Needed only to build the daemon image.
  </Card>
</Columns>

## Common targets

```bash
make build           # build all Go modules
make install         # drop the runnable CLIs into ./bin
make test            # go test -count=1 -race ./... per module
make vet             # go vet ./... per module
make ci              # gofmt-check + vet + tests (mirrors GitHub Actions)
make version         # print Go + golangci-lint + Docker versions
```

<Tip>
A clean `make ci` is the bar for opening a PR.
</Tip>

## Linting

```bash
make lint-install    # installs golangci-lint (pinned to v1.61.0)
make lint
```

The lint config (`.golangci.yml`) narrows static analysis to bugs and correctness rather than style churn.

## Test discipline

- **Don't weaken existing tests.** Removing or skipping a test requires an explicit reason in the PR description.
- **Add tests for new behavior** — at minimum a happy path plus one error path.
- **Cortex mutation paths** need a `Rebuild`-after-mutation test (see `cortex/rebuild_test.go`).
- **MCL lexer/parser/validator** changes need token + parser tests, and every new validator rule needs a green-path and red-path test.
- **Skill corpus:** `./bin/mcl-validate skills/<slug>/SKILL.mtx`; the `mtx-corpus` CI job validates every `SKILL.mtx` on each PR.

<Card title="Contributing" icon="code-pull-request" href="/developer/contributing">
  Branching, commit conventions, and the PR process.
</Card>