keiro-dsl-authoring

Author typed .keiro specifications and drive the keiro-dsl toolchain to generate Haskell event-sourcing services.

5|1|Updated May 4, 2026
One-click install
npx skills add https://github.com/shinzui/keiro --skill keiro-dsl-authoring-shinzui
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: keiro-dsl-authoring
Source: https://github.com/shinzui/keiro/tree/main/agents/skills/keiro-dsl-authoring
Command: npx skills add https://github.com/shinzui/keiro --skill keiro-dsl-authoring-shinzui

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building an event-sourced service on the keiro framework requires coordinating aggregates, process managers, timers, routers, Kafka inbox/outbox contracts, pgmq workqueues, read models, and durable workflows — all with replay-safety and evolution guarantees. This Skill makes a single .keiro specification the machine-checkable source of truth and drives the keiro-dsl CLI to validate, scaffold, and gate that spec instead of hand-writing the deterministic Haskell layer. ## Core Features & Use Cases - Spec authoring and validation: Write typed .keiro specs for every node type (aggregate/snapshot, process + timer, router, contract/intake/emit/publisher, workqueue/dispatch, readmodel, workflow/operation) and validate them with keiro-dsl check, including language-version contracts and CI flags like --min-language and --deny-warnings. - Deterministic scaffolding with typed holes: Run keiro-dsl scaffold to emit -- @generated modules (domain ADTs, codecs, transducers, stream/projection wiring) plus create-once hole modules that you fill against generated signatures — never editing generated code. - Conformance and evolution gating: Run the generated conformance harness to pin behavior and replay-safety, and use keiro-dsl diff --since <git-ref> to classify spec changes as ADDITIVE or BREAKING before merge. - Use Case: Add a new process manager with a timer to an existing service: declare the process node in the .keiro spec, run check, scaffold, fill the typed decoder hole, run the conformance tests, and diff the spec to confirm the change is additive. ## Quick Start Ask the agent to create a new keiro aggregate specification for your feature, then check, scaffold, and fill the generated holes using the keiro-dsl-authoring workflow.

Frequently Asked Questions about keiro-dsl-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a new keiro service specification?

Start with `cabal run -v0 keiro-dsl -- new <kind>` to print a minimal valid skeleton for kinds like aggregate, process, router, contract, intake, emit, publisher, workqueue, dispatch, workflow, or operation. Pipe it into a `.keiro` file, declare the language version, then run `check` before scaffolding.

How do I validate a .keiro spec before generating Haskell code?

Run `cabal run keiro-dsl -- check service.keiro`, which exits 0 only when every required decision is present and no dangerous inversion is misstated. For CI, add `--min-language 4`, `--deny-warnings`, and `--report-out` to enforce the stable contract and emit a JSON report.

Can I edit the generated Haskell modules from keiro-dsl scaffold?

No. Modules marked `-- @generated` are overwritten on every scaffold run. You only fill create-once hole modules such as `Holes.hs` or `ProcessHoles.hs` against the generated signatures; to change generated behavior, edit the `.keiro` spec and re-scaffold.

Why does startup report my event stream is not replay-safe?

The generated `mkEventStreamOrThrow` wrapper throws when the transducer fails validation, such as a `state-changing-epsilon` edge that changes state without emitting an event. Fix the hand-owned transducer or spec using the warning taxonomy; never bypass the gate with `mkEventStreamUnchecked`.

How do I safely evolve event schemas in a keiro service?

Run `keiro-dsl diff --since <git-ref> service.keiro` to classify the change. BREAKING means an on-disk payload could fail to decode; add a versioned event with `upcast from v(N-1) = HOLE` or a deprecated event until the diff reports ADDITIVE.

What are the limitations of the keiro-dsl notation?

Direct aggregate fields cannot use Json, Optional, List, or Map shapes; declare a `mapped structural` type instead. Time is always injected from input timestamps, never sampled from a wall clock, and Int arithmetic, division, and mixed numeric types are rejected by the checker.