Domains
Each domain is the README.md of a directory under domains/. A small YAML frontmatter block carries its name and description; the Markdown body carries the business context.
The root domain is domains/README.md; every other domain is domains/<path>/README.md. Domain documents follow the Open Knowledge Format (OKF), so they read as plain documentation on GitHub and in any Markdown editor.
The parts
| Part | Where | Notes |
|---|---|---|
type | frontmatter, required | Always Domain. It is what marks the README as a domain file; a README without it is treated as ordinary prose and ignored |
title | frontmatter | Human name, shown in the UI and to the agent. Always set it |
description | frontmatter | One or two sentences. Shown when the parent domain lists its children |
| body | markdown | Everything after the frontmatter: the domain’s prose context. This is where business rules, glossary, and gotchas go |
Frontmatter follows the same strict rules as the YAML fields. Only type, title, and description are recognized. An unknown key, a typo like titel, is reported as drift and fails the check rather than being silently kept.
Example
---
type: Domain
title: Seller acquisition
description: 'Marketing qualified leads and closed deals: how Stallora wins new sellers.
Bridges to marketplace sellers.'
---
Prospective sellers enter as marketing qualified leads; the sales team closes
some of them into deals; a closed deal creates a seller on the marketplace.
<!-- cassis:nav:begin (generated, do not edit) -->
<!-- cassis:nav:end -->Generated navigation
Below the body, Cassis maintains a generated block between cassis:nav:begin and cassis:nav:end markers linking the tables and metrics placed in the domain, so the README browses on GitHub. It is regenerated on every format and publish, so do not hand-edit it. If it goes stale, because you placed or moved a table without re-running the formatter, the check fails and points you at cassis ontology fmt.
The directory path is the domain path
A domain’s path is its directory path under domains/. It is not stored anywhere inside the file, and the file is always named README.md.
| Domain path | File |
|---|---|
| (root) | domains/README.md |
marketplace | domains/marketplace/README.md |
marketplace/measuring-sales | domains/marketplace/measuring-sales/README.md |
- Moving or renaming a directory renames the domain. Tables and metrics reference domains by path (
domain_path: marketplace), so update those references in the same pull request. - Path segments are lowercase slugs: letters, digits,
_,-. No spaces, no uppercase. - Give every level its own
README.md, intermediate ones included. A child directory without a parent domain file leaves the parent unnavigable.
The root domain is the global context
domains/README.md supplies the agent’s global business context for every question, so it is where project-wide rules belong: what a win is, which rows to exclude by default, which vocabulary maps to which concept. A rule written here applies everywhere; a rule written in a leaf domain applies only when that domain is in play.
Migrating from the old format. Repositories authored before this used YAML domain files, _project.yml for the root and domains/<path>/_domain.yml for the rest. Cassis still reads them, so nothing breaks on upgrade. Convert whenever you like with cassis ontology fmt (cassis-cli 1.1.0 or newer), which rewrites the domain files and leaves the diff for you to review.