Skip to main content

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.), baselines can define custom base folders that specify where recipes should be placed in the project repository. This allows recipes to be organized according to each coding assistant's conventions.

Example Configuration​

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"

File Management Rules​

When committing or updating recipes from a baseline the folder-structure of .recipes from the baseline will be synchronized to the base folder of the coding assistant.

ℹ️note

If there are multiple coding-assistants configured in the baseline, there will be multiple base folders as a result of the sync operation, where each of the base folder will contain the folders and files.

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