@joktec/skills 0.1.2 → 0.1.4

package/skill-pack.json

@@ -1,6 +1,6 @@
 {
   "name": "@joktec/skills",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "sourceOfTruth": "../joktec-framework",
   "frameworkBaseline": {
     "repo": "https://github.com/joktec/joktec-framework",
@@ -41,106 +41,315 @@
       "requiredByDefault": true,
       "dependencies": [],
       "recommended": [],
-      "packages": ["@joktec/*"],
-      "scope": { "paths": ["**/*"] },
-      "triggers": ["joktec", "@joktec", "framework", "package selection"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "packages": [
+        "@joktec/*"
+      ],
+      "scope": {
+        "paths": [
+          "**/*"
+        ]
+      },
+      "triggers": [
+        "joktec",
+        "@joktec",
+        "framework",
+        "package selection"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-common-skill",
       "title": "JokTec Common Skill",
       "role": "foundation",
       "requiredByDefault": true,
-      "dependencies": ["joktec-framework-skill"],
+      "dependencies": [
+        "joktec-framework-skill"
+      ],
       "recommended": [],
-      "packages": ["@joktec/core", "@joktec/utils", "@joktec/cron", "@joktec/types"],
-      "scope": { "paths": ["packages/common/**"] },
-      "triggers": ["BaseController", "BaseService", "pagination", "config", "cron", "utils"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "packages": [
+        "@joktec/core",
+        "@joktec/utils",
+        "@joktec/cron",
+        "@joktec/types"
+      ],
+      "scope": {
+        "paths": [
+          "packages/common/**"
+        ]
+      },
+      "triggers": [
+        "BaseController",
+        "BaseService",
+        "pagination",
+        "config",
+        "cron",
+        "utils"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-mongo-skill",
       "title": "JokTec Mongo Skill",
       "role": "focused",
       "requiredByDefault": false,
-      "dependencies": ["joktec-framework-skill"],
-      "recommended": ["joktec-common-skill"],
-      "packages": ["@joktec/mongo"],
-      "scope": { "paths": ["packages/databases/mongo/**"] },
-      "triggers": ["mongo", "mongoose", "typegoose", "MongoRepo", "cursor pagination"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "dependencies": [
+        "joktec-framework-skill",
+        "joktec-common-skill"
+      ],
+      "recommended": [],
+      "packages": [
+        "@joktec/mongo"
+      ],
+      "scope": {
+        "paths": [
+          "packages/databases/mongo/**"
+        ]
+      },
+      "triggers": [
+        "mongo",
+        "mongoose",
+        "typegoose",
+        "MongoRepo",
+        "cursor pagination"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-mysql-skill",
       "title": "JokTec MySQL Skill",
       "role": "focused",
       "requiredByDefault": false,
-      "dependencies": ["joktec-framework-skill"],
-      "recommended": ["joktec-common-skill"],
-      "packages": ["@joktec/mysql"],
-      "scope": { "paths": ["packages/databases/mysql/**"] },
-      "triggers": ["mysql", "typeorm", "MysqlRepo", "schema-first decorators", "uuidv7"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "dependencies": [
+        "joktec-framework-skill",
+        "joktec-common-skill"
+      ],
+      "recommended": [],
+      "packages": [
+        "@joktec/mysql"
+      ],
+      "scope": {
+        "paths": [
+          "packages/databases/mysql/**"
+        ]
+      },
+      "triggers": [
+        "mysql",
+        "typeorm",
+        "MysqlRepo",
+        "schema-first decorators",
+        "uuidv7"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-broker-skill",
       "title": "JokTec Broker Skill",
       "role": "grouped",
       "requiredByDefault": false,
-      "dependencies": ["joktec-framework-skill"],
-      "recommended": ["joktec-common-skill"],
-      "packages": ["@joktec/kafka", "@joktec/rabbit", "@joktec/sqs", "@joktec/redcast"],
-      "scope": { "paths": ["packages/brokers/**"] },
-      "triggers": ["kafka", "rabbit", "sqs", "redcast", "broker", "message pattern"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "dependencies": [
+        "joktec-framework-skill",
+        "joktec-common-skill"
+      ],
+      "recommended": [],
+      "packages": [
+        "@joktec/kafka",
+        "@joktec/rabbit",
+        "@joktec/sqs",
+        "@joktec/redcast"
+      ],
+      "scope": {
+        "paths": [
+          "packages/brokers/**"
+        ]
+      },
+      "triggers": [
+        "kafka",
+        "rabbit",
+        "sqs",
+        "redcast",
+        "broker",
+        "message pattern"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-adapter-skill",
       "title": "JokTec Adapter Skill",
       "role": "grouped",
       "requiredByDefault": false,
-      "dependencies": ["joktec-framework-skill"],
-      "recommended": ["joktec-common-skill"],
-      "packages": ["@joktec/cacher", "@joktec/mailer", "@joktec/notifier", "@joktec/storage"],
-      "scope": { "paths": ["packages/adapters/**"] },
-      "triggers": ["cache", "mail", "notification", "storage", "adapter"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "dependencies": [
+        "joktec-framework-skill",
+        "joktec-common-skill"
+      ],
+      "recommended": [],
+      "packages": [
+        "@joktec/cacher",
+        "@joktec/mailer",
+        "@joktec/notifier",
+        "@joktec/storage"
+      ],
+      "scope": {
+        "paths": [
+          "packages/adapters/**"
+        ]
+      },
+      "triggers": [
+        "cache",
+        "mail",
+        "notification",
+        "storage",
+        "adapter"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-database-extended-skill",
       "title": "JokTec Extended Database Skill",
       "role": "grouped",
       "requiredByDefault": false,
-      "dependencies": ["joktec-framework-skill"],
-      "recommended": ["joktec-common-skill"],
-      "packages": ["@joktec/elastic", "@joktec/arango", "@joktec/bigquery"],
-      "scope": { "paths": ["packages/databases/elastic/**", "packages/databases/arango/**", "packages/databases/bigquery/**"] },
-      "triggers": ["elastic", "arango", "bigquery", "extended database"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "dependencies": [
+        "joktec-framework-skill",
+        "joktec-common-skill"
+      ],
+      "recommended": [],
+      "packages": [
+        "@joktec/elastic",
+        "@joktec/arango",
+        "@joktec/bigquery"
+      ],
+      "scope": {
+        "paths": [
+          "packages/databases/elastic/**",
+          "packages/databases/arango/**",
+          "packages/databases/bigquery/**"
+        ]
+      },
+      "triggers": [
+        "elastic",
+        "arango",
+        "bigquery",
+        "extended database"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-integration-skill",
       "title": "JokTec Integration Skill",
       "role": "grouped",
       "requiredByDefault": false,
-      "dependencies": ["joktec-framework-skill"],
-      "recommended": ["joktec-common-skill"],
-      "packages": ["@joktec/firebase", "@joktec/gpt"],
-      "scope": { "paths": ["packages/integrations/**"] },
-      "triggers": ["firebase", "gpt", "openai", "integration"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "dependencies": [
+        "joktec-framework-skill",
+        "joktec-common-skill"
+      ],
+      "recommended": [],
+      "packages": [
+        "@joktec/firebase",
+        "@joktec/gpt"
+      ],
+      "scope": {
+        "paths": [
+          "packages/integrations/**"
+        ]
+      },
+      "triggers": [
+        "firebase",
+        "gpt",
+        "openai",
+        "integration"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     },
     {
       "id": "joktec-tool-skill",
       "title": "JokTec Tool Skill",
       "role": "grouped",
       "requiredByDefault": false,
-      "dependencies": ["joktec-framework-skill"],
-      "recommended": ["joktec-common-skill"],
-      "packages": ["@joktec/http", "@joktec/file", "@joktec/alert"],
-      "scope": { "paths": ["packages/tools/**"] },
-      "triggers": ["http", "axios", "file", "alert", "tool"],
-      "outputs": { "codex": true, "claude": true, "cursor": true, "gemini": true, "copilot": true, "windsurf": true }
+      "dependencies": [
+        "joktec-framework-skill",
+        "joktec-common-skill"
+      ],
+      "recommended": [],
+      "packages": [
+        "@joktec/http",
+        "@joktec/file",
+        "@joktec/alert"
+      ],
+      "scope": {
+        "paths": [
+          "packages/tools/**"
+        ]
+      },
+      "triggers": [
+        "http",
+        "axios",
+        "file",
+        "alert",
+        "tool"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     }
   ]
 }

package/skills/joktec-adapter-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-adapter-skill
 description: Use when wiring or using JokTec adapter packages @joktec/cacher, @joktec/mailer, @joktec/notifier, or @joktec/storage for cache, mail delivery, push notifications, object storage, config-driven clients, and app-neutral adapter services.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Adapter Skill
@@ -20,6 +24,7 @@ Use this skill for pluggable external capability adapters.
 - Use validated config and `conId` where supported.
 - Keep secrets and credentials in app config or runtime environment, never in code.
 - Prefer adapter services over direct SDK usage in app services.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/skills/joktec-adapter-skill/references/adapters.md

@@ -1,12 +1,40 @@
 # Adapter Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/adapters/README.md`
+- `packages/adapters/AGENTS.md`
+- `packages/adapters/<package>/README.md`
+- `packages/adapters/<package>/src/index.ts`
+- package module/config/service files under `src/`
+
 ## Runtime Pattern
 
 Adapters are global Nest modules. Services own native client creation and expose package-specific operations.
 
+Most adapters follow `AbstractClientService`: config is validated, native clients are created by the service, `conId` selects the connection, and shutdown/retry/debug behavior should remain package-owned.
+
 ## Package Notes
 
 - Cacher: choose local, Redis, or Memcached stores based on runtime config.
 - Mailer: centralize mail transport configuration in the service that owns outbound email.
 - Notifier: keep push provider configuration outside app business logic.
 - Storage: keep storage metadata and object operations behind the adapter service.
+
+## Best Practices
+
+- Import adapter modules in the application layer, then inject services into domain services.
+- Keep provider credentials, endpoints, bucket names, SMTP secrets, and push credentials in runtime config.
+- Keep business payload composition in the consuming app. The adapter should send/cache/store, not decide product semantics.
+- Use `conId` for multiple providers or tenants instead of creating ad-hoc service instances.
+- Normalize provider errors at the package/app boundary so controllers do not branch on SDK-specific messages.
+- Mock SDK clients in unit tests; run live provider checks only in explicit integration or consumer harness tests.
+
+## Anti-Patterns
+
+- Do not put email template business rules inside `@joktec/mailer`.
+- Do not hardcode S3 buckets, Redis URLs, SMTP credentials, or notification tokens in source.
+- Do not bypass adapter services by importing provider SDK clients directly throughout the app.
+- Do not assume every adapter has identical method names; read each package README/source before calling.

package/skills/joktec-broker-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-broker-skill
 description: Use when wiring or using JokTec broker packages @joktec/kafka, @joktec/rabbit, @joktec/sqs, or @joktec/redcast, including client config, producer decorators, consumer loaders, message handlers, auto-binding, and app-level broker flows.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Broker Skill
@@ -20,6 +24,7 @@ Use this skill for message broker packages.
 - Use broker decorators for transport wiring, not for domain policy.
 - Preserve config-driven client selection and `conId` when available.
 - Keep topic, queue, and routing names explicit in app configuration or decorators.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/skills/joktec-broker-skill/references/brokers.md

@@ -1,12 +1,41 @@
 # Broker Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/brokers/README.md`
+- `packages/brokers/AGENTS.md`
+- `packages/brokers/<package>/README.md`
+- `packages/brokers/<package>/src/index.ts`
+- package decorators, loaders, config, and service files under `src/`
+
 ## Runtime Pattern
 
 Broker services follow `AbstractClientService` lifecycle. Loader classes discover decorator metadata after module initialization. Apps define producers, consumers, and message semantics.
 
+Use broker packages for transport wiring, not for business workflow ownership. The consuming app owns event names, payload contracts, idempotency, retry policy, dead-letter behavior, and handler semantics.
+
 ## Package Notes
 
 - Kafka: check topic existence and broker advertised listeners in local development.
 - RabbitMQ: use module options and decorators for exchanges, queues, and bindings.
 - SQS: local ElasticMQ-style environments may require queues to exist before consumers start.
 - Redcast: use Redis-backed list, stream, or pub/sub behavior when a lightweight broker is enough.
+
+## Best Practices
+
+- Start consumers only in processes that should own subscriptions.
+- Keep producer and consumer payload DTOs versionable and explicit.
+- Use config paths or module options for topic/queue names when supported.
+- Make handlers idempotent; brokers may redeliver.
+- Add observable effects for consumer tests rather than asserting log text.
+- Keep broker health/preflight checks separate from business request handling.
+- In local stacks, verify broker-specific infrastructure: Kafka topics, Rabbit exchanges/queues, SQS queues, Redis password/db.
+
+## Anti-Patterns
+
+- Do not hide domain workflows inside decorators or broker package services.
+- Do not assume auto-create topic/queue behavior unless the package and local broker support it.
+- Do not run the same consumer group/queue owner in every process by accident.
+- Do not swallow message handling errors without retry/dead-letter visibility.

package/skills/joktec-common-skill/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: joktec-common-skill
 description: Use when implementing or wiring @joktec/core, @joktec/utils, or @joktec/cron in a consumer app, especially BaseController, BaseService, pagination, config, client lifecycle, bootstrap, cron decorators, or utility helpers.
+metadata:
+  dependencies:
+    - joktec-framework-skill
 ---
 
 # JokTec Common Skill
@@ -21,6 +24,7 @@ Use this skill for shared framework primitives, low-level helpers, cron utilitie
 - Use page, offset, or cursor pagination contracts from core; let database packages execute storage-specific pagination.
 - Use `AbstractClientService` patterns for client packages that need config, lifecycle, retry, and `conId`.
 - Use `@joktec/utils` for shared helpers instead of duplicating conversion, validation, hashing, or UUID logic.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## References
 

package/skills/joktec-common-skill/references/core.md

@@ -1,19 +1,75 @@
 # Common Core Usage
 
+## Source Lookup
+
+When blocked, inspect these framework files before guessing:
+
+- `packages/common/core/README.md`
+- `packages/common/core/AGENTS.md`
+- `packages/common/core/src/index.ts`
+- `packages/common/core/src/abstractions/*`
+- `packages/common/core/src/models/base.request.ts`
+- `packages/common/core/src/models/base.response.ts`
+- `packages/common/core/src/models/paginations/*`
+- `packages/common/core/src/client/abstract-client.service.ts`
+- `packages/common/core/src/infras/application.ts`
+- `packages/common/core/src/modules/*`
+
 ## Runtime Bootstrap
 
 Use the application bootstrap helpers from `@joktec/core` for gateway and microservice runtimes. Keep runtime behavior config-driven.
 
+Best practice:
+
+- Use `Application.bootstrap(AppModule)` instead of hand-rolling Nest bootstrap unless the consumer app has a specific runtime reason.
+- Keep gateway-only behavior in gateway runtime modules and microservice-only behavior in micro runtime modules.
+- Register framework modules through their dynamic module APIs when provided.
+- Do not duplicate config parsing, logger setup, metrics setup, or process lifecycle hooks in consumer apps.
+
 ## CRUD Abstractions
 
 - `BaseController` creates standard REST CRUD endpoints for DTO-backed resources.
 - `BaseService` delegates repository operations through the shared repository contract.
 - `ClientController` and `ClientService` provide generated microservice CRUD patterns.
 
+Use BaseController/BaseService when the resource follows standard CRUD. Avoid them when the endpoint has domain-specific command semantics, multi-step transactions, or non-standard authorization that would make the generic abstraction obscure behavior.
+
+Controller checklist:
+
+- choose the DTO/entity class intentionally
+- set `paginationMode` for the representative Swagger response shape
+- use `customDto.paginationDto` only when the built-in page/offset/cursor response does not represent the API
+- keep auth/guards/interceptors consistent with app conventions
+- avoid putting business branching in controller methods when it belongs in the service
+
 ## Pagination
 
 Request priority is cursor, then offset, then page. `BaseController.paginationMode` affects Swagger response shape; runtime selection remains request-driven unless the app service narrows it.
 
+Best practice:
+
+- Use page pagination for admin tables and simple back-office views.
+- Use offset pagination for mobile-style load-more when the data set is moderate and stable enough.
+- Use cursor pagination for feeds, timelines, frequently inserted lists, or large tables.
+- Do not document cursor support for a resource unless the underlying repository package actually supports it.
+- When using cursor mode, ensure the database layer has stable sort keys and tie-breakers.
+
 ## Client Lifecycle
 
 Use `ClientConfig`, `AbstractClientService`, and `conId` when building or consuming packages that support multiple client connections.
+
+Client package checklist:
+
+- config class validates all required runtime options
+- service startup fails clearly when the native client cannot initialize
+- shutdown closes native connections only when initialized
+- `conId` is preserved through service/repository calls
+- logs do not leak credentials or full connection strings
+- retries and debug behavior are config-driven
+
+## Do Not
+
+- Do not import concrete package or app code into `@joktec/core`.
+- Do not bypass shared pagination contracts with ad-hoc response shapes for standard CRUD.
+- Do not add new public symbols without exporting them through `src/index.ts`.
+- Do not silently swallow bootstrap/client initialization failures.

package/skills/joktec-common-skill/references/utils-cron.md

@@ -6,12 +6,40 @@ Use `@joktec/utils` for common generators, validators, converters, hashing helpe
 
 Prefer package helpers over app-local reimplementation when behavior should stay consistent across services.
 
+Source lookup:
+
+- `packages/common/utils/README.md`
+- `packages/common/utils/src/index.ts`
+- `packages/common/utils/src/helpers/*`
+- `packages/common/utils/src/validators/*`
+- `packages/common/utils/src/constants/*`
+
+Best practice:
+
+- Use shared validators from `@joktec/utils` when building schema-first entity/schema decorators.
+- Use shared generators for IDs, tokens, random values, and hashes when consistency matters.
+- Keep utility usage deterministic in tests; mock time/randomness where needed.
+- Do not add framework-level dependencies to `utils`.
+
 ## Cron
 
 Use `@joktec/cron` when a consumer app needs scheduled jobs, job worker contracts, or decorator-driven cron registration.
 
 Keep job business logic in the consumer app. The package provides scheduling abstractions, not domain behavior.
 
+Source lookup:
+
+- `packages/common/cron/README.md`
+- `packages/common/cron/src/index.ts`
+- cron decorators, models, scheduler services, and worker contracts under `src/`
+
+Best practice:
+
+- Keep job names, schedules, concurrency, and retry behavior visible in the consumer app.
+- Make cron handlers idempotent.
+- Avoid enabling the same cron owner in multiple processes unless the package/app has explicit locking semantics.
+- Treat cron runtime as infrastructure orchestration; domain writes still belong in app services/repositories.
+
 ## Types
 
 Use `@joktec/types` when a consumer workflow needs generated JokTec package config schema/type artifacts. Treat the framework repository as source-of-truth for the generated schema shape.

package/skills/joktec-database-extended-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-database-extended-skill
 description: Use when working with extended JokTec database packages @joktec/elastic, @joktec/arango, or @joktec/bigquery in a consumer app, including app-neutral client setup, config-driven lifecycle, and package-specific query/service usage.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Extended Database Skill
@@ -19,6 +23,7 @@ Use this skill for database clients that are not Mongo or MySQL.
 - Use package services for client lifecycle and connection config.
 - Do not claim parity with Mongo/MySQL repository behavior unless the package implements it.
 - Use package README and source as final truth before adding advanced behavior.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference