Mentu

Recipe Schema

Recipe Schema

A mentu recipe is a JSON file that defines an ordered set of agent steps. Recipes live in .mentu/recipes/ (project-local) or ~/.mentu/recipes/ (user-global). Run a recipe with mentu sequence <name>.

{
  "name": "hello-world",
  "description": "A minimal recipe",
  "workspace": "~/project",
  "steps": [
    {
      "label": "say-hello",
      "args": ["-P", "~/.mentu/prompts/hello.md"],
      "model": "claude-opus-4-6",
      "completion_keyword": "STEP_COMPLETE"
    }
  ]
}

Top-Level Fields

Field Type Required Description
name string Yes Recipe identifier. Used as the key passed to mentu sequence.
description string No Human-readable description shown in mentu recipe list.
workspace string No Target workspace directory. Absolute path or ~-relative.
type string No Recipe type: sequence (default), pipeline, compound, parallel, adversarial, convergent, temporal, sentinel, substrate.
requires object No Precondition check. { bins: string[], env: string[], vault_keys: string[] }.
cir object No CIR integration config. See CIR Configuration below.
env object No Key-value environment variables available to all steps.
steps array Yes (sequence) Ordered array of step objects.
sequences array Yes (pipeline) Ordered array of pipeline entries.
transfer_mode string No Default filesystem isolation: worktree, mirror, rsync, none.
vm bool No Recipe-level VM default. Overridden per step.
allow_destructive_intents bool No If true, warn instead of block on destructive patterns.
canary bool No false to skip the canary. Omit (or null) to run canary.
canary_timeout int No Canary timeout override, in seconds. Default 60.

Requires

Preconditions that must be satisfied before the recipe runs. The engine fails fast if any condition is not met.

{
  "requires": {
    "bins": ["node", "swift", "gh"],
    "env": ["GITHUB_TOKEN"],
    "vault_keys": ["STRIPE_KEY"]
  }
}
Field Description
bins Binaries that must exist on PATH.
env Environment variables that must be set.
vault_keys Keys that must exist in the mentu vault.

CIR Configuration

Configure how the recipe interacts with the CIR substrate.

{
  "cir": {
    "write_after_step": true,
    "embed": true,
    "detect_patterns_on_complete": true,
    "query_limit": 10,
    "pattern_min_strength": 0.5
  }
}
Field Type Default Description
write_after_step bool false Write CIR signals after each step completes.
embed bool false Generate embeddings for captured signals.
detect_patterns_on_complete bool false Run pattern detection when the recipe finishes.
query_limit int 10 Maximum signals fetched when the agent queries CIR.
pattern_min_strength float 0.5 Minimum pattern strength to surface to the agent.

Step Fields

Every step in steps is an object with these fields.

Field Type Default Description
label string (required) Unique step identifier within the recipe.
args string[] (required) CLI args passed to the step runner. Usually ["-P", "path/to/prompt.md"].
model string (inherit) Model ID (e.g. claude-opus-4-6).
effort string (inherit) Thinking effort: low, medium, high, max.
auth string (inherit) Auth profile name (e.g. rashid, juan).
permission_mode string (inherit) acceptEdits or bypassPermissions.
completion_keyword string (inherit) Keyword the agent emits to signal step completion.
max_phases int 10 Maximum agentic turns before the step is terminated.
timeout int 1800 Seconds before the step watchdog kills it.
build_command string (none) Shell command run after the step completes successfully.
depends_on string[] (none) Step labels that must complete before this step starts.
gate string (none) Set to review to pause for human review.
gate_options string[] (none) Options presented at the review gate.
gate_action string (none) Default action at the gate if none is chosen.
dir string (inherit) Per-step workspace override.
env object (inherit) Per-step environment variables.
vm bool (inherit) Per-step VM isolation override.
wave int (none) Execution wave number. Steps in the same wave run in parallel.
concurrencySafe bool false Mark step as safe for concurrent execution with its peers.
outputPersistenceThreshold int (none) Minimum output size (bytes) to persist to disk.

See Transfer Modes & VM Isolation for how vm and transfer_mode compose.

Recipe Types

Sequence (default)

The default type. Ordered execution of steps. Dependencies are resolved via depends_on and wave.

{
  "name": "build-and-test",
  "steps": [
    { "label": "build", "args": ["-P", "build.md"] },
    { "label": "test", "args": ["-P", "test.md"], "depends_on": ["build"] }
  ]
}

Pipeline

A chain of sequences. Each entry runs a recipe by name and passes results forward.

{
  "name": "release-pipeline",
  "type": "pipeline",
  "sequences": [
    { "name": "build-artifacts", "workspace": "~/project", "on": "success" },
    { "name": "run-tests", "on": "success" },
    { "name": "cleanup", "on": "always" }
  ]
}

Pipeline entry fields:

Field Type Description
name string Recipe to invoke.
workspace string Override workspace for this sequence.
model string Override model.
on string When to run: success, failure, always.
from string Resume from a specific step label.
pre string[] Shell commands to run before the sequence starts.

Compound

A compound recipe layers multiple sequences over a shared substrate. Layers can read each other's CIR signals.

{
  "name": "compound-audit",
  "type": "compound",
  "layers": [
    { "name": "static-analysis", "sequence": "analyze-code" },
    { "name": "dynamic-probe", "sequence": "probe-runtime" },
    { "name": "synthesis", "sequence": "audit-report" }
  ]
}

Parallel

A fanout of the same recipe across N concurrent runners. Useful for independent variations (A/B testing prompts, different strategies).

{
  "name": "parallel-exploration",
  "type": "parallel",
  "recipe": "explore-option",
  "fanout": 5,
  "vars": [
    { "OPTION": "a" },
    { "OPTION": "b" },
    { "OPTION": "c" },
    { "OPTION": "d" },
    { "OPTION": "e" }
  ]
}

Adversarial

Red team versus blue team pairing. Two agents argue, a judge picks the winner.

{
  "name": "security-review",
  "type": "adversarial",
  "red": { "recipe": "attack-strategies" },
  "blue": { "recipe": "defense-strategies" },
  "judge": { "recipe": "verdict" },
  "rounds": 3
}

Convergent

Run N strategies in parallel, pick the best result by a scoring rubric.

{
  "name": "find-fix",
  "type": "convergent",
  "strategies": 4,
  "recipe": "propose-fix",
  "scorer": "score-fix"
}

Variable Resolution

Variables are resolved in three layers. Higher layers override lower layers.

  1. Recipe env block (lowest priority). Static defaults declared in the recipe JSON.
  2. Process environment (middle priority). Any non-MENTU_-prefixed variable in the shell running mentu.
  3. CLI --var, webhook payloads, trigger vars (highest priority). Injected at run time.

Variables are substituted in prompts via $VAR_NAME or ${VAR_NAME}.

mentu sequence my-recipe --var TARGET=production --var TAG=v1.2.3

Workspace Configuration (mentu.yml)

A workspace may include a mentu.yml file that configures project-level defaults and provider endpoints.

oracle_url: https://api.mentu.ai
api_key: vault:api-key
providers:
  ollama:
    type: ollama
    base_url: http://localhost:11434
    models: [qwen3:14b, deepseek-coder:33b]
  anthropic:
    type: anthropic
    api_key: vault:anthropic-key
Field Description
oracle_url URL of the mentu oracle service.
api_key API key for the oracle. Use vault:<key> to reference a vault entry.
providers Map of provider name to provider config.

Provider config fields depend on the type. Common types: anthropic, ollama, openai, custom.

Example: Full Recipe

{
  "name": "deploy-pipeline",
  "description": "Build, test, canary, and deploy a service",
  "workspace": "~/project",
  "type": "sequence",
  "transfer_mode": "worktree",
  "vm": false,
  "requires": {
    "bins": ["swift", "gh"],
    "vault_keys": ["DEPLOY_TOKEN"]
  },
  "cir": {
    "write_after_step": true,
    "embed": true,
    "detect_patterns_on_complete": true
  },
  "env": {
    "DEPLOY_TARGET": "production"
  },
  "steps": [
    {
      "label": "build",
      "args": ["-P", "~/.mentu/prompts/deploy/build.md"],
      "model": "claude-opus-4-6",
      "effort": "high",
      "auth": "rashid",
      "completion_keyword": "STEP_COMPLETE",
      "timeout": 900
    },
    {
      "label": "test",
      "args": ["-P", "~/.mentu/prompts/deploy/test.md"],
      "model": "claude-opus-4-6",
      "depends_on": ["build"],
      "timeout": 600
    },
    {
      "label": "deploy",
      "args": ["-P", "~/.mentu/prompts/deploy/deploy.md"],
      "model": "claude-opus-4-6",
      "depends_on": ["test"],
      "gate": "review",
      "gate_options": ["approve", "abort"],
      "vm": true
    }
  ]
}

See also

PreviousRuntime CLI
© 2026 Mentu.