blong

Define database schemas, seed data, and test seed data in a Blong realm using the declarative

Create and configure suites in the Blong framework. Suites are the top-level organizational unit that group related realms and define multi-platform entry points (server, browser, desktop). Use this skill for each of the following distinct tasks - (1) Creating a new top-level solution or Blong project — follow the server/browser entry point patterns. - (2) Configuring test runners — follow the index.ts and internal.test.ts patterns. - (3) Wiring up multiple realms into a suite — follow the children and config patterns. Use this skill when the user explicitly requests any of these tasks, or when their request clearly aligns with one of them.

Understand, create, and maintain documentation in the Blong docs site (docs/blong/docs/). Docs are split into three tiers — rationale, concept, and pattern — with a strict separation of concerns between them. Use this skill whenever writing a new doc, splitting an existing one, or reviewing a doc to decide what tier it belongs to.

Implement BDD-style Cucumber/Gherkin tests in Blong using @cucumber/gherkin as the fully compliant parser. Converts .feature file strings into blong ChainStep[] arrays via featureToSteps. Step definitions map Gherkin patterns to handler calls. Supports Scenario Outline, Background, and all cucumber expression types. Use this skill whenever the user wants to write Gherkin feature files, define Given/When/Then steps, run BDD tests, or integrate cucumber-style testing with blong handlers.

Write server-side integration tests using mock handlers in Blong. Mock handlers in test/mock/ simulate external systems (databases, services). mockDispatch and testDispatch orchestrators in the test layer wire the mocks and tests together. Make sure to use this skill whenever the user wants to test without real infrastructure, mentions mocking adapters or external services, or needs server-side integration testing with deterministic mock data.

Write full-stack Playwright tests for Blong applications. The blong-browser package provides reusable fixtures (auto-login, Portal helper) and generic CRUD test helpers that work with any model spec. Tests run against the live dev server (Vite + blong-watch) and use primarily screenshot-based assertions. Use this skill whenever the user wants to write E2E tests, UI integration tests, Playwright tests, or full-stack browser tests — even if they just say 'test the UI' or 'add a visual test'.

Create business domain boundaries in Blong framework. Realms separate business logic into independent, modular units that can be deployed as monolith or microservices. Make sure to use this skill whenever creating a new business domain or service in Blong — even if the user says 'add a new module', 'create a new service', or 'set up a new package'.

Set up the test entry point to run Blong tests against the public or internal API. Covers loading server and browser platforms in index.ts, wiring the @feasibleone/blong-test package, and choosing between public API testing (browser-simulated) and internal API testing (server-only). Use this skill whenever setting up the test runner entry point for a suite, configuring index.ts for test execution, or deciding how to connect tests to a running platform — even if the user just says 'how do I run the tests' or 'set up the test entry point'.

Implement, extend, or debug the blong-browser React/TypeScript component library and portal framework. blong-browser is a Blong realm that lives in `core/blong-browser/`. Use this skill whenever working on UI components, Editor/Form/Explorer/Report pages, widgets, portal navigation, schema-driven forms, action wiring, Storybook stories, or any blong-browser adapter/orchestrator code — even if the user just says "add a page", "fix the widget", or "show this in a tab". For multi-language support, translations, or i18n, use the blong-i18n skill. For developing or improving the model system itself, use the blong-browser-model-dev skill. For using the model to implement CRUD pages in a realm, use the blong-browser-model skill.

Develop, extend, debug, or improve the blong-browser model system internals. The model system lives in `core/blong-browser/src/model/` and provides the `subjectObjectComponent` aggregator that auto-generates Browse/New/Open/Report pages from IModelSpec declarations. Use this skill when working on the model system itself: subjectObjectComponent, entry files (subjectObjectBrowse/New/Open/Report in component/), IModelSpec types, withDefaults, dropdownRegistry, or the mock system (adapter/mock.ts + subjectObjectMock.ts). For using the model to build realm pages, use the blong-model skill instead.

Use the blong-browser model system to implement CRUD pages in a blong realm or suite. The model system generates Browse/New/Open/Report pages automatically from IModelSpec declarations. Use this skill whenever a realm needs to contribute UI pages for domain entities — even if the user just says "add list and edit pages for this entity" or "wire up the UI for this API". For developing or improving the model system internals, use blong-model-dev instead.

Define input/output validation for Blong handlers using TypeScript types or TypeBox schemas. Automatic validation generates OpenAPI documentation and runtime checks. Make sure to use this skill whenever a handler needs typed parameters, you're generating API docs, or the user asks about schemas, validation rules, or TypeBox types in Blong — even if they don't mention 'validation' by name.

Provision and use real backend services in Kubernetes for Blong integration tests. Covers the test/integration/ kustomization.yaml structure, k3d cluster setup in CI, the ci-test Rush bulk command, wait.sh pattern, and tap-wrapped index.test.ts. Use this skill only when the user explicitly requests CI integration tests with real databases or services in a k3d cluster, or needs to wire Kubernetes manifests for a test backend.

Implement Enterprise Integration Patterns (EIP) as Blong handlers. Each pattern (Pipes and Filters, Content-Based Router, Splitter, Aggregator, Claim Check, etc.) maps to a single handler that calls downstream handlers via the handler proxy. Make sure to use this skill whenever the user mentions routing, filtering, splitting, aggregating, or transforming messages in a pipeline — even if they don't use the term 'EIP' or 'enterprise integration'.

Write automated tests for Blong handlers using parallel test execution. Tests run in parallel by default with automatic dependency detection via thenable proxies. Supports assertions, error testing, and test reuse. Make sure to use this skill whenever writing any test handler in Blong, including test-driven development, API testing, or verifying business logic — even if the user just says 'add a test' or 'write tests for this'.

Define and throw typed errors in Blong framework. Errors are defined in the error layer or inline, with support for parameterized messages, HTTP status codes, and error wrapping. Make sure to use this skill whenever defining, throwing, or handling errors in Blong — including error.ts files, validation failures, domain-specific exceptions, or any 'throw' that needs a typed error.

Implement, configure, or extend Blong CLI intents. Intents are named CLI signals (positional arguments to the `blong` command) that activate configuration blocks, layers, and framework features. Use this skill when creating a new intent for the `blong` CLI, configuring intent-based activation in a realm or adapter, documenting intent behaviour for agents, or understanding how the existing well-known intents work. Also use this skill when a user asks about "activations" — that is the older term for intents.

Organize handlers into named functional groups within a Blong realm. Layers include gateway (API), adapter (external systems), orchestrator (business logic), error (domain errors), and test (automation). Make sure to use this skill whenever creating a new layer in a realm, setting up the folder structure for handlers, or configuring which layers activate in which environment — even if the user just says 'organize this' or 'add a new layer'.

Simulate backend systems locally for Blong integration tests without requiring the real backend. Covers two patterns - OpenAPI-based HTTP simulation using orchestrator.openapi from @feasibleone/blong-openapi, and TCP-based simulation using adapter.tcp with listen=true. Use this skill whenever the real backend is unavailable, you need to stand up a local mock server for integration tests, or you want to exercise the full adapter and codec stack against a controlled simulator — even if the user just says 'mock the backend server' or 'simulate the HSM'.

Access real-time application logs via REST API. The log server runs at `http://127.0.0.1:9998` by default. Provides filtering by level, service name, trace ID, and free text search. Use this skill whenever monitoring application behavior, debugging issues, verifying feature behavior, searching for errors, or tracing requests across services — proactively check logs after making code changes, even if logs aren't explicitly mentioned.

Implement multi-language support (i18n) in blong-browser: translate UI labels, validation messages, and PrimeReact widget strings. Use this skill whenever working on translations, localization, language switching, the Text component, Button label translation, appStore setTranslations/setLanguage, PrimeReact locale registration, or adding a lang story arg — even if the user just says "add Bulgarian support", "translate this label", or "make this work in another language".

Initial Storybook v10 setup and configuration for React/TypeScript projects. Make sure to use this skill for any first-time Storybook installation or major configuration task — even if the user just says 'set up Storybook', 'add Storybook to this project', or 'configure addons'. Covers addon setup, monorepo composition, and CI/CD integration. For development workflow and testing patterns, see the storybook-testing-workflow skill.

Integrate Blong with external systems using adapter pattern. Supports HTTP/REST APIs, TCP protocols, SQL databases, and webhooks. Hides protocol details behind high-level APIs. Make sure to use this skill whenever the user wants to connect to a database, call an external API, integrate with an HSM or payment terminal, or wire up any external dependency — even if they just say 'add database support' or 'call this API'.

Implement protocols on top of transport layers in Blong. Includes HTTP codecs (OpenAPI, JSON-RPC, MLE) and TCP codecs (Payshield, ISO8583, SMPP). Handle serialization, deserialization, and request/response matching. Make sure to use this skill for any serialization/deserialization work, binary protocol wiring, or connecting to payment networks, HSM devices, or external systems with custom wire formats — even if the user doesn't say 'codec' explicitly.

Create API handlers and library functions in Blong using semantic triple naming (subjectObjectPredicate). Handlers implement business operations, protocol tasks, or reusable logic. Make sure to use this skill whenever you're writing any function in a Blong realm — API endpoints, library helpers, adapter logic, or test steps. Even if the user just says 'add a function' or 'implement this logic in Blong', use this skill.

Implement business logic coordination in Blong, decoupled from integration protocols. Orchestrators coordinate between adapters, define API namespaces, and become Kubernetes services. Use this skill whenever implementing business workflows, coordinating multiple adapter calls, adding business rules, defining new namespaces, or translating sequence diagrams to code — even without the word 'orchestrator'.

Implement REST APIs in Blong using OpenAPI/Swagger definitions. Framework defaults to JSON-RPC but supports REST for pre-defined APIs. Covers both server-side (gateway) and client-side (adapter) patterns with OpenAPI codec integration. Make sure to use this skill whenever the user mentions OpenAPI, Swagger, REST endpoints, HTTP methods like GET/PUT/DELETE, or needs to consume a pre-defined REST API from an external provider.

Daily Storybook development workflow and testing patterns. Make sure to use this skill whenever working on existing Storybook stories, writing play() functions, running interaction tests, or debugging component behavior — even if the user doesn't mention 'workflow' or 'testing' explicitly. For initial setup and configuration, see the storybook-v10-setup skill.