Blueprint Reference

Blueprints define how Maabarium runs a workflow. This page is intentionally user-facing. If you need the full contract, read the repository technical spec as well.

At a glance

A blueprint usually answers these questions:

What repository or workspace is this workflow operating on?
Which models or providers are involved?
How are proposals generated?
How are results evaluated?
What determines a winner?

It also answers two practical product questions that matter just as much:

What kind of deliverable is this workflow supposed to produce?
Should it touch one named file or a family of existing files?

Choose the workflow type first

Use this quick mapping before you reach for raw TOML fields:

Code or application improvement: code-oriented language, source-tree globs, and tests usually enabled.
One named document or prompt output: markdown or prompt language and an exact target path such as docs/release-plan.md.
Research brief with citations: research language and markdown-oriented targets.
LoRA artefact validation: lora language and artefact-focused targets.

The most common mistake is configuring a document workflow like a code workflow. If the output is one markdown file, make that explicit in the blueprint contract.

Minimal mental model

Think of a blueprint as a checked-in workflow plan, not just a prompt file.

[blueprint]
name = "example"

[domain]
repo_path = "/path/to/workspace"

The real files are richer than this, but the important part is that they are explicit and reviewable.

Target path rules

Use exact paths and globs deliberately:

Exact path: docs/project-brief.md Use this when the workflow should create or refine one specifically named file.
Glob: src/**/*.rs Use this when the workflow should scan or modify many existing files.
Markdown glob: docs/**/*.md Use this when the workflow should work across a collection of document files.

In practice, exact paths are safer for document-first workflows and globs are safer for code-first workflows.

How evaluator selection works

In Maabarium, language is not just descriptive metadata, but it is also not the only routing signal.

Evaluator selection follows this precedence:

Explicit override first: evaluator.kind = "process" selects a process plugin, and evaluator.kind = "builtin" plus evaluator.builtin = "code" | "prompt" | "research" | "lora" selects that built-in evaluator directly.
Template metadata second: bundled templates such as prompt optimization, general research, and LoRA validation map to their matching built-in evaluators.
Heuristic fallback last: language, metric names, blueprint name, and target paths still guide routing for older or custom blueprints.

As a result:

markdown does not automatically mean prompt evaluation.
research still strongly signals research-oriented behavior.
code-oriented values such as rust or application still fit source-tree work.
exact document paths and prompt-specific target paths remain useful fallback hints when no explicit evaluator override is present.

If you need fully deterministic behavior, prefer an explicit evaluator block in the blueprint itself.

For advanced readers

Technical references in the core repository:

Use those when you need implementation-level detail.