@klok-integration/cli 0.4.0 → 0.6.203

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

@@ -0,0 +1,88 @@
+---
+name: klok-solution
+description: Design, build or maintain a Klok integration solution and keep its solution document true to what is built. Use whenever a task asks to design or develop a service, integration, API or route, to change, fix or extend an existing one, or to explain how a flow is built — before the first route of a new solution and on every change of a leg.
+---
+
+# Designing and maintaining a solution
+
+New development and maintenance follow one process. A **solution** is the business level unit that a set of
+integration legs belongs to; its **solution document** (`README.md` in the tenant's `integration-solutions`
+registry) says what the legs are, how they interact and why. The document is written before the code of a new
+solution and is brought to the new steady state by every change of a leg, so that the registry describes the
+integration landscape as it is built and deployed, not as it was once planned.
+
+Read first: the registry's own `README.md` on `main` (the section list of a solution document, the classification
+of services, the descriptor contract), `klok docs read klok-integration-strategy-and-tactics` (*From solution
+documents to design documents*, *Event driven with sync compatible interfaces*) and
+`klok docs read klok-framework-klok-quarkus-extension`. Reference examples:
+`solutions/KLK010_personnel_scheduling_services/` (two systems) and `solutions/KLK008_ai_image_generation/` (a
+shared platform service) in `klok/integration-solutions`.
+
+## Steps
+
+1. **Find the solution.** The route id prefix is the solution id (`KLK010I1_…` belongs to `KLK010`); a project
+   names its solution in `klok-system-project.json` (`solutionId`). The document is
+   `<tenant>/integration-solutions/solutions/<SOLUTIONID>_<slug>/README.md` on `main` (fetch first). The tenant's
+   `<tenant>-context` skill lists solutions, routes and topics (`data/solutions.jsonl`, `data/routes.jsonl`).
+2. **Check that the document is still true** before relying on it: `klok solutions check --root <registry>`
+   compares every solution document with the route classes on the default branch of every repository of the tenant
+   in the workspace (`klok sync` first). Findings are drift to fix in this task or to file as an
+   issue, never to ignore.
+3. **Read the design.** The solution document and any design page next to it, then each project's `klok-docs/`
+   (`klok docs read <doc-id>`, `klok docs id <repo path>` gives the id).
+4. **A new solution gets an id and a document before code.** Take the id from the code, not the next free
+   number: grep the integration repositories, pushed branches included, and run `klok solutions validate`. Write
+   `README.md`, `solution.meta.json` (`generatedBy: "manual"`) and, when the details do not fit, a design page next
+   to it, in a worktree of the registry. The sections are listed in the registry README.
+5. **Reuse before building.** Look for an existing solution or platform capability first: tasks and the task API
+   (KLK002), the ODL, the AI services (KLK003), mail (KLK006), the claim check, datamodels in the catalog. A
+   capability that needs a change to serve the solution is *reused, slight change*, with its own merge request in
+   the owning project.
+6. **Classify every service** the solution needs: *new project*, *new routes in an existing project*, *reused,
+   slight change*, *reused as is*, *client change*. Name the repository of each.
+7. **Map the legs.** For every route: id (`<TENANTSHORT><NNN><LEG><seq>_<Description>`, leg and sequence not used
+   before — `klok solutions check` reports duplicates), project, pattern base class, topics with their purpose,
+   datamodels and their class, task types, configuration keys, and how the legs interact (diagrams in the flows
+   section). Route configuration and details stay in the project's `klok-docs/`; the solution links there.
+8. **Choose the technology deliberately.**
+   * Integration logic is **Java Klok routes** on the Klok Quarkus extension. They are documented by the platform
+     with their topics, datamodels and configuration, and related integrations group in one project and reuse its
+     services.
+   * Integration logic written with the Python or TypeScript broker clients, or kept inside an application, is a
+     **`[TACTICAL]`** choice: write the motivation, its cost and the condition for removing it in the solution's
+     tactical section.
+   * An external engine (a GPU model server, a vendor service) stays **simple and dumb**: it does one request at a
+     time over REST. Priority, queues, retries, claim checks and task state live in a Java egress. The engine may be
+     written in any language; that is not tactical, logic moved into it would be.
+9. **Order the delivery.** Datamodels and framework changes are released and merged into the dependency catalog
+   before their consumers; steps only a person may take (creating projects in klok.dev, Vault, running Ansible,
+   merging) are numbered hold points in the document's delivery order. The answer that hands them over is a
+   step-by-step guide with the commands, the merge order and the release result each step waits for
+   (KLOK-AGENTS.md *Manual steps are handed over as a guide*).
+10. **Build each leg** with the `klok-route`, `klok-datamodel` and `klok-release` skills, every repository in its own
+    worktree with the same task id (`klok-worktree` skill).
+11. **Keep the document true.** Every merge request that adds, changes or removes a leg updates the solution
+    document in the same change set: the legs table, the flows and the status. A leg that is not on `main` yet
+    carries `planned` in the Status column of its table row; `klok solutions check` relies on it. After the merges,
+    run `klok solutions check` again.
+
+## Maintenance is the same process
+
+* A fix or a change in one route starts at step 1: find its solution and read it before touching the code.
+* A change that alters a leg's contract (a topic, a purpose, a datamodel, an API, a task type, a configuration key
+  another project reads) updates the solution document as well as the project's `klok-docs/`.
+* When the document and the code disagree, the code on `main` is what is built: correct the document. When the code
+  differs from what was agreed, file an issue in the owning project and name it in the document's open questions.
+* The deployed landscape counts too: a leg that is on `main` but not deployed, or deployed from somewhere the
+  document does not name, is written down. Deployment manifests are in `klok/environment/ipaas-se-deploy-manifests`,
+  hosts and stateful services in the Ansible inventories of `klok/environment/klok-environment-setup`.
+
+## Things that are always wrong
+
+* Code for a new solution before its document exists, or a route id whose prefix is not a registered solution.
+* A leg in code that its solution document does not name, or a document that names a leg as built that is not.
+* Reusing a leg and sequence (`KLK002A11`) for a second route.
+* Integration logic in a Python or TypeScript client, or in an external engine, without a `[TACTICAL]` entry.
+* A solution document that describes an unbuilt part in the present tense without saying it is planned.
+* Copying a leg's route configuration or route table details into the solution document instead of linking the
+  project's `klok-docs/`.

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
 
@@ -100,12 +100,17 @@ cleanup task, never moved or deleted on the way.
 ## Finish
 
 1. Validate the requested behaviour, inspect the final diff, and commit to the task branch: stage specific paths,
-   check for secrets and unrelated files. Respect an explicit request to leave changes uncommitted.
-2. Push and open a merge request ready for review when the task or the established workflow allows it (see the
+   check for secrets and unrelated files, and write the message as a Conventional Commit (`fix(odl): …`; see
+   *Commits follow Conventional Commits* in `KLOK-AGENTS.md`). Respect an explicit request to leave changes
+   uncommitted.
+2. Push and open a merge request ready for review, with a Conventional Commits title that types the whole change
+   (`docs` only when nothing but documentation changed), when the task or the established workflow allows it (see the
    `klok-release` skill for what to check afterwards). Do not invent approval requirements and do not assume a
    permission that was not given.
 3. Report: canonical repository path, worktree path, branch, commits, tests run, push and merge request status,
    remaining changes and the next action. Unfinished work gets a clear handoff and keeps its worktree.
+4. End with the step-by-step guide of everything left for a human, merging the merge requests included
+   (KLOK-AGENTS.md *Manual steps are handed over as a guide*).
 
 ## Cleanup