Skip to main content

Kukum

kukum = to cook in Bislama

Kukum is the framework's own scaffolding API. It exposes the file recipes that live in the skills as callable endpoints — kukum.handler.add, kukum.schema.add, kukum.realm.add — and adds introspection endpoints that report what the framework currently has wired up.

It has three entry points over one implementation: a kukum CLI, a JSON-RPC/MCP surface on a running suite, and an in-process module for tests and tooling.

The key behaviours:

  • Everything is derived from one catalogue. Fourteen primitive descriptors, each naming the skill that owns its prose, times five standard predicates (find, get, add, edit, check). Adding a primitive adds five routes and no new plumbing.
  • add is plan-first and non-destructive by default. It composes with machine-generated shared files so a second entity does not drop the first, and refuses hand-written files unless forced.
  • It validates before it writes. The name checks live in each descriptor and run on add and check (not on get or find, which write nothing): the subject on every primitive that takes one, the object on the four where it matters (handler, model, test, component), and the predicate on handler, where the standard predicates are the point. handler is also the primitive that restricts its target to the layers it declares — the restriction is per descriptor, not a property every primitive has.
  • Generated files are self-describing. They carry an ownership marker and may carry @kukum-instructions for the next agent, readable back through source get.
  • The CLI is not a reimplementation. It loads the realm through the cli intent and dispatches through the same handler map the RPC surface serves.

See the pattern guide for the endpoint reference and the maintenance recipes, and the rationale for why the API is shaped this way.