Recipes

Available in product edition: Professional

What are Recipes?

Recipes is a collection term for implementation guidance that helps translate design models into working code. Recipes are committed to the Git repository and picked up by coding assistants as skills, commands, and/or rules. They encompass:

• Coding Guidelines: Standards and conventions for writing code
• Technology Definitions: Specifications of frameworks, libraries, and tools to use
• Project Dependencies: Required packages, modules, and their versions
• Implementation Patterns: Proven solutions for common design problems
• Commands: Executable workflows triggered in the prompt window
• Workflows: Step-by-step processes for common development tasks

Recipes are organized into three main categories:

• Skills: Markdown files (.md) that describe how implementation should be generated from design models. They provide context and patterns for coding assistants to follow when creating code.
• Commands: Markdown files that define commands triggered in the prompt window. These enable quick access to common workflows and operations.
• Rules: Markdown files that define validation and enforcement rules. They help maintain consistency and quality across the codebase.

How Recipes Work

Recipes are stored in the project's git repository within the base folder of the codingAssistant with a structure like:

.codingAssistant/
├── skills/
│   └── recipe-1.md            # Implementation generation guidance
├── commands/
│   └── k5-command-1.md        # Prompt window commands
└── rules/
    └── k5-rule-1.md           # Validation and enforcement rules

When a project is created from a baseline, the recipes from that baseline are automatically committed to the project repository. Coding assistants then:

1. Discover recipes in the repository
2. Parse the markdown content to understand patterns and rules
3. Apply the guidance when generating or validating code
4. Execute commands when triggered by developers

Updating Recipes

Recipes in a project are synchronized with the baseline at specific points in the project lifecycle. Understanding when and how updates occur helps teams manage their custom recipes alongside baseline-provided ones.

When Recipes Are Updated

The project's recipes are updated in the following scenarios:

1. Project Creation: When a new project is created, all recipes from the selected baseline are committed to the project repository according to the coding assistant mappings.

2. Baseline Version Change: When a user chooses a new version of a baseline for the project, the system updates the recipes to match the new baseline version. This is typically done through project settings and can be assisted by AI commands for migration.

3. Manual Sync: Users can manually trigger the Sync baseline action to refresh recipes from the current baseline version. This is useful for:

   • Recovering from accidental manual edits to workbench-managed files
   • Ensuring the project has the latest baseline content without changing versions
   • Resolving inconsistencies between the project and baseline

Update Behavior

During recipe updates:

• Workbench-managed files (prefixed with k5-): Always overwritten with baseline content. Files residing in .k5 folder are always treated as workbench-managed files.
• User-managed files (no k5- prefix):
  • Added if they don't exist
  • Left unchanged if they already exist
  • Never deleted during updates
• Deleted baseline files: Workbench-managed files removed from the baseline are deleted from the project; user-managed files are preserved

This approach allows teams to maintain custom recipes while benefiting from baseline updates and improvements.

Recipe Types

Skills

Skills describe how to generate implementation from design models. They typically include:

• Context: What design elements the skill applies to
• Patterns: Code patterns and structures to generate
• Examples: Sample implementations
• Dependencies: Required libraries or frameworks
• Best Practices: Coding standards and conventions

Example use cases:

• Generating REST API endpoints from service definitions
• Creating database schemas from domain models
• Implementing event handlers from business events
• Scaffolding test suites from component specifications

Commands

Commands provide quick access to common workflows through the prompt window. They can:

• Execute multi-step processes
• Generate boilerplate code
• Run validation checks
• Trigger migrations or updates
• Perform project-specific operations

Example use cases:

• Updating project dependencies
• Running code quality checks
• Generating documentation
• Migrating to new baseline versions

Rules

Rules enforce consistency and quality across the codebase. They define:

• Validation criteria: What to check
• Severity levels: Error, warning, or info
• Enforcement scope: Where rules apply
• Remediation guidance: How to fix violations

Example use cases:

• Enforcing naming conventions
• Validating API contracts
• Checking dependency versions
• Ensuring test coverage
• Verifying security practices

Coding Assistant Support

To support different coding assistants (Bob, GitHub Copilot, Cursor, etc.), a baseline declares codingAssistantPreferences in k5-baseline.yaml. For each assistant id, the workbench copies files from the baseline archive into the Git repository when creating a project, changing the baseline version, running Sync baseline.

Each assistant entry must use one of the following (see Fine-grained path mapping for details):

• baseFolder only — Mirror the baseline’s recipes / .recipes tree into a single directory in the repo.
• A non-empty mapping list — Control exactly which paths in the baseline map to which repository paths. When mapping is present, it is used exclusively; baseFolder is ignored for that assistant.

Example configuration (baseFolder)

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"
codingAssistantPreferences:
  bob:
    baseFolder: "./.bob"
  github:
    baseFolder: "./.github"
  cursor:
    baseFolder: "./.cursor"

Fine-grained path mapping

For each assistant, mapping is a list of rules. Each rule has:

Field	Description
source	Selects files under the baseline zip root. Patterns match path suffixes (a leading folder in the archive, e.g. a bundle name, does not need to appear in the pattern). recipes/... and .recipes/... are treated as aliases for matching.
target	Repository-relative directory (no ..); matched files are written under this folder, preserving subpaths after the static part of the pattern.
overwrite	Boolean (required in k5-baseline.yaml for baseline upload). If false, the rule does not replace a file already written to the same destination by an earlier rule. If true, a later rule can replace that destination.

source patterns can include directory prefixes, globs, extension filters such as dir/*.yml or dir/**/*.yml, directory-wide recursion like dir/*, and regular expressions written as /pattern/ (slash-delimited). Files outside a recipes / .recipes segment can be included when you use mapping; this is the main difference from baseFolder-only mode.

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

File management rules

baseFolder (no mapping, or empty mapping): When committing or updating from the baseline, only files that sit under a path segment named recipes or .recipes in the archive are copied; their path below that segment is mirrored under the assistant’s baseFolder. Root metadata files such as k5-baseline.yaml and k5-oml.yaml are not copied in this mode.

mapping (non-empty): Files are selected and placed according to each rule’s source and target. Multiple assistants each produce their own target layout; rules from different assistants are merged, respecting each rule’s overwrite flag.

ℹ️note

If several coding assistants are configured, you get one output layout per assistant (each under its baseFolder or per its mapping rules). The track’s enabled assistants determine which of those apply for a given operation.

Best Practices

• Keep recipes focused: Each recipe should address a specific concern or pattern
• Use clear language: Write recipes for both humans and AI assistants
• Include examples: Provide concrete code samples and use cases
• Version carefully: Update recipes alongside code changes
• Document dependencies: Clearly specify required tools and libraries
• Test thoroughly: Validate that recipes produce correct results
• Organize logically: Group related recipes in subdirectories
• Maintain consistency: Follow established patterns across recipes