Configure Goose recipes

How to attach parameterised recipe playbooks to a Goose project, what the recipe file format supports, and how spec-task authors fill in recipe parameters at task creation time.

Goose supports recipes — reusable, parameterised playbooks for recurring tasks such as triaging a failing CI run, writing release notes, or reviewing a spec document. You define a recipe once, commit it to a repository, attach it to a Goose project, and Helix renders a structured form on the spec-task creation screen for each recipe. The agent receives a fully baked recipe at session start — no free-text prompting to gather context.

This guide covers everything after the initial agent selection. For the basic Goose project YAML, start there.

Attach recipes to a project

Recipes are declared in the goose.recipes list on the project agent. Each entry names a recipe and gives its path relative to the repository it lives in:

apiVersion: helix.ml/v1alpha1
kind: Project
metadata:
  name: my-app
spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true
 
  agent:
    name: "Goose Agent"
    runtime: goose_code
    model: claude-sonnet-4-6
    provider: anthropic
 
    goose:
      recipes:
        - name: triage
          path: .goose/recipes/triage.yaml
        - name: fix-flaky-test
          path: .goose/recipes/fix-flaky-test.yaml

By default, path resolves against the primary repository. If your recipes live in a separate repository, add that repository to the project and point recipe_repo_url at it:

spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true
    - url: "https://github.com/org/goose-recipes"
      branch: main
 
  agent:
    runtime: goose_code
    goose:
      recipe_repo_url: "https://github.com/org/goose-recipes"
      recipes:
        - name: triage
          path: recipes/triage.yaml
        - name: release-notes
          path: recipes/release-notes.yaml

path is repo-relative and free-form — .goose/recipes/ is a convention, not a requirement.

Recipe file format

A recipe is a small YAML file in the repository:

version: "1.0.0"
title: "Triage failing CI"
description: "Walk through a failing CI run and produce a triage note."
 
instructions: |
  You are helping diagnose a failing CI run. Stay focused on the run
  the user provided; do not wander into unrelated branches or issues.
 
prompt: |
  Investigate the failing CI run at {{ ci_url }} for branch {{ branch }}.
  Identify the failing step, root-cause the failure, and produce a
  triage note covering what failed, the likely cause, the smallest
  plausible fix, and whether the failure looks flaky.
 
parameters:
  - key: ci_url
    input_type: string
    requirement: required
    description: "URL of the failing CI run"
  - key: branch
    input_type: string
    requirement: required
    description: "Branch the run was for"

prompt and instructions may use Jinja-style {{ key }} placeholders. The key must match a parameters[].key value.

Parameter types

Each parameter in the list becomes one field on the task creation form.

String

The most common type. Renders as a text input.

parameters:
  - key: branch
    input_type: string
    requirement: required
    description: "Branch name to operate on"
  - key: head_ref
    input_type: string
    requirement: optional
    default: HEAD
    description: "Ref to compare against (defaults to HEAD)"

Set default to pre-fill the field. Optional parameters without a default render as empty.

Select

Renders as a dropdown. Declare the allowed values in options:

parameters:
  - key: audience
    input_type: select
    requirement: required
    options:
      - engineering
      - customer
      - marketing
    description: "Who the release notes are for"

File

Renders as a dropdown populated from the Attachments section of the same spec-task form. The agent receives the absolute path to the file inside the sandbox — no separate upload step, no size limit beyond the attachment limit itself.

parameters:
  - key: spec_doc
    input_type: file
    requirement: required
    description: "Spec document to review"

When the task is created, Helix commits the attachment to the project's helix-specs branch (the same mechanism used for all spec-task attachments), then rewrites the {{ spec_doc }} placeholder from the bare filename to the absolute path inside the agent's workspace. The agent can read the file with its normal tool calls.

File inputs work for any file type the agent can consume: spec PDFs, markdown docs, CSVs, log dumps, screenshots.

Starter recipes

The Helix repository ships six ready-to-use recipes under examples/goose_recipes/:

They cover the full range of parameter types. Copy them into your repo at .goose/recipes/<name>.yaml, or reference them directly by attaching helixml/helix as a second repository and using recipe_repo_url:

spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true
    - url: "https://github.com/helixml/helix"
      branch: main
 
  agent:
    runtime: goose_code
    goose:
      recipe_repo_url: "https://github.com/helixml/helix"
      recipes:
        - name: release-notes
          path: examples/goose_recipes/release-notes.yaml
        - name: triage
          path: examples/goose_recipes/triage.yaml

Creating a spec task with a recipe

When you create a spec task against a Goose project that has recipes configured, the task creation form shows a Goose Recipe dropdown listing every declared recipe by name.

1. Pick a recipe from the dropdown. The parameter form for that recipe appears below it.
2. Fill in the required fields (and optionally override any optional defaults).
3. For file parameters, stage the file in the Attachments section first — it will appear in the file dropdown.
4. Submit the task.

Leave the dropdown on None (vanilla Goose) to run the agent without a baked recipe — it starts with only the project-level instructions, and all declared recipes are still available as slash commands inside the thread for interactive use.

Limits

• Recipes live in a git repository. Edit and version them with your normal review process; there is no in-Helix recipe editor.
• Parameter values are baked at session start. To change values, restart the session with a new spec task.
• A recipe_repo_url must be a repository already attached to the project — the URL is a key into spec.repositories, not a freestanding URL.
• If a declared recipe file is missing or malformed, Helix surfaces a warning in the project settings UI rather than failing the whole agent. The remaining recipes continue to work.