Project Baseline Reference

This reference describes the structure and format of project baselines, including the k5-baseline.yaml configuration file, ZIP archive structure, and API operations.

Baseline ZIP Archive Structure

A project baseline is distributed as a ZIP archive with the following structure:

baseline-name-VERSION.zip
├── k5-baseline.yaml          # Baseline metadata and configuration (required)
├── k5-oml.yaml               # OML configuration (required)
├── recipes/                  # Recipes folder (optional)
│   ├── skills/               # Skills for implementation generation
│   │   └── *.md              # Markdown files
│   ├── commands/             # Commands for prompt window
│   │   └── *.md              # Markdown files
│   └── rules/                # Validation and enforcement rules
│       └── *.md              # Markdown files
└── README.md                 # Documentation (optional)

The recipes tree may be named recipes/ or .recipes/; path mapping and baseFolder sync treat both the same.

File Requirements

Required files: k5-baseline.yaml, k5-oml.yaml
Optional files: README.md, a recipes tree folder (recipes/ or .recipes/) with any structure
Allowed extensions (root level): .yaml, .yml, .txt, .md
Recipes folder: Any file types allowed under recipes/ or .recipes/
Maximum size: 16 MB

Excluded Files

The following files are automatically excluded during processing:

MacOS resource fork files (._ *)
__MACOSX/ folders and their contents

k5-baseline.yaml Format

The k5-baseline.yaml file defines the baseline metadata and configuration.

Required Fields

id: "baseline-identifier"           # Unique baseline identifier
version: "1.0.0"                     # Semantic version
name: "Baseline Display Name"        # Human-readable name

Optional Fields

description: "Detailed description of the baseline"
tags:
  - "domain-driven-design"
  - "microservices"
icon: "Application"                  # Icon identifier
color: "#0f62fe"                     # Hex color code

Coding Assistant Preferences

codingAssistantPreferences maps each coding assistant id (for example cursor, bob, github) to an entry that controls how files from the baseline ZIP are copied into the project Git repository when the workbench syncs baseline content.

For each assistant, you must define one of the following (validation fails if both are missing):

Mode	When to use
`baseFolder` (string)	Copy only files that sit under a `recipes` or `.recipes` path segment in the archive; mirror the path below that segment into this repository-relative folder.
`mapping` (non-empty array)	Fine-grained rules: select arbitrary paths in the archive and place them under specific target folders. When `mapping` is present, it is used exclusively and `baseFolder` is ignored for that assistant.

Optional per-assistant field: label — display name for the assistant.

`baseFolder` example

codingAssistantPreferences:
  bob:
    baseFolder: "./.bob"
  cursor:
    baseFolder: "./.cursor"
  github:
    baseFolder: "./.github"

`mapping` rules

Each element of mapping is an object with:

Field	Type	Description
`source`	string (required)	Non-empty. Selects files in the baseline archive. Patterns match path suffixes relative to the ZIP root (a leading bundle folder in the archive does not need to appear in the pattern). `recipes/...` and `.recipes/...` are treated as equivalent for matching.
`target`	string (required)	Non-empty. Repository-relative directory; matched files are written under it, preserving subpaths after the static part of the `source` pattern. Must not use `..` to escape the repository root.
`overwrite`	boolean (required)	If `false`, this rule does not replace a file already written to the same path by an earlier rule. If `true`, it can.

source may use directory prefixes, glob patterns, extension filters (for example dir/*.yml, dir/**/*.yml), trailing dir/* for all files under a directory, and regular expressions written in slash form: /regex/.

`mapping` example

codingAssistantPreferences:
  cursor:
    label: "Cursor"
    mapping:
      - source: "recipes/skills/*"
        target: ".cursor/skills"
        overwrite: true
      - source: ".recipes/common.rules/**/*.yml"
        target: ".cursor/rules"
        overwrite: true

For a narrative explanation of behavior, see Recipes — Coding assistant support.

Complete Example

id: "ddd-quarkus-baseline"
version: "1.3.2"
name: "Domain Service based on Quarkus"
description: "A baseline configuration for implementing a domain service based on Quarkus with domain-driven-design principles"
tags:
  - "ddd"
  - "quarkus"
  - "domain-driven-design"
icon: "Application"
color: "#ca3131"
codingAssistantPreferences:
  bob:
    baseFolder: "./.bob"

k5-oml.yaml Format

The k5-oml.yaml file defines the OML configuration. See OML Configuration Reference for complete details.

Required Structure

id: "modeling-configuration-id"
version: "1.0.0"
name: "Configuration Name"
description: "Configuration description"

layers:
  - id: "layer-id"
    name: "Layer Name"
    description: "Layer description"

systemDefinitions:
  - id: "k5-oml-system"
    version: "1.0.0"

profiles:
  - id: "profile-id"
    version: "1.0.0"

Baseline Lifecycle States

Status	Description	Allowed Operations
`DRAFT`	Under development, can be modified	Upload new file, Download, Publish, Deprecate, Delete
`PUBLISHED`	Released for use, immutable	Download, Deprecate
`DEPRECATED`	No longer recommended	Download, Re-publish

State Transitions

DRAFT ──────────> PUBLISHED ──────────> DEPRECATED
  │                   │                      │
  │                   │                      │
  └───────────────────┴──────────────────────┘
           (Delete only from DRAFT)

API Operations

Upload Baseline

Endpoint: POST /api/project-baselines

Request:

Content-Type: multipart/form-data
Field: baselineFile (ZIP file, max 16 MB)
Allowed extensions: .zip
Allowed MIME types: application/zip, application/x-zip-compressed, application/octet-stream

Validation:

ZIP must contain k5-baseline.yaml and k5-oml.yaml
All referenced OML profiles must exist
Baseline ID + version combination must be unique (for new baselines)
For updates: baseline must be in DRAFT status

Response: 201 Created

{
  "baselineId": "ddd-quarkus-baseline",
  "baselineVersion": "1.3.2",
  "name": "Domain Service based on Quarkus",
  "status": "DRAFT",
  "description": "...",
  "tags": ["ddd", "quarkus"],
  "icon": "Application",
  "color": "#ca3131"
}

List Baselines

Endpoint: GET /api/project-baselines

Query Parameters:

publishedBaselineOnly: true | false (filter for published baselines only)
latestVersionOnly: true | false (show only latest version of each baseline)

Response: 200 OK

[
  {
    "baselineId": "ddd-quarkus-baseline",
    "baselineVersion": "1.3.2",
    "name": "Domain Service based on Quarkus",
    "status": "PUBLISHED",
    "k5Oml": { ... }
  }
]

Get Baseline Metadata

Endpoint: GET /api/project-baselines/:baselineId/:version

Response: 200 OK

{
  "baselineId": "ddd-quarkus-baseline",
  "baselineVersion": "1.3.2",
  "name": "Domain Service based on Quarkus",
  "status": "PUBLISHED",
  "k5Oml": {
    "id": "ddd-quarkus-config",
    "version": "1.0.0",
    "layers": [...],
    "profiles": [...]
  }
}

Download Baseline

Endpoint: GET /api/project-baselines/:baselineId/:version/download

Authorization: Requires admin privileges

Response: 200 OK

Content-Type: application/zip
Content-Disposition: attachment; filename="baseline-id-version.zip"
Body: ZIP file buffer

Update Baseline Status

Endpoint: PUT /api/project-baselines/:baselineId/:version/status

Authorization: Requires admin privileges

Request Body:

{
  "status": "PUBLISHED"
}

Allowed Transitions:

DRAFT → PUBLISHED
DRAFT → DEPRECATED
PUBLISHED → DEPRECATED
DEPRECATED → PUBLISHED

Validation for Publishing:

Baseline ZIP file must be valid
All referenced OML profiles must exist and be published

Response: 204 No Content

Delete Baseline

Endpoint: DELETE /api/project-baselines/:baselineId/:version

Authorization: Requires admin privileges

Restrictions:

Only baselines in DRAFT status can be deleted
Published and deprecated baselines cannot be deleted

Response: 204 No Content

Validation Rules

ZIP Archive Validation

Required files present: k5-baseline.yaml, k5-oml.yaml
File extensions (root level): Only .yaml, .yml, .txt, .md allowed
Recipes folder: Any file types allowed under recipes/ or .recipes/
Size limit: Maximum 16 MB
System files: MacOS resource forks and __MACOSX folders excluded

k5-baseline.yaml Validation

Required fields: id, version, name must be present
Version format: Must follow semantic versioning
Coding assistant preferences: If present, each assistant must define either a non-empty mapping array or a non-empty baseFolder string; each mapping entry must include non-empty source and target strings and a boolean overwrite

k5-oml.yaml Validation

Required fields: id, version, name, layers must be present
Profile references: All referenced profiles must exist in the system
System definitions: Must reference valid system definition IDs

Status Change Validation

Publishing: All referenced profiles must be in PUBLISHED status
Deletion: Only DRAFT baselines can be deleted
Re-upload: Only DRAFT baselines can be re-uploaded

Error Codes

Error	Description
`ProjectBaselineValidationError`	ZIP structure or YAML content is invalid
`ProjectBaselineAlreadyExistsError`	Baseline with same ID and version already exists
`ProjectBaselineNotFoundError`	Baseline with specified ID and version not found
`ProjectBaselineStatusUpdateNotAllowedError`	Status transition not allowed
`ProjectBaselineDeleteNotAllowedError`	Deletion not allowed (not in DRAFT status)
`ProjectBaselineReferenceNotPublishedError`	Referenced profile not published
`ProjectBaselineVersionIsLowerThanLatestError`	New version is lower than existing latest version

Best Practices

Versioning: Use semantic versioning (MAJOR.MINOR.PATCH)
Testing: Thoroughly test baselines in DRAFT before publishing
Profile dependencies: Ensure all referenced profiles are published first
Documentation: Include comprehensive README.md in the ZIP
Recipes organization: Structure recipes logically in subdirectories
File naming: Use k5- prefix for workbench-managed files
Size optimization: Keep ZIP archives under 16 MB
Backward compatibility: Consider compatibility when creating new versions

Baseline ZIP Archive Structure​

File Requirements​

Excluded Files​

k5-baseline.yaml Format​

Required Fields​

Optional Fields​

Coding Assistant Preferences​

baseFolder example​

mapping rules​

mapping example​

Complete Example​

k5-oml.yaml Format​

Required Structure​

Baseline Lifecycle States​

State Transitions​

API Operations​

Upload Baseline​

List Baselines​

Get Baseline Metadata​

Download Baseline​

Update Baseline Status​

Delete Baseline​

Validation Rules​

ZIP Archive Validation​

k5-baseline.yaml Validation​

k5-oml.yaml Validation​

Status Change Validation​

Error Codes​

Best Practices​

Related Documentation​

Baseline ZIP Archive Structure

File Requirements

Excluded Files

k5-baseline.yaml Format

Required Fields

Optional Fields

Coding Assistant Preferences

`baseFolder` example

`mapping` rules

`mapping` example

Complete Example

k5-oml.yaml Format

Required Structure

Baseline Lifecycle States

State Transitions

API Operations

Upload Baseline

List Baselines

Get Baseline Metadata

Download Baseline

Update Baseline Status

Delete Baseline

Validation Rules

ZIP Archive Validation

k5-baseline.yaml Validation

k5-oml.yaml Validation

Status Change Validation

Error Codes

Best Practices

Related Documentation