Reference
Configuration
.cumaru/config.yaml declares the installed domain's tree and validation contracts. Start from the configuration shipped by your domain.
Authoritative shape: v9 JSON Schema. Default example: base configuration.
Top-level keys
| Key | Contract |
|---|---|
version | Required. The current schema requires the integer 9. This is the project contract version, not the CLI release version. |
domain | Required. The installed source domain name; base aliases __base. It is not a list of composable domains. |
rules | Required. Global Markdown, index, pillar-index, and named pattern-rule declarations. |
root | Required. The recursive configured tree, starting at .cumaru/. |
meta | Required. Adopter targets and optional context, coverage, durable-pillar and doctor settings. |
workflows | Optional. Named skill dependency graphs executed by the cumaru-flow skill. |
Unknown top-level properties are rejected. Named objects are closed where the schema declares them; the recursive root selectors are the structural extension point.
The recursive node
| Property | Meaning |
|---|---|
path | Optional non-empty string. Physical path override relative to the parent; otherwise the selector names the path. |
optional | Optional boolean. Makes a literal entry optional; glob selectors may match no entries. |
framework | Optional boolean. Only explicit true marks this entry framework-owned; ownership never inherits. |
frontmatter | A map from field names to contracts: {} requires presence; { optional: true } permits absence. |
tags | An array of unique semantic marker names required on the host. Bodies remain adopter-owned. |
child selectors | Literal or glob keys whose values are nodes of the same shape. There is no entities wrapper. |
A directory has its own index.md. The filesystem supplies its child inventory; declared semantic links express relationships. Literal selectors can specialize a glob. For example, an optional literal discipline entry can prevent a missing framework file from being recreated by ordinary update.
Sources: node model and literal ownership and update selection.
Global rules and names
rules.markdown requires required_heading and a frontmatter map. The shipped heading value is h1. rules.index_md and rules.pillar_index each require a frontmatter map. Additional named rule objects require severity (warning or error), a non-empty pattern, and an applies_to string array.
Names for domains, workflows, steps and named rules match ^[a-z][a-z0-9_-]*$. Frontmatter field names use ^[a-z][a-z0-9_-]*$. Tag names allow colon-separated segments under the schema's tag-name pattern. Use the schema for the exact grammar; valid field presence alone does not validate the meaning of its prose.
Adopter metadata
meta.targets.valuesis required: a non-empty array of unique strings. Align component keys with your confirmed project components; shipped domains reserveplatformandmeta.meta.specification_dirselects a durable pillar name or a non-empty unique list of pillar names for reference coverage. When absent, coverage usesspecs.meta.coverage.sourceis a string array of source globs. Empty or absent means the default tracked-source inventory. Coverage uses Git-tracked files, not a filesystem crawl; its glob*crosses directory separators.meta.context.frameworkandmeta.context.adopterare unique arrays of paths relative to.cumaru/.meta.context.sourceis relative to the project root.meta.doctor.after.warmis an optional boolean. When true, a passing doctor report warms the adopter context cache. This can write cache data; it does not download a model.
Context paths cannot be absolute or contain .. segments. Source-scope entries can use gitignore-style globs, where * stays in one segment and **/ spans directories. These differ from coverage globs. Source context does not honor .gitignore; keep its scope deliberate.
Sources: coverage configuration, context scopes, and doctor cache warming.
Workflow graphs
workflows.<name>.steps is a non-empty map. Each step requires a skill name and may declare a unique needs array of prerequisite step names. The cumaru-flow skill executes the configured graph and preserves its gates. It is not a native cumaru flow command.
This illustrative excerpt is JSON, which is also valid YAML. It is not a complete replacement config. The paths assume an SDLC Light project; keep your installed domain's structure and confirm your own targets.
{
"meta": {
"targets": { "values": ["platform", "meta", "webapp"] },
"specification_dir": "specs",
"coverage": { "source": ["src/**"] },
"context": {
"framework": ["domain.md", "index.md", "disciplines", "roles", "templates"],
"adopter": ["plans", "specs", "exploring"],
"source": ["src"]
},
"doctor": { "after": { "warm": false } }
},
"workflows": {
"inspect": {
"steps": {
"health": { "skill": "cumaru-doctor" },
"references": { "skill": "cumaru-refs", "needs": ["health"] }
}
}
}
} Source: workflow execution.
Validation and reconciliation
cumaru doctor validates the installed configuration and tree. cumaru update config prints a read-only reconciliation report and candidate. The agent must review it: source defaults can fill missing fields, valid adopter values remain, and invalid permitted values block automatic reconciliation.
The CLI does not write config through update config --apply; that invocation is invalid. The current project version integer and CLI build version are separate. Use migration instructions when crossing a supported config-version boundary.
Update reference · Migration reference · Ownership explanation