@klok-integration/cli 0.3.4 → 0.5.0

package/assets/agents/skills/klok-route/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: klok-route
-description: Write or change a Camel route on the Klok Quarkus extension 2.0 (onramp, processing, offramp, REST API handler, async task worker, custom route) with the correct naming, configuration, error handling, tests and klok-docs. Use for any change inside a Klok integration project.
+description: Write or change a Camel route on the Klok Quarkus extension 2.0 (onramp, processing, offramp, REST API handler, async task worker, custom route) with the correct naming, topics and topic purpose, configuration, error handling, tests and klok-docs. Use for any change inside a Klok integration project.
 ---
 
 # Writing a Klok route
 
-Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt first (pages `patterns`, `naming`,
+Read `klok docs read klok-framework-klok-quarkus-extension` first (pages `patterns`, `naming`,
 `config`, `error-handling`, `testing`); read the `klok-docs` skill for other pages.
 
 ## Steps
@@ -17,23 +17,77 @@ Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt first (
 2. **Name it.** `<TENANTSHORT><NNN><LEG><seq>_<Description>`, one class per route, the solution number from the
    portal registry. Sub routes are `S`, timers `T`.
 3. **Bind the datamodels** as type parameters; take them from the catalog bundle, never hand written DTOs.
-4. **Configure** through `routeConfig("key", default)` / `requiredRouteConfig("key")` and document every key in
+4. **Choose the topic purpose** of every topic the route publishes or consumes (next section).
+5. **Configure** through `routeConfig("key", default)` / `requiredRouteConfig("key")` and document every key in
    `application.properties` as `<RouteId>.<key>`. Reserved keys: `enabled`, `logevents.*`, `retry.*`, `dlq.*`,
    `topic.*`, `subscription.*`, `claimcheck.*`.
-5. **Errors.** Throw `Klok4XXException` for caller errors, let retryable failures propagate; the base route logs,
+6. **Errors.** Throw `Klok4XXException` for caller errors, let retryable failures propagate; the base route logs,
    retries with backoff, republishes to `<topic>_DLQ` and emits the failure CloudEvent. Override `failureHandled()`
    only when the route owns its failures (custom routes that answer HTTP themselves).
-6. **Capabilities** as interfaces: `SplitIncomingMessage`, `AggregateOutgoingMessages`, `ClaimCheck`,
+7. **Capabilities** as interfaces: `SplitIncomingMessage`, `AggregateOutgoingMessages`, `ClaimCheck`,
    `KlokEmitCloudEventOnSuccess/Failure`, `PersistOutgoingMessages`, `KlokAsyncTaskInitiator`.
-7. **Test** with `@QuarkusTest` and the recording broker client factory: assert the route status is `Started`,
-   send a message, assert the published topic, body and `klok-*` properties.
-8. **Document** in `klok-docs/`: the route in `routes.md`, decisions in `design-decisions.md`, operations notes.
-9. Build (`./gradlew build`) in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch,
-   open a merge request ready for review, check the pipeline.
+8. **Test** with `@QuarkusTest` and the recording broker client factory: assert the route status is `Started`,
+   send a message, assert the published topic (the full name, purpose included), body and `klok-*` properties.
+9. **Document** in `klok-docs/`: the route in `routes.md` with the purpose of each topic and the project on its other
+   end, decisions in `design-decisions.md`, operations notes.
+   Annotate central classes with `@KlokDocs` (`dev.klok.framework.common.docs.KlokDocs`, klok-common): configuration
+   or standards several routes read, shared mappers, domain logic used by several routes. Each gets its own generated
+   page; write its Javadoc for a reader who has not seen the code. Not every class: the classes a route calls
+   directly reach its generated documentation without the annotation.
+10. Build (`./gradlew build`) in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch,
+    open a merge request ready for review, check the pipeline.
+
+## Topic purpose
+
+A topic is named after its datamodel: `<Model>[_<purpose>]`. The purpose (called *producer intention* in older code)
+is a suffix that the producer and the consumer agree on and each set on their own route, so one datamodel serves
+several flows: `CallAiResponseV1_documentation` and `CallAiResponseV1_invoicecoding` both carry the typed
+`CallAiResponseV1`, and each consumer receives only its own flow. The framework builds the full topic name on both
+sides from the model and the purpose.
+
+* **When.** Give a flow a purpose when its datamodel is, or may be, used by another flow. Without one, every consumer
+  of the model receives every message. No purpose only when every consumer wants every message.
+* **Ingress** (onramps, webhook onramp): decide which flow the data belongs to and publish with that purpose.
+  **Egress** (offramps): consume the purpose the producer publishes on; find it in the producer's `klok-docs/` or its
+  route configuration, and ask when it is not written down. Never guess a purpose.
+* **Where it is set.** Configuration wins over code.
+
+  | Pattern | Code | Configuration |
+  |---|---|---|
+  | onramps, `KlokWebhookOnrampRoute`, offramps, channel adapters, `Sync` variants | `topicPurpose()` | `<RouteId>.topic.purpose` |
+  | `KlokOfframpRouteWithResult` | `topicPurpose()`, `resultTopicPurpose()` (default: the request's) | `.topic.purpose`, `.topic.result-purpose` |
+  | `KlokProcessingRoute` | `incomingTopicPurpose()`, `outgoingTopicPurpose()` | `.topic.purpose`, `.topic.outgoing-purpose` |
+  | `KlokAsyncTaskWorkerRoute` | `taskType()`: the task type is the request topic's purpose | |
+  | REST handler with `task.initiate` | the `klok-task-type` header in `transformBody` | `.task.type` |
+
+  Put it in code when the purpose is part of what the route is; put it in configuration when the same route serves
+  several flows. Set `<SolutionId>.topic.purpose` only when every route of the solution is on that flow.
+* **Name** the flow as both sides understand it (`created`, `reminder`, `documentation`): letters, digits, `-` and
+  `.`, never `_`, and no version, tenant or environment. Task types are `<domain>.<verb>-<object>`. A topic read by
+  another tenant appends the reader after the purpose: `<Model>_<purpose>_<reader>`.
+* **A mismatch fails silently**: the two routes end up on different topics and nothing arrives. Check the start log
+  (`Route <RouteId> subscribes to <topic>`, `Route <RouteId> publishes <Model> to <topic>`) and assert the full topic
+  in the test.
+* **Changing a purpose** moves the flow to a new topic: move the consumers first, then the producers, and let the old
+  topic drain.
+* **Limit.** A route has one purpose, fixed when it starts. A shared service that answers each caller on the purpose
+  the caller chose is not supported yet (klok/framework/klok-quarkus-extension#32); do not write a subclass per
+  caller in the shared service, say so in the merge request instead.
+
+The user guide page *Topic Purpose: One Datamodel, Several Flows* (`klok docs read klok-user-guide`)
+explains the reasons and the naming in full.
 
 ## Things that are always wrong
 
 * A route id that does not start with the solution id, or two routes with the same id.
 * Publishing to a hand written topic string; use the resolver and the datamodel.
+* Consuming a shared topic and discarding the messages of other flows (a filter on a payload field, an ODL lookup
+  per message) where the producer could publish the flow with a topic purpose.
+* A purpose with `_`, a version, a tenant or an environment in it, or a purpose guessed instead of agreed with the
+  other side.
+* Choosing a tenant, index, repository or account from a field in the message; the topic decides the tenant.
+* Sharing broker credentials between services, or granting a whole namespace of another domain or tenant.
+* Publishing into another tenant's namespace, with `<RouteId>.topic.tenant-override` or otherwise; a route consumes
+  another tenant's topic with the override and a `consume` grant, and publishes only in its own tenant.
 * Catching exceptions to return HTTP 200 with an error text.
 * Pinning a framework or datamodel version in `gradle/klok-libs.versions.toml` by hand.

package/assets/agents/skills/klok-worktree/SKILL.md

@@ -8,7 +8,7 @@ description: Create, use, hand over and clean up the per task Git worktree and b
 The rule is in `KLOK-AGENTS.md` (*One task, one worktree, one branch*): every task that changes repository files runs
 in its own Git worktree on its own branch, and the canonical checkout is left exactly as found. This skill is the
 procedure. The principle behind it, *Git is the truth*, is described in
-https://docs.klok.dev/klok-integration-strategy-and-tactics/llm.txt.
+`klok docs read klok-integration-strategy-and-tactics`.
 
 ## Directory contract