@kb-labs/devkit 1.4.0 → 2.9.0

package/assets/claude/CLAUDE.md.snippet

@@ -0,0 +1,30 @@
+## KB Labs Platform
+
+This project uses the [KB Labs](https://github.com/KirillBaranov/kb-labs) platform.
+A set of Claude Code skills is installed under `.claude/skills/kb-labs-*` to help
+you work with the platform efficiently.
+
+### Common tasks (just ask)
+
+- **Create a plugin** — "create a kb-labs plugin called my-plugin"
+- **Create a service** — "create a kb-labs service called my-service"
+- **Troubleshoot** — "kb-labs is not starting" / "kb-dev shows failed"
+- **Explore the project** — "what kb-labs services and plugins are installed here?"
+- **Update the platform** — "update kb-labs to the latest version"
+
+### Manual reference
+
+- `pnpm kb --help` — list all platform commands
+- `pnpm kb-dev status` — service status
+- `pnpm kb-dev doctor` — environment diagnostics
+- `pnpm kb plugins list` — installed plugins
+- `kb-create update` — update the platform
+- `kb-create doctor` — verify the installation
+
+### Where things live
+
+- `.kb/kb.config.jsonc` — project configuration (safe to edit)
+- `.kb/` — platform runtime state (do not edit by hand)
+- `.claude/skills/kb-labs-*` — managed skills (reinstalled by `kb-create update`)
+
+For full platform documentation see https://github.com/KirillBaranov/kb-labs.

package/assets/claude/manifest.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "devkitVersion": "1.5.0",
+  "platformCompat": ">=0.10.0 <2.0.0",
+  "claudeMd": {
+    "snippetPath": "CLAUDE.md.snippet",
+    "markerId": "kb-labs"
+  },
+  "skills": [
+    {
+      "id": "kb-labs-quickstart",
+      "path": "skills/kb-labs-quickstart/SKILL.md",
+      "version": "1.0.0",
+      "description": "Quickstart for the KB Labs platform: verify install, locate state, find common commands"
+    },
+    {
+      "id": "kb-labs-create-plugin",
+      "path": "skills/kb-labs-create-plugin/SKILL.md",
+      "version": "1.0.0",
+      "description": "Scaffold a new KB Labs plugin (cli/core/contracts packages) following the platform-standard layout"
+    },
+    {
+      "id": "kb-labs-create-product",
+      "path": "skills/kb-labs-create-product/SKILL.md",
+      "version": "1.0.0",
+      "description": "Create a new KB Labs product/service with canonical bootstrap, health, observability, and tests"
+    },
+    {
+      "id": "kb-labs-troubleshoot",
+      "path": "skills/kb-labs-troubleshoot/SKILL.md",
+      "version": "1.0.0",
+      "description": "Diagnose KB Labs platform issues: stuck services, dirty submodules, port conflicts, broken builds"
+    },
+    {
+      "id": "kb-labs-explore",
+      "path": "skills/kb-labs-explore/SKILL.md",
+      "version": "1.0.0",
+      "description": "Discover what is installed in a KB Labs project: services, plugins, configuration, and entry points"
+    },
+    {
+      "id": "kb-labs-update",
+      "path": "skills/kb-labs-update/SKILL.md",
+      "version": "1.0.0",
+      "description": "Safely update the installed KB Labs platform via kb-create update, including diff review"
+    }
+  ]
+}

package/assets/claude/skills/kb-labs-create-plugin/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: kb-labs-create-plugin
+description: Use when the user wants to create a new KB Labs plugin, asks how to scaffold a plugin, extend KB Labs with new commands, or add a marketplace entity. Do not use for creating services (use kb-labs-create-product) or for adding new packages to an existing plugin.
+user-invocable: true
+argument-hint: [plugin-name]
+---
+
+# Create a KB Labs Plugin
+
+Help the user scaffold a new KB Labs plugin following the platform-standard
+three-package layout (`cli` / `core` / `contracts`).
+
+## Step 1: Clarify the plugin intent
+
+Before scaffolding, make sure you know:
+
+- **Plugin name** — kebab-case, without the `kb-labs-` prefix (e.g. `audit`, `deploy`).
+  The scaffolded repo will be named `kb-labs-<name>`.
+- **What it does** — one sentence. This goes into the plugin manifest `description`.
+- **Does it add CLI commands?** — almost always yes.
+- **Does it need LLM access / cache / state?** — informs which platform composables
+  the plugin will use (`useLLM`, `useCache`, `useState`).
+
+If the user did not provide these, ask concise questions before generating files.
+
+## Step 2: Create the plugin from the template
+
+KB Labs ships a plugin template and a launcher command:
+
+```bash
+kb-create plugin --name=$ARGUMENTS
+```
+
+If that command is not yet available in the user's kb-create version, fall back to
+copying `templates/kb-labs-plugin-template` manually and replacing the package names.
+
+## Step 3: Required package layout
+
+A compliant plugin must have three packages:
+
+```
+kb-labs-<name>/
+├── packages/
+│   ├── <name>-contracts/     # types, interfaces, zod schemas — no runtime deps
+│   ├── <name>-core/          # business logic, imports contracts
+│   └── <name>-cli/           # command handlers, plugin manifest, imports core
+├── package.json              # workspace root
+└── pnpm-workspace.yaml
+```
+
+Rules:
+- `contracts` has zero runtime dependencies beyond `zod`.
+- `core` depends on `contracts`.
+- `cli` depends on `core` and registers commands via the plugin manifest.
+- Do not merge these into a single package — the separation is load-bearing
+  for types, tree-shaking, and marketplace distribution.
+
+## Step 4: Plugin manifest
+
+The CLI package must ship `kb.manifest.json` (discovered automatically by the
+platform). Minimal shape:
+
+```json
+{
+  "name": "@kb-labs/<name>",
+  "version": "0.1.0",
+  "kind": "plugin",
+  "commands": [
+    {
+      "id": "<name>:hello",
+      "summary": "Example command",
+      "handler": "./dist/handlers/hello.js"
+    }
+  ]
+}
+```
+
+## Step 5: Use platform composables, not direct imports
+
+Inside command handlers, read platform capabilities via composables from
+`@kb-labs/sdk`:
+
+```ts
+import { useLLM, useCache, useState, useLogger } from '@kb-labs/sdk';
+
+export async function handler(ctx, argv, flags) {
+  const log = useLogger();
+  const cache = useCache();
+  // ...
+}
+```
+
+Do **not** reach into `ctx.platform.*` directly — that path loses prototype
+information and breaks wrapper layers (analytics, queuing, proxying).
+
+## Step 6: Build the plugin
+
+```bash
+pnpm install
+pnpm --filter "@kb-labs/<name>-contracts" build
+pnpm --filter "@kb-labs/<name>-core" build
+pnpm --filter "@kb-labs/<name>-cli" build
+```
+
+Build order matters: contracts → core → cli. If in doubt, use the devkit
+build-order tool when it is available in the user's environment.
+
+## Step 7: Clear the plugin cache and verify
+
+The CLI caches plugin manifests. After building a new plugin, always clear the
+cache — otherwise the new commands will not be discovered.
+
+```bash
+pnpm kb marketplace clear-cache
+pnpm kb <name>:hello --help
+```
+
+If the command is not found, clear the cache deeply and retry:
+
+```bash
+pnpm kb marketplace clear-cache --deep
+```
+
+## Step 8: Register in the workspace (only if needed)
+
+If the user is adding the plugin to an existing multi-repo workspace, add it to
+`pnpm-workspace.yaml` and to the launcher's project config at
+`.kb/kb.config.jsonc`. If the plugin is a standalone repo consumed by a different
+project, this step is handled by `kb-create` on the consuming side.
+
+## Definition of done
+
+- Three packages exist and build cleanly
+- `kb.manifest.json` is valid
+- `pnpm kb <name>:hello --help` works
+- Handlers use composables from `@kb-labs/sdk`
+- No direct imports of platform internals
+
+## Do not
+
+- Do not create single-package plugins
+- Do not edit files under `.kb/` as part of plugin development
+- Do not forget to clear the marketplace cache after building
+- Do not invent a custom command discovery format — use `kb.manifest.json`

package/assets/claude/skills/kb-labs-create-product/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: kb-labs-create-product
+description: Use when the user wants to create a new KB Labs product or service (HTTP API, daemon, background worker) that runs under kb-dev. Do not use for creating plugins (use kb-labs-create-plugin) or for adding routes to an existing service.
+user-invocable: true
+argument-hint: [service-name]
+---
+
+# Create a KB Labs Product / Service
+
+Help the user create a new platform service that follows the canonical bootstrap,
+health/readiness, observability, and logging conventions.
+
+## Step 1: Clarify the service intent
+
+Before scaffolding, confirm:
+
+- **Service name** — kebab-case (e.g. `audit`, `notifier`).
+- **Kind** — HTTP API (Fastify), background daemon, or worker.
+- **Port** — must not collide with existing services in `.kb/devservices.yaml`.
+- **Dependencies** — does it need Redis, qdrant, state-daemon, gateway?
+
+## Step 2: Pick the closest reference service
+
+Do not invent a layout. Copy the structure of the closest reference:
+
+- HTTP API → look at how `marketplace-api` or `workflow-daemon` is organised
+- bootstrap-style platform service → look at `rest-api`
+- router/proxy style → look at `gateway`
+- small daemon with HTTP surface → look at `core-state-daemon`
+
+These services live under the `platform/` and `infra/` directories of a kb-labs
+workspace. If the user is in a downstream consumer project (not the platform
+monorepo), copy from `templates/kb-labs-product-template` instead.
+
+## Step 3: Required outcomes
+
+A compliant service must expose:
+
+- `/health` — cheap health snapshot
+- `/ready` — readiness for orchestration
+- `/observability/describe` — versioned identity and capabilities
+- `/observability/health` — structured runtime diagnostics
+- `/metrics` — canonical Prometheus output
+
+It must use:
+
+- `@kb-labs/core-platform` types (`ILogger`, `ICache`, etc.) — never local copies
+- `@kb-labs/shared-http` for `registerOpenAPI()` and HTTP helpers
+- `HttpObservabilityCollector` from shared-http for metrics and operations
+- structured log correlation fields (`serviceId`, `instanceId`, `requestId`,
+  `traceId`, `operation`, normalized `route`)
+
+## Step 4: Wire bootstrap
+
+```ts
+import Fastify from 'fastify';
+import { registerOpenAPI } from '@kb-labs/shared-http';
+import { initPlatform } from '@kb-labs/core-runtime';
+
+const platform = await initPlatform();
+const server = Fastify({ logger: platform.logger });
+
+await registerOpenAPI(server, {
+  title: 'My Service',
+  version: '0.1.0',
+  servers: [{ url: 'http://localhost:5099', description: 'Local dev' }],
+  ui: process.env.NODE_ENV !== 'production',
+});
+
+// ...register routes...
+
+await server.listen({ port: 5099, host: '0.0.0.0' });
+```
+
+Routes that should appear in OpenAPI need a `tags:` entry on their schema.
+Routes without `tags:` are hidden — this is the visibility model.
+
+## Step 5: Register the service with kb-dev
+
+Add an entry to `.kb/devservices.yaml` so the service can be started/stopped/
+restarted via the unified manager:
+
+```json
+{
+  "services": {
+    "my-service": {
+      "group": "backend",
+      "port": 5099,
+      "command": "node ./apps/my-service/dist/index.js",
+      "healthUrl": "http://localhost:5099/health",
+      "dependsOn": ["state-daemon"]
+    }
+  }
+}
+```
+
+Then:
+
+```bash
+pnpm kb-dev start my-service
+pnpm kb-dev status
+```
+
+## Step 6: Tests
+
+At minimum, add tests that verify:
+
+- `/health` returns OK
+- `/ready` returns ready
+- `/observability/describe` validates against the canonical contract
+- `/observability/health` validates against the canonical contract
+- `/metrics` includes the canonical metric families
+
+Use validators from `@kb-labs/core-contracts` if available:
+
+- `validateServiceObservabilityDescribe(...)`
+- `validateServiceObservabilityHealth(...)`
+- `checkCanonicalObservabilityMetrics(...)`
+
+## Step 7: Compliance check
+
+```bash
+pnpm --filter <service-package> build
+pnpm --filter <service-package> test
+pnpm kb-dev restart my-service
+pnpm kb-dev ready my-service --timeout 60s
+pnpm kb-dev health
+```
+
+## Definition of done
+
+- Service starts and stops cleanly via `kb-dev`
+- Canonical endpoints respond with valid payloads
+- Metrics include the canonical families
+- Logs carry correlation fields
+- Tests pass
+- No legacy observability surface left behind
+
+## Do not
+
+- Do not invent a per-service observability format
+- Do not duplicate platform types — always import from `@kb-labs/core-*`
+- Do not run the service via raw `node` or `pnpm *:dev` — always go through `kb-dev`
+- Do not commit secrets or hard-coded ports outside `.kb/devservices.yaml`

package/assets/claude/skills/kb-labs-explore/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: kb-labs-explore
+description: Use when the user wants to know what is installed in their KB Labs project — which services, plugins, commands are available, what is configured, where things live. Do not use for general code search (use Grep) or for finding file paths the user already knows.
+user-invocable: true
+---
+
+# Explore a KB Labs Installation
+
+Help the user discover what is installed and configured in their KB Labs project.
+
+## Step 1: Show install status
+
+```bash
+kb-create status
+```
+
+This prints the platform version, the bound project directory, and the selected
+services and plugins.
+
+## Step 2: Show project configuration
+
+The user-editable project config lives at `.kb/kb.config.jsonc`. Read it and
+summarise:
+
+- Which services are enabled
+- Which plugins are enabled
+- Any custom adapter or LLM settings
+
+Do not parse `.kb/kb.config.json` (the platform-internal one) — that is
+auto-generated runtime state and may change format.
+
+## Step 3: Discover available commands
+
+```bash
+pnpm kb --help
+```
+
+This lists all command groups (e.g. `mind`, `qa`, `marketplace`, `workflow`,
+`commit`, `agent`). For details on a group:
+
+```bash
+pnpm kb <group> --help
+```
+
+For a single command:
+
+```bash
+pnpm kb <group>:<command> --help
+```
+
+## Step 4: Discover services
+
+```bash
+pnpm kb-dev status
+```
+
+Service states: `alive` / `starting` / `failed` / `stopping` / `dead`.
+
+For machine-readable output (when piping into other tools):
+
+```bash
+pnpm kb-dev status --json
+```
+
+To see the service registry (definitions, ports, dependencies), look at
+`.kb/devservices.yaml`. Do not edit this file unless the user explicitly asks —
+it is the source of truth for the dev environment.
+
+## Step 5: Discover installed plugins
+
+```bash
+pnpm kb plugins list
+```
+
+To see which entities the marketplace knows about (plugins, adapters, etc.):
+
+```bash
+pnpm kb marketplace list
+```
+
+The marketplace lock file at `.kb/marketplace.lock` records explicitly installed
+entities (it is never auto-populated).
+
+## Step 6: Discover routes (HTTP services only)
+
+If a REST/Workflow/Gateway service is running:
+
+```bash
+curl http://localhost:5050/api/v1/routes      # rest-api
+curl http://localhost:7778/openapi.json       # workflow-daemon
+curl http://localhost:4000/openapi-merged.json # gateway aggregated
+```
+
+Or open `/docs` on each port for a Swagger UI.
+
+## Step 7: Where things live
+
+A standard KB Labs project has:
+
+| Path | Purpose |
+|---|---|
+| `.kb/kb.config.jsonc` | User-editable project config |
+| `.kb/devservices.yaml` | Service definitions for kb-dev |
+| `.kb/logs/tmp/<service>.log` | Service logs |
+| `.kb/tmp/<service>.pid` | Service PIDs (managed by kb-dev) |
+| `.kb/marketplace.lock` | Installed marketplace entities |
+| `.claude/skills/kb-labs-*` | Managed Claude Code skills |
+
+Do not list or read files under `node_modules/@kb-labs/` unless the user
+specifically asks — they are implementation details of the installed platform.
+
+## Important rules
+
+- The user-facing config is `.kb/kb.config.jsonc` (with comments). The other
+  file `.kb/kb.config.json` is internal — read it only if you have a reason.
+- Services should always be inspected via `kb-dev`, not via raw `ps` / `lsof`.
+- For semantic code search of the user's own code, use Grep — Mind RAG is a
+  platform-internal tool that is only available inside the kb-labs monorepo
+  itself.

package/assets/claude/skills/kb-labs-quickstart/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: kb-labs-quickstart
+description: Use when the user has just installed KB Labs and wants to verify the install, see what is available, or asks "what is kb-labs" / "how do I get started" / "is kb-labs working".
+user-invocable: true
+---
+
+# KB Labs Quickstart
+
+Help the user verify their KB Labs installation and discover what is available.
+
+## Step 1: Verify the install
+
+Run the doctor command — it checks node, pnpm, the platform directory, and the
+installed manifest.
+
+```bash
+kb-create doctor
+```
+
+If this fails, switch to the `kb-labs-troubleshoot` skill.
+
+## Step 2: Show platform status
+
+```bash
+kb-create status
+```
+
+This prints the installed platform version, the bound project directory, and the
+selected services/plugins.
+
+## Step 3: Show what platform commands are available
+
+```bash
+pnpm kb --help
+```
+
+The output groups commands by product (mind, qa, marketplace, workflow, etc).
+For details on a group:
+
+```bash
+pnpm kb <group> --help
+```
+
+## Step 4: Check services (only if the user has services installed)
+
+KB Labs ships an internal service manager called `kb-dev`. Check whether anything
+is running:
+
+```bash
+pnpm kb-dev status
+```
+
+States: `alive` / `starting` / `failed` / `stopping` / `dead`. If the user has
+no services installed yet, this is empty and that is fine.
+
+## Step 5: Point the user at the right next skill
+
+Based on what the user wants to do:
+
+- Wants to build a plugin → suggest `kb-labs-create-plugin`
+- Wants to build a service → suggest `kb-labs-create-product`
+- Something is broken → suggest `kb-labs-troubleshoot`
+- Wants to see what is installed → suggest `kb-labs-explore`
+- Wants to upgrade the platform → suggest `kb-labs-update`
+
+## Important rules
+
+- Never edit files inside `.kb/` directly — it is platform runtime state.
+- The user's project config lives at `.kb/kb.config.jsonc` (with comments) and
+  is safe to edit.
+- If `kb-create` is not on PATH, the user can also call `npx kb-create ...` from
+  the project root.