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
• 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

When a project is created with a baseline:

1. The system creates the repository in Git
2. Commits the 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 update to newer baseline versions through assisted upgrades, typically initiated by the project team.

Baseline Folder Structure

Baselines are distributed as ZIP archives with a standardized folder structure. A typical baseline archive contains:

baseline-name-VERSION/
├── k5-oml.yaml                    # Main modeling configuration (defines id, version, layers), references the profiles and systemDefinitions
├── k5-baseline.yaml               # System definitions (link types, organizational roles) – optional if using default
├── .recipes                        # Folder for the recipes, that are copied to the repository
│   ├── skills                     # A folder containing skills
│   │   └── recipe-1.md            # A skill / recipe that describes how implementation is generated
│   ├── commands                   # A folder containing commands
│   │   └── k5-command-1.md        # A command that is triggered in the prompt window
│   ├── rules                      # A folder containing rules
│   │   └── k5-rule-1.md           # A rule for validation and enforcement
└── README.md                      # A readme file, that describes the baseline and is used for the project as template

Key Components

• k5-oml.yaml: Required. Defines the modeling configuration including layers, profile references, and system definitions
• k5-baseline.yaml: Optional. Contains system-specific definitions like link types and organizational roles. If not provided, defaults are used
• recipes/: Optional folder 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