kronk-service-architecture
Skill868 starsChanged 14 days agoApache-2.0View on GitHub
Kronk Go architecture rules. Ownership along the request flow (foundation/web and mid → app/domain/*app → sdk/pool → typed pools → sdk/{kronk,bucky,malina} handles → model engines → yzma/llama.cpp) and import direction, with encoding/json v1 for wire types, SDK sentinel errors mapped in errs.FromSDK, type-set enums (Parse/MustParse, *_types.go), cross-cutting concerns in mid/observ, the lifecycle invariants (admission permits, cancellation, slot/sequence isolation, IMC, MTP, pool reservations), and shallow-branching style (default-first assignment, naked switch). Use when writing, editing, or auditing Go under cmd/kronk, cmd/server, sdk, or examples, when adding an endpoint, SDK option, error, enum, metric, span, parser, or pool/engine behavior.
In this repository5 other files it gives its agents.
- .agents/default/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- kronk-pr-reviewSkill
- probing-kronkSkill
- use-modern-goSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Use use-modern-go for syntax in all of them.
- Distinctive: line 55
When authoring interactively, the user controls the types: Before committing new request/response fields, SDK options, or config fields, …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Kronk Service Architecture
The diagram is the request flow, not import direction (see the import rule below). Every arrow is an ownership boundary (Chapter 20 §20.5.1); the owner of a concern is the only place it is implemented.
cmd/kronk (CLI) ─┐ examples/ (separate module, public SDK only)
▼ │
cmd/server/foundation/{web,logger} transport, request lifecycle, logging primitives
cmd/server/app/sdk/{mid,errs,mux,…} middleware, error translation (errs.FromSDK), auth, mux
cmd/server/app/domain/<x>app routes, access, model lookup, error mapping; typed endpoints
│ also own request/response structs (inference: SDK *HTTP writes)
▼
sdk/pool ──► sdk/{kronk,bucky,malina}/pool ──► sdk/pool/engine (+ resman reservations)
▼
sdk/kronk · sdk/bucky · sdk/malina one-model public handles: admission, active use, unload
▼
sdk/kronk/model (batch engine, IMC, MTP) · sdk/bucky/model · sdk/malina/model native state
▼
yzma / llama.cpp · whisper.cpp · stable-diffusion.cpp
sdk/tools/* catalogs, downloads, libs, devices: shared by CLI and toolappWhich reference to read (MUST)
<skill> = this file's dir. Read the matching reference before writing or auditing the code it covers. This file holds only the invariants.
| Task | Read |
HTTP edge (SDK *HTTP pass-through vs typed endpoints), enums (*_types.go), options, SDK errors and their HTTP mapping | <skill>/references/types.md |
| Handles, pools, engines, streams, IMC, prompt plans, parsers, Responses normalization, speculative/MTP, tracing, Bucky | <skill>/references/lifecycle.md |
Conditional logic in any Go code: 1-3 branches, nested if/else, type assertions on any | <skill>/references/branching.md |
Use use-modern-go for syntax in all of them. Source-of-truth order is Chapter 20 §20.1.1's: scoped AGENTS.md, then current code and tests, then Makefiles and workflows, then Chapter 20. This skill ranks below all of them; when it disagrees with one, follow that source and say so.
Invariants (MUST, always)
Apply these to new and changed code. Existing code that predates a rule is not a finding by itself; follow the neighboring code when a rule and the codebase disagree, and say so.
- Import direction.
sdk/*never importscmd/*.cmd/server/foundation/*imports neithercmd/server/app/*norsdk/*. A<x>apppackage never imports another<y>app. Allowed exceptions: the generatedauthappgRPC/protobuf contract (imported bytoolapp,app/sdk/authclient,app/sdk/apitest), andcmd/kronkimportingtoolapprequest/response types for web mode.examples/imports only public SDK packages, nevercmd/*orinternal/. - Change the owner, don't duplicate policy. Inference, caching, scheduling, eviction, and resource policy live in
sdk/*; transport concerns live infoundation/webandmid. A handler never touches native model state, pool eviction, or KV; the CLI never re-implements asdk/toolsmanager. - Who owns the HTTP shape. OpenAI-compatible inference endpoints (
chatapp,respapp,embedapp,rerankapp,tokenapp,decisionapp) hand theResponseWriterto an SDK*HTTPmethod (ChatStreamingHTTP,ResponseStreamingHTTP,EmbeddingsHTTP,RerankHTTP,TokenizeHTTP,DecisionHTTP) that writes headers, SSE, and themodel.*Responsebody; their wire shape is owned insdk/kronk. The domain owns routing, access middleware, model lookup, and error mapping. Other endpoints (msgsapp,toolapp,imageapp,audioapp, …) own their request/response structs in the domain. Seereferences/types.md. - Wire types stay on
encoding/jsonv1. Request decoding and response encoding for HTTP, SSE, and exported SDK types useencoding/json, neverencoding/json/v2orjsontext, whateveruse-modern-gosuggests. v2 changes Kronk's OpenAI-compatible output and can abort streams (references/types.md). Switching needs explicit approval and wire-level tests. - Error identity survives to the edge. The SDK returns wrapped sentinels (
%w); handlers returnerrs.FromSDK(err), orerrs.New/errs.Errorfwith an explicit code for protocol errors. A new client-reachable SDK sentinel needs a case inerrs.FromSDK(otherwise it surfaces asInternal). - Cross-cutting concerns are not inlined into handlers. HTTP-wide: a
midweb.MidFunc(global inmux.WebAPI, or per route). SDK: spans throughsdk/kronk/observ/otel(otel.AddSpan) and metrics on the private registry insdk/kronk/observ/metrics(promauto.With(reg), never the default registerer). - New exported enums are type sets (
references/types.md): struct-wrapped value, registry,Parse<T>/MustParse<T>,String/Equal/IsZero/MarshalText/UnmarshalText, in<topic>_types.go, covered by the package'sregistered_types_test.gowhere one exists. - Lifecycles are owned (
references/lifecycle.md): whoever creates a goroutine, stream, native object, permit, or reservation releases it on every return path, including cancellation and error. - Generated outputs are never hand-edited:
DocsManual.tsx,DocsSDK{Kronk,Model,Pool,Bucky,BuckyModel,Malina,MalinaModel,Examples}.tsx,cli-reference.json, the generated section ofLayout.tsx,cmd/server/api/services/kronk/static/**,*.pb.go,zarf/nix/gomod2nix.toml. Change the source (.manual/, Go doc comments,examples/, CobraLong/Example, BUI source) and regenerate (make kronk-docs,npm run build). - Native versions move together. Yzma in
go.mod, the pinned llama.cpp insdk/tools/libs, the root andexamplesmodules, and Nix data are one tested set (§20.4.1). - Tests follow
AGENTS.md, whateveruse-modern-gosuggests: setGITHUB_WORKSPACE, test only the changed packages by path, never./...and never anything undersdk/kronk/tests. - When authoring interactively, the user controls the types. Before committing new request/response fields, SDK options, or config fields, state the concrete types and get confirmation. Reviewers don't block on this; they report type problems as findings.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

