Project baselines

What are Project Baselines?

A project baseline is a comprehensive configuration package that defines the complete modeling environment for a project. It actually defines the vocabulary along with capabilities and the patterns how to transfer items into code. Each baseline consists of:

• Baseline definition: A k5-baseline.yaml file defining core data of the baseline
• OML configuration: The main modeling configuration (k5-oml.yaml) that defines layers, references profiles, and specifies the modeling vocabulary
• Coding assistant recipes: Implementation guidance including:
  • Skills: Markdown files describing how implementation should be generated
  • Commands: Markdown files defining commands triggered in the prompt window
  • Rules: Markdown files defining validation and enforcement rules
• Documentation: A README.md file that describes the baseline and serves as a template for projects

Each baseline carries metadata including:

Attribute	Description
id	Unique identifier
version	Semantic version
name	Display name
description	Human-readable description
tags	Categorization tags
icon	Visual identifier
color	UI accent color
status	Lifecycle state: draft / published / deprecated

How Baselines work

Baselines are distributed as ZIP archives and follow a dedicated lifecycle:

1. Draft: Under development, can be modified and re-uploaded
2. Published: Released for use, immutable, available for project creation
3. Deprecated: No longer recommended, but still available for existing projects

Published baselines can be selected as the base for your new project during creation.

When a project is created with a baseline:

1. The system creates the repository in Git
2. Commits the Coding Assistant recipes (skills, commands, rules) from the selected baseline
3. Places the README.md at the project root
4. References the baseline in the project's k5-project.yaml

Projects can be updated to newer baseline versions through assisted upgrades, typically initiated by the project team. Within the workbench, each project can easily be changed to a different version as soon as it is made avaliable as a published baseline.

❗️info

Project baselines are managed in the admin settings of the Workbench. Here, you can create new baselines and manage their status. For further information on the basic structure of a baseline, view the reference section.

Baseline folder structure

Baselines are distributed as ZIP archives with standardized folder structure. Two standards are allowed for baselines:

Folder structure variant 1

baseline-name-VERSION/
├── baseline/                     # Folder for system definitions and main modeling configuration (k5-baseline.yaml, k5-oml.yaml, …)  -  required
│   └── recipes/...               # Folder for coding assistant recipes  -  optional
├── profiles/                     # Folder for the profiles referenced in k5-oml.yaml (*.yaml / *.yml)  -  optional
└── designRecipes/                # Folder for the design recipes that are copied to the repository, with one sub-folders per recipe  -  optional
    ├── recipe-a/
    │   ├── k5-design-recipe.yaml
    │   └── skills/...
    └── recipe-b/
        └── ...

With this folder structure, a new baseline can be uploaded together with the corresponding OML profiles and design recipes. This saves time especially if you begin working with the workbench.

Folder structure variant 2

baseline-name-VERSION/
├── k5-oml.yaml                    # Main modeling configuration (defines id, version, layers), references the profiles and systemDefinitions  -  required
├── k5-baseline.yaml               # System definitions (link types, organizational roles) – optional if using default  -  required
└── README.md                      # A readme file, that describes the baseline and is used for the project as template

This simplified folder structure can be used to upload new baselines for which the corresponding OML profiles and/or design recipes already exist in the OMl profiles overview. It is also possible to mix both structures and add a profiles or a design recipes folder.

Key Components

• baseline/: Optional folder for definitions and configuration (k5-oml.yaml, k5-baseline.yaml, see below)
• k5-oml.yaml: Required. Defines the modeling configuration including layers, profile references, and system definitions
• k5-baseline.yaml: Required. Contains system-specific definitions like link types and organizational roles. If not provided, defaults are used
• profiles/: Folder for OML profiles referenced in the main modeling configuration
• designRecipes/: Folder (with optional subfolders) containing implementation guidance:
  • skills/: Markdown files (.md) describing how to generate implementation
  • commands/: Markdown files defining commands for the prompt window. Files prefixed with k5- are automatically managed by the workbench
  • rules/: Markdown files defining validation and enforcement rules. Files prefixed with k5- are automatically managed by the workbench
• README.md: Required. Documentation that describes the baseline and serves as the initial README for projects created with this baseline

System Baselines

Workbench ships with pre-built system baselines that serve as starters and examples. These baselines:

• Follow the same lifecycle (draft → published → deprecated) as user-managed baselines
• Are maintained by the workbench team and updated regularly
• Serve as starting points for teams setting up their first baselines
• Can be downloaded, customized, and evolved into organization-specific versions

System-defined baselines are installed and updated through a dedicated API, which is available for admins in the designer-backend.

Currently following baselines are published:

• architecture — Architecture and Design — A high-level project to visualize and design the architecture and design of a project with help of C4
• java-basic-springboot — Basic Service Java — Implementing a service with Java/Spring Boot
• java-ddd-springboot — Domain Service Java — Implementing a domain service with Java/Spring Boot based on domain driven design terminology
• java-int-springboot — Integration Service Java — Implementing an integration service with Java/Spring Boot
• node-bff-nestjs — Backend for Frontend Node (NestJS) — Implementing a backend for frontend with Node/NestJS
• node-int-nestjs — Integration Service Node (NestJS) — Implementing an integration service with Node/NestJS

ℹ️note

System baselines can also easily be adjusted to exactly fit your project needs. To learn more about creating your own baselines and OML profiles, visit the Customization overview