Spec & Codegen

This is the authoring core of the platform: you describe your product as YAML spec definitions, then generate code and artifacts from them. If you’re building a backend, this is where the real work happens, spec to define and validate, and code to scaffold. To import an existing database, use spec new --from-sql.

kis spec

What it is. The toolchain for the platform’s YAML specifications, the definitions (Entity, Workflow, Route, Pipeline, Agent, Policy, …) that describe what your product is. It validates, lints, scaffolds, inspects, and generates from them.

Why it exists. The platform is spec-driven: getting these YAML files right is the core authoring loop. spec is the safety net and accelerator for that loop, catch mistakes before they ship, scaffold from templates, and inspect the schema you’re writing against.

When to reach for it. Any time you create or edit a platform definition. This is the command you’ll use most when building on the platform.

kis spec list                       # all registered kinds and versions
kis spec schema Entity              # a kind's fields, types, and docs
kis spec new entity order           # scaffold a new definition
kis spec validate entities/order.yaml
kis spec lint entities/             # best-practice checks beyond schema

validate, check against the schema

The schema is auto-detected from each file’s kind. Works on files or whole directories.

kis spec validate entities/
kis spec validate --cross-ref entities/ workflows/   # check references resolve
kis spec validate --strict --format json entities/

lint, best-practice checks

kis spec lint --list-rules                           # see available rules
kis spec lint --fix entities/                        # auto-fix where possible
kis spec lint --ignore description-required entities/

new, scaffold definitions

kis spec new entity order
kis spec new workflow order-approval
kis spec new entity --from-sql schema.sql order      # seed fields from SQL
kis spec new entity -o entities/order.yaml --dry-run order

schema / generate, inspect and emit

kis spec schema Entity --format jsonschema
kis spec generate jsonschema --kind Entity --output ./schemas
kis spec generate docs --output ./docs

Global spec flags: --format text|json|yaml, -v/--verbose.

kis code

What it is. A family of code generators for platform building blocks, plus parsers that import from other formats.

Why it exists. It scaffolds the repetitive, structure-heavy code (components, forms, pages, routes, workflows) so you start from a working skeleton instead of a blank file, and it imports existing assets (JSON, JSON Schema, Postman collections) into platform definitions.

When to reach for it. Generating a new app artifact, or converting an external spec into platform form. kis code has 18 subcommands in three groups.

Generators, scaffold a platform building block:

Subcommand	Generates
`component`	A UI component
`page`	A page
`form`	A form
`formcontainer`	A form container
`formflow`	A form flow
`workflow`	A workflow
`website`	A website
`plugin`	A plugin
`automation`	An automation
`get`	App code (the `get` generator)

kis code component ...      kis code page ...       kis code form ...
kis code workflow ...       kis code website ...    kis code plugin ...
kis code automation ...     kis code formcontainer ...   kis code formflow ...

Converters, import an external format into platform definitions:

Subcommand	Purpose
`json2entity`	JSON → entity definition
`jsonschema2entity`	JSON Schema → entity definition
`postman2api`	Postman collection → API collection
`postman2atc`	Postman collection → ATC test cases

Route & port helpers:

Subcommand	Purpose
`update-routes`	Auto-generate routes from views
`generate-routes-js`	JS index from a routes YAML
`generate-routes-yaml`	Routes YAML per view file
`update-ports`	Configure ports on a product’s apps

With your data modeled, continue to Documents & OCR for document-driven logic, or jump ahead to storing data.