Getting Started

Getting Started

Prerequisites

  • Node.js ≥ 20.10
  • pnpm 9.x (via Corepack: corepack enable)
  • Python ≥ 3.12
  • uv for Python dependency management — installation

Install

git clone https://github.com/lokomotifai/lokomotif-kit.git
cd lokomotif-kit
corepack enable
pnpm install
cd packages/eval && uv sync
cd ../..

Verify the install

pnpm typecheck
pnpm lint
pnpm test
pnpm validate:modules

Each command should exit cleanly. If anything fails, file an issue with the output before continuing.

Scaffold a module

Modules belong to exactly one RTCSG concern: role, task, context, style, or guardrail. Use the CLI to scaffold a frontmatter-complete skeleton — every composition needs at least a role or a task, so a role is a good place to start in your own project:

pnpm -F @lokomotif/cli start -- modules new role finance/your-role

This writes:

  • modules/roles/finance/your-role.yaml — the module skeleton with TODO markers.
  • modules/roles/finance/__tests__/your-role.eval.yaml — the eval test placeholder.

Replace TODOs with content adapted from real practice. Modules must reflect actual practice — see Authoring Modules for the rule and the policy behind it.

Validate the module

pnpm validate:modules

The schema validator walks modules/**/*.yaml, validates each file, and reports failures with JSON Pointer paths. A green run means every module is shape-correct.

Run the eval

cd packages/eval
uv run lokomotif-eval run

The harness loads each module and its sibling __tests__/<name>.eval.yaml, runs every check, and reports pass/fail. The default LLM judge is the deterministic stub — CI runs without API keys.

Compose a flow

A flow combines modules into a single prompt:

# flow.yaml
name: kvkk-board-brief
modules:
  - roles/finance/your-role # the role you scaffolded above
  - contexts/finance/kvkk-compliance
  - styles/cross-industry/executive-board-brief
  - guardrails/cross-industry/pii-tr
pnpm -F @lokomotif/cli start -- compose flow.yaml

The CLI canonicalizes the order to R → T → C → S → G, deduplicates, and emits a single prompt. Every composition needs at least one role or task — compose throws if both slots are empty. For programmatic use, call compose() from @lokomotif/sdk.

What ships in v0.1.0. Three Pass-1 modules: contexts/finance/kvkk-compliance, styles/cross-industry/executive-board-brief, guardrails/cross-industry/pii-tr. Roles and tasks (roles/finance/aml-analyst, tasks/general/structured-summary) ship as Pass-2 in v0.2.0 — author your own in the meantime. See ROADMAP.md.

Next steps

  • The Method — RTCSG, the Maturity Spectrum, the Three-Horizon Adoption Journey.
  • Authoring Modules — frontmatter, body shapes per kind, source-material rules.
  • Eval Harness — eval YAML format, judges, and how to add your own.
  • Blueprints — Anthropic SDK, Dify, n8n, LangGraph adapters.
Lokomotif KitThe Method