Domain Bundle File Formats

This guide is the format contract for Domain Bundles.

A Domain Bundle is the folder-scoped configuration unit for one domain:

1. config/domains/<domain_id>/cerebrum.md
2. config/domains/<domain_id>/cortices/*.md

The intent is to align humans and LLMs on one authoring model before any additional implementation work.

Status

Current status: Draft for review.

Use this document to propose changes, agree on names and required fields, then implement.

Pre-v1 schema policy:

1. This format can change quickly while we iterate.
2. Once a standard is chosen (for example key case), switch immediately.
3. Do not keep compatibility aliases for superseded markdown key shapes.

Design Principles

1. One file, two parts: YAML frontmatter plus Markdown body.
2. Frontmatter is machine-readable contract data.
3. Markdown body is human and LLM guidance.
4. Bundle structure should support progressive disclosure.
5. Source references should support local first, remote later.

Naming Convention

All markdown config keys and identifiers in this format must use kebab-case.

Rule:

1. Use kebab-case for frontmatter keys, reference keys, and profile/role identifiers.
2. Do not introduce new snake_case keys in markdown config files.
3. Do not preserve or add snake_case compatibility paths for markdown keys.

Examples:

1. domain-id not domain_id
2. required-cortices not required_cortices
3. module-path not module_path

Exceptions:

1. Python import values and symbol values are not reformatted. For example, cdp.comms_cortex and create_cli_comms_cortex remain unchanged as values.
2. Free-form payloads inside metadata values can contain snake_case when needed by downstream systems.

Domain Bundle Layout

config/domains/
  <domain_id>/
    cerebrum.md
    cortices/
      <cortex-id>.md

File Anatomy

Every config file uses:

1. Opening ---
2. YAML frontmatter
3. Closing ---
4. Markdown body

Domain Root File (cerebrum.md)

Path:

config/domains/<domain_id>/cerebrum.md

Required frontmatter fields:

Field	Type	Required	Notes
kind	string	yes	Must be cerebrum.
name	string	yes	Human-readable name.
description	string	yes	What this Domain Bundle is for and when to use it.
version	string	yes	Bundle schema/version tag.
domain-id	string	yes	Must match folder name.
tenant-id	string	yes	Tenant scope identifier.
lifecycle	string	yes	Example: proposed, active.
required-cortices	list	yes	Items must contain id and source.
degradable-cortices	list	yes	Items may fail without blocking boot; explicit list, can be empty.

Optional frontmatter fields:

Field	Type	Notes
metadata	mapping	Extension-safe metadata for non-runtime concerns.

Reference item shape (for both required and degradable lists):

Field	Type	Required	Notes
id	string	yes	Logical cortex identifier.
source	string	yes	Local relative path now; remote later.

Cortex File

Path:

config/domains/<domain_id>/cortices/<cortex-id>.md

Required frontmatter fields:

Field	Type	Required	Notes
kind	string	yes	Must be cortex.
id	string	yes	Must match the cerebrum reference id.
role	string	yes	Example: communication.
profile	string	yes	Profile key used by boot/chat selection.
description	string	yes	Human-readable summary.
launch	mapping	yes	Runtime launcher configuration.

Required launch fields:

Field	Type	Required	Notes
launch.launcher	string	yes	MVP uses inprocess.
launch.target.module-path	string	yes	Python module import path.
launch.target.symbol-name	string	yes	Callable symbol name.

Optional frontmatter fields:

Field	Type	Notes
agent	mapping	Prompt/model extras and agent hints.
metadata	mapping	Operational metadata.

Source Reference Model

Current support:

1. Local relative markdown paths such as ./cortices/cli-comms-cortex.md.

Planned support:

1. URL references.
2. Repository references.
3. Mixed local and remote references in one Domain Bundle.

Progressive Disclosure Model

The loader flow should be:

1. Read cerebrum frontmatter only.
2. Select candidate cortex refs by role/profile and required/degradable rules.
3. Load only selected cortex files.
4. Validate and compile runtime launch inputs.

This keeps context and parse work small while scaling to larger bundles.

Validation Rules

Baseline validation should enforce:

1. domain-id matches folder.
2. kind values are exact (cerebrum, cortex).
3. Every cortex ref has id + source.
4. Cortex file id matches reference id.
5. Required launch target fields exist for selected cortices.
6. Clear errors for unsupported remote sources.

Example: Cerebrum

---
kind: cerebrum
name: demo-cerebrum
description: Single-cortex MVP Domain Bundle for local CLI chat validation.
version: v0
domain-id: demo
tenant-id: tenant-demo
lifecycle: proposed
required-cortices:
  - id: comm.cli
    source: ./cortices/cli-comms-cortex.md
degradable-cortices: []
---

# Demo Domain Bundle

Authoring notes for humans and LLMs.

Example: Cortex

---
kind: cortex
id: comm.cli
role: communication
profile: cli
description: Communication cortex for terminal chat.
launch:
  launcher: inprocess
  target:
    module-path: cdp.comms_cortex
    symbol-name: create_cli_comms_cortex
---

# CLI Communication Cortex

Behavior and operating notes.

Review Checklist

Use this checklist before implementation updates:

1. Field names are stable and clear.
2. Required vs degradable fields are agreed.
3. Source reference roadmap is accepted.
4. Validation rules are complete enough for MVP.
5. Examples are copy-paste runnable.

Implementation Plan

Phase 1:

1. Enforce this bundle layout in local config.
2. Validate required frontmatter fields.
3. Keep remote sources explicitly unsupported.

Phase 2:

1. Add remote source resolver abstraction.
2. Add trust and provenance checks.
3. Add merge policy for mixed local and remote cortex configs.