Documentation

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

Allowed configuration properties
KeyContract
versionRequired. The current schema requires the integer 9. This is the project contract version, not the CLI release version.
domainRequired. The installed source domain name; base aliases __base. It is not a list of composable domains.
rulesRequired. Global Markdown, index, pillar-index, and named pattern-rule declarations.
rootRequired. The recursive configured tree, starting at .cumaru/.
metaRequired. Adopter targets and optional context, coverage, durable-pillar and doctor settings.
workflowsOptional. 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

Node properties
PropertyMeaning
pathOptional non-empty string. Physical path override relative to the parent; otherwise the selector names the path.
optionalOptional boolean. Makes a literal entry optional; glob selectors may match no entries.
frameworkOptional boolean. Only explicit true marks this entry framework-owned; ownership never inherits.
frontmatterA map from field names to contracts: {} requires presence; { optional: true } permits absence.
tagsAn array of unique semantic marker names required on the host. Bodies remain adopter-owned.
child selectorsLiteral 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.values is required: a non-empty array of unique strings. Align component keys with your confirmed project components; shipped domains reserve platform and meta.
  • meta.specification_dir selects a durable pillar name or a non-empty unique list of pillar names for reference coverage. When absent, coverage uses specs.
  • meta.coverage.source is 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.framework and meta.context.adopter are unique arrays of paths relative to .cumaru/. meta.context.source is relative to the project root.
  • meta.doctor.after.warm is 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