Contributing

This page is a short version of the repository’s CONTRIBUTING.md. That file is the one that counts.

Where behaviour is defined

These pages are the contract. HTTP API has the routes, the error bodies and the rejection order. Storage has the tables. CRDs has the class format. The concepts pages explain what each rule is for. CONTRIBUTING.md in the repository holds the requirements, the acceptance criteria and the decisions already made.

Read the parts you need before you write code. Do not add behaviour they do not describe.

A pull request that changes behaviour changes the page that describes it, in the same pull request. A page that describes last month’s code is worse than none, because a reader trusts it.

Enforcement lives in internal/gateway/ops.go and nowhere else. When a page and the code disagree, that file is what runs.

To propose a design change, open an issue that explains the change and the reasons, and wait for a maintainer. The pull request comes after and links the issue.

Rules

• The non-goals are fixed. No vector search, LLM extraction, UI, multi-cluster, hosted service, orchestration, task decomposition, message passing, conflict resolution, world-truth checks, CRDTs, custom storage engine, or multi-field atomic writes. If your change needs one, start a discussion first.
• kslate knows nothing about LLMs. Nothing in kslate mentions a model, a prompt, a tool call or a message. If an API needs to know what an LLM is, it belongs in the caller.
• Tests use real Postgres. They run against Postgres in Docker. There is no in-memory store.
• One Go binary. The gateway, worker, CLI and controller are one binary. The Python client is separate and shares no server code.
• Error bodies are exact. STALE, STALE_PREMISE and HELD match the HTTP API page field for field. No retry hints. kslate never waits, merges, or retries for the caller.
• The check order is fixed. If a request fails more than one check, kslate returns the first failure in the defined order.

Where the code is

The policy checks live in internal/gateway/ops.go, and the compare-and-swaps they depend on run in internal/store. The HTTP, gRPC and MCP adapters parse requests and format responses, and reject input their own transport cannot represent. If you change what is allowed, rejected or returned, change ops.go. The change then applies on all three transports.

There are two Go modules. The root module, and client/go, which uses only the standard library. The client’s tests live in internal/clienttest because they need the real gateway. Tag client releases as client/go/vX.Y.Z.

Before you open a pull request

Every change in behaviour starts with a failing test. Then run:

make test          # Go + a throwaway Postgres in Docker; the bar every PR clears
make vet           # go vet; CI checks gofmt separately
make test-python   # the Python client, if touched
make test-k8s      # kind end to end, if the chart, controller or k8s identity changed
make proto         # regenerate api/kslatev1 if the .proto changed; CI checks it matches
make docs          # this site: zero warnings, guard passes

Where decisions go

Two places, and the split matters.

An open question is an issue. CONTRIBUTING.md lists the decisions already made and the questions still open. When your code has to answer an open one, open an issue labelled decision-needed with the question, the options, and your recommendation, and wait for a maintainer. Do not settle it quietly in code. Do the same if you find two pages that disagree: say so instead of picking one.

The answer is a pull request that changes the page and the code together, linking that issue. The issue keeps the argument. The page records what was decided, and CONTRIBUTING.md records the alternative that was rejected.

What the pages do not reach, the code comments carry. Where a choice is not obvious, the comment at the site says why, and it is the only record of it. Do not strip one, and write one when you make such a choice.

Demos and comparisons

The comparison against other frameworks, the incident demo and the kagent demo live in a companion repository. This repository ships only the product. If you change a guarantee here, re-run the matching entry there.

This site

The pages are Markdown under docs-site/content/. make docs-serve previews the site. make docs builds it and runs the guard. The guard fails on banned words and on a literal placeholder. In production mode it also fails on any number that has not been measured.

Diagrams use Mermaid. Mark an unmeasured number with {{< tbd >}}. A feature that is designed but not built gets a warning callout saying so. See docs-site/README.md and docs-site/STYLE.md for more.

Security

Report vulnerabilities through a private GitHub security advisory on the repository. Do not open a public issue. You will hear back within three working days.

Licence

Apache-2.0. Your contributions are licensed the same way.