diff --git a/documentation/docs/guides/recipes/recipe-reference.md b/documentation/docs/guides/recipes/recipe-reference.md index 22a3677597c4..97935afcda89 100644 --- a/documentation/docs/guides/recipes/recipe-reference.md +++ b/documentation/docs/guides/recipes/recipe-reference.md @@ -1,239 +1,63 @@ --- sidebar_position: 2 title: Recipe Reference Guide +sidebar_label: Recipe Reference description: Complete technical reference for creating and customizing recipes in goose --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Recipes are reusable goose configurations that package up a specific setup so it can be easily shared and launched by others. +Recipes are reusable goose configurations that package up instructions and settings so the setup can be easily shared and launched by others. ## Recipe File Format -Recipes can be defined in either: -- `.yaml` files (recommended) -- `.json` files +Recipes can be defined in: +- `.yaml` (recommended) and `.yml` files +- `.json` files -See [Shareable Recipes](/docs/guides/recipes/session-recipes) to learn how to create, use, and manage recipes. - -### CLI and Desktop Formats - -goose recipes use two formats: - -- **CLI Format**: Recipe fields (like `title`, `description`, `instructions`) are at the root level of the YAML/JSON file. This format is used when recipes are created via the CLI `/recipe` command and [Recipe Generator](/recipe-generator) YAML option. -- **Desktop Format**: Recipe fields are nested inside a `recipe` object, with additional metadata fields at the root level. This format is used when recipes are created from goose Desktop. - -The CLI automatically detects and handles both formats for `.yaml` and `.json` recipe files when running `goose run --recipe ` and `goose recipe` commands. The Desktop can [import](/docs/guides/recipes/storing-recipes#importing-recipes) `.yaml`, `.yml`, and `.json` recipe files (or deeplinks) in either CLI or Desktop format. - -
-Format Examples - -Recipes can be written in either YAML or JSON format. Both formats follow the same schema structure. - -### CLI Format - - - - -```yaml -version: "1.0.0" -title: "Code Review Assistant" -description: "Automated code review with best practices" -instructions: "You are a code reviewer..." -prompt: "Review the code in this repository" -extensions: [] -``` - - - - -```json -{ - "version": "1.0.0", - "title": "Code Review Assistant", - "description": "Automated code review with best practices", - "instructions": "You are a code reviewer...", - "prompt": "Review the code in this repository", - "extensions": [] -} -``` - - - - -### Desktop Format - - - - -```yaml -name: "Code Review Assistant" -recipe: - version: "1.0.0" - title: "Code Review Assistant" - description: "Automated code review with best practices" - instructions: "You are a code reviewer..." - prompt: "Review the code in this repository" - extensions: [] -isGlobal: true -lastModified: 2025-07-02T03:46:46.778Z -isArchived: false -``` - - - - -```json -{ - "name": "Code Review Assistant", - "recipe": { - "version": "1.0.0", - "title": "Code Review Assistant", - "description": "Automated code review with best practices", - "instructions": "You are a code reviewer...", - "prompt": "Review the code in this repository", - "extensions": [] - }, - "isGlobal": true, - "lastModified": "2025-07-02T03:46:46.778Z", - "isArchived": false -} -``` - - - - -:::note -goose automatically adds metadata fields to recipes saved from the Desktop app. +:::info +`.yml` files aren't supported by goose CLI. ::: -
- -## Recipe Structure - -### Required Fields - -| Field | Type | Description | -|-------|------|-------------| -| `version` | String | The recipe format version (e.g., "1.0.0") | -| `title` | String | A short title describing the recipe | -| `description` | String | A detailed description of what the recipe does | - -### Optional Fields - -| Field | Type | Description | -|-------|------|-------------| -| `instructions` | String | Template instructions that can include parameter substitutions | -| `prompt` | String | A template prompt that can include parameter substitutions; required in headless (non-interactive) mode | -| [`parameters`](#parameters) | Array | List of parameter definitions | -| [`activities`](#activities) | Array | List of example prompts that appear as clickable bubbles in goose Desktop | -| [`extensions`](#extensions) | Array | List of extension configurations | -| [`settings`](#settings) | Object | Configuration for model provider, model name, and other settings | -| [`sub_recipes`](#subrecipes) | Array | List of subrecipes | -| [`response`](#structured-output-with-response) | Object | Structured output schema for automation workflows | -| [`retry`](#automated-retry-with-success-validation) | Object | Configuration for automated retry logic with success validation | - -### Desktop Format Metadata Fields - -When recipes are saved from goose Desktop, additional metadata fields are included at the top level (outside the `recipe` key). These fields are used by the Desktop app for organization and management but are ignored by CLI operations. - -| Field | Type | Description | -|-------|------|-------------| -| `name` | String | Display name used in Desktop Recipe Library | -| `isGlobal` | Boolean | Whether the recipe is available globally or locally to a project | -| `lastModified` | String | ISO timestamp of when the recipe was last modified | -| `isArchived` | Boolean | Whether the recipe is archived in the Desktop interface | - -## Parameters - -The `parameters` field allows you to create dynamic, reusable recipes that can be customized for different contexts. Parameters define placeholders that users fill in when running the recipe, making the recipe more flexible and adaptable. - -Parameter substitution uses Jinja-style template syntax with `{{ parameter_name }}` placeholders. Each parameter in the `parameters` array has the following structure: - -### Required Parameter Fields - -| Field | Type | Description | -|-------|------|-------------| -| `key` | String | Unique identifier for the parameter | -| `input_type` | String | Type of input: `"string"` (default), `"number"`, `"boolean"`, `"date"`, `"file"`, or `"select"` | -| `requirement` | String | One of: "required", "optional", or "user_prompt" | -| `description` | String | Human-readable description of the parameter | - -### Optional Parameter Fields - -| Field | Type | Description | -|-------|------|-------------| -| `default` | String | Default value for optional parameters | -| `options` | Array | List of available choices (required for `select` input type) | - -### Parameter Requirements - -- `required`: Parameter must be provided when using the recipe -- `optional`: Can be omitted if a default value is specified -- `user_prompt`: Will interactively prompt the user for input if not provided - -The `required` and `optional` parameters work best for recipes opened in goose Desktop. If a value isn't provided for a `user_prompt` parameter, the parameter won't be substituted and may appear as literal `{{ parameter_name }}` text in the recipe output. +See [Shareable Recipes](/docs/guides/recipes/session-recipes) to learn how to create, use, and manage recipes. -### Input Types +## Recipe Location -- `string`: Default type. The parameter value is used as-is in template substitution -- `number`: Numeric values. Desktop UI provides number input validation -- `boolean`: True/false values. Desktop UI shows dropdown with "True"/"False" options -- `date`: Date values. Currently renders as text input -- `file`: The parameter value should be a file path. goose reads the file contents and substitutes the actual content (not the path) into the template -- `select`: Dropdown selection with predefined options. Requires `options` field +Recipes can be loaded from: -**Example:** -```yaml -parameters: - - key: max_files - input_type: number - requirement: optional - default: 10 - description: "Maximum files to process" - - - key: output_format - input_type: select - requirement: required - description: "Choose output format" - options: - - json - - markdown - - csv - - - key: enable_debug - input_type: boolean - requirement: optional - default: false - description: "Enable debug mode" - - - key: source_code - input_type: file - requirement: required - description: "Path to the source code file to analyze" +1. Local filesystem: + - Current directory + - Directories specified in [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) environment variable + +2. GitHub repositories: + - Configure using [`GOOSE_RECIPE_GITHUB_REPO`](/docs/guides/environment-variables#recipe-configuration) configuration key + - Requires GitHub CLI (`gh`) to be installed and authenticated -prompt: "Process {{ max_files }} files in {{ output_format }} format. Debug: {{ enable_debug }}. Code:\n\n{{ source_code }}" -``` +## Core Recipe Schema -:::important -- Optional parameters MUST have a default value specified -- Required parameters cannot have default values -- File parameters cannot have default values regardless of requirement type to prevent unintended importing of sensitive files -- Select parameters MUST have an `options` field with available choices -- Parameter keys must match any template variables used in instructions, prompt, or activities -::: +Recipes follow this schema structure: -### Parameter Substitution in Desktop +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `description` | String | ✅ | A detailed description of what the recipe does | +| `instructions` | String | ✅* | Template instructions that can include parameter substitutions | +| `prompt` | String| ✅* | A template prompt that can include parameter substitutions. Required in [headless](/docs/tutorials/headless-goose) (non-interactive) mode. | +| `title` | String | ✅ | A short title describing the recipe | +| [`activities`](#activities) | Array | - | List of example prompts that can include parameter substitutions. Activities appear as clickable bubbles in goose Desktop. | +| [`extensions`](#extensions) | Array | - | List of extension configurations | +| [`parameters`](#parameters) | Array | - | List of parameter definitions for dynamic recipes | +| [`response`](#response) | Object | - | Structured output schema for automation workflows | +| [`retry`](#retry) | Object | - | Configuration for automated retry logic with success validation | +| [`settings`](#settings) | Object | - | Configuration for model provider, model name, and other settings | +| [`sub_recipes`](#subrecipes) | Array | - | List of subrecipes | +| `version` | String | - | The recipe format version, defaults to "1.0.0" if omitted | -When a recipe with parameters is opened in goose Desktop, users are presented with a **Recipe Parameters** dialog where they can: -- Provide values for required parameters -- Modify or accept default values for optional parameters -- Enter values for `user_prompt` parameters +*At least one of `instructions` or `prompt` must be provided. -Once parameter values are submitted, they are substituted into the recipe's `instructions`, `prompt`, and `activities` fields before the recipe starts. +## Field Specifications -## Activities +### Activities The `activities` field defines an optional message and clickable activity bubbles (buttons) that appears when a recipe is opened in goose Desktop. @@ -241,7 +65,7 @@ The `activities` field defines an optional message and clickable activity bubble Activities are a Desktop-only feature. When recipes with activities are run via the CLI or as a scheduled job, the `activities` field is ignored and has no effect on recipe execution. ::: -### Activity Types +#### Activity Types Activities can be defined in two ways: @@ -256,45 +80,80 @@ Activities can be defined in two ways: 2. **Button Activities**: Text to display in activity bubbles, which send the activity text as a prompt when clicked -### Parameter Substitution +#### Parameter Substitution Activities support [parameter substitution](#parameters), allowing you to create dynamic, personalized activity bubbles. After users provide parameter values in the **Recipe Parameters** dialog, the values are substituted into the activity text before the bubbles are displayed. -### Example Configuration +#### Example Configuration -```yaml -version: "1.0.0" -title: "Code Review Assistant" -description: "Review code with customizable focus areas" -parameters: - - key: language - input_type: string - requirement: required - description: "Programming language to review" - - key: focus - input_type: string - requirement: optional - default: "best practices" - description: "Review focus area" - -activities: - - "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}." - - "Review the current file for {{ focus }}" - - "Suggest improvements for {{ language }} code quality" - - "Check for security vulnerabilities" - - "Generate unit tests" -``` + + + ```yaml + version: "1.0.0" + title: "Code Review Assistant" + description: "Review code with customizable focus areas" + parameters: + - key: language + input_type: string + requirement: required + description: "Programming language to review" + - key: focus + input_type: string + requirement: optional + default: "best practices" + description: "Review focus area" + + activities: + - "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}." + - "Review the current file for {{ focus }}" + - "Suggest improvements for {{ language }} code quality" + - "Check for security vulnerabilities" + - "Generate unit tests" + ``` + + + ```json + { + "version": "1.0.0", + "title": "Code Review Assistant", + "description": "Review code with customizable focus areas", + "parameters": [ + { + "key": "language", + "input_type": "string", + "requirement": "required", + "description": "Programming language to review" + }, + { + "key": "focus", + "input_type": "string", + "requirement": "optional", + "default": "best practices", + "description": "Review focus area" + } + ], + "activities": [ + "message: Click an option below to start reviewing {{ language }} code with a focus on {{ focus }}.", + "Review the current file for {{ focus }}", + "Suggest improvements for {{ language }} code quality", + "Check for security vulnerabilities", + "Generate unit tests" + ] + } + ``` + + In this example: - The message activity displays instructions with substituted parameter values, for example: "Click an option below to start reviewing rust code with a focus on best practices." - The first two activity bubbles use parameter substitution, for example: "Review the current file for best practices" - The last two activity bubbles are static prompts that work regardless of parameters -## Extensions +### Extensions -The `extensions` field allows you to specify which Model Context Protocol (MCP) servers and other extensions the recipe needs to function. Each extension in the array has the following structure: +The `extensions` field allows you to specify which Model Context Protocol (MCP) servers and other extensions the recipe needs to function. Each extension in the `extensions` array has the following schema: -### Extension Fields +#### Extension Schema | Field | Type | Description | |-------|------|-------------| @@ -308,9 +167,19 @@ The `extensions` field allows you to specify which Model Context Protocol (MCP) | `description` | String | Description of what the extension does | | `available_tools` | Array | List of tool names within the extension that will be available. When not specified all will be available | -### Example Extension Configuration +#### Extension Types + +- **`stdio`**: Standard I/O client with command and arguments +- **`sse`**: Server-sent events client with a URI endpoint +- **`builtin`**: Built-in extension that is part of the bundled goose MCP server +- **`platform`**: Platform extensions that run in the agent process +- **`streamable_http`**: Streamable HTTP client with URI endpoint +- **`frontend`**: Frontend-provided tools called through the frontend +- **`inline_python`**: Inline Python code executed using uvx. Requires `code` field; optional `dependencies` for packages. + +#### Example Extensions Configuration - + ```yaml @@ -341,6 +210,17 @@ extensions: - GITHUB_PERSONAL_ACCESS_TOKEN timeout: 60 description: "GitHub MCP extension for repository operations" + + - type: inline_python + name: data_processor + code: | + import pandas as pd + print("Processing data...") + dependencies: + - pandas + - numpy + timeout: 120 + description: "Process data using pandas" ``` @@ -374,6 +254,14 @@ extensions: "env_keys": ["GITHUB_PERSONAL_ACCESS_TOKEN"], "timeout": 60, "description": "GitHub MCP extension for repository operations" + }, + { + "type": "inline_python", + "name": "data_processor", + "code": "import pandas as pd\nprint(\"Processing data...\")", + "dependencies": ["pandas", "numpy"], + "timeout": 120, + "description": "Process data using pandas" } ] } @@ -382,7 +270,7 @@ extensions: -### Extension Secrets +#### Extension Secrets This feature is only available through the CLI. @@ -400,89 +288,167 @@ This feature is designed to prompt for and securely store secrets (such as API k Users can press `ESC` to skip entering a variable if it's optional for the extension. ::: -## Settings +### Parameters -The `settings` field allows you to configure the AI model and provider settings for the recipe. This overrides the default configuration when the recipe is executed. +The `parameters` field allows you to create dynamic, reusable recipes that can be customized for different contexts. Parameters define placeholders that users fill in when running the recipe, making the recipe more flexible and adaptable. -### Settings Fields +Parameter substitution uses Jinja-style template syntax with `{{ parameter_name }}` placeholders. Each parameter in the `parameters` array has the following schema: -| Field | Type | Description | -|-------|------|-------------| -| `goose_provider` | String | (Optional) The AI provider to use (e.g., "anthropic", "openai") | -| `goose_model` | String | (Optional) The specific model name to use | -| `temperature` | Number | (Optional) The temperature setting for the model (typically 0.0-1.0) | +#### Parameter Schema + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `key` | String | ✅ | Unique identifier for the parameter | +| `input_type` | String | ✅ | Type of input: `"string"` (default), `"number"`, `"boolean"`, `"date"`, `"file"`, or `"select"` | +| `requirement` | String | ✅ | One of: "required", "optional", or "user_prompt" | +| `description` | String | ✅ | Human-readable description of the parameter | +| `default` | String | - | Default value for optional parameters | +| `options` | Array | - | List of available choices (required for `select` input type) | -### Example Settings Configuration +#### Parameter Requirements + +- `required`: Parameter must be provided when using the recipe +- `optional`: Can be omitted if a default value is specified +- `user_prompt`: Will interactively prompt the user for input if not provided + +The `required` and `optional` parameters work best for recipes opened in goose Desktop. If a value isn't provided for a `user_prompt` parameter, the parameter won't be substituted and may appear as literal `{{ parameter_name }}` text in the recipe output. + +#### Input Types + +- `string`: Default type. The parameter value is used as-is in template substitution +- `number`: Numeric values. Desktop UI provides number input validation +- `boolean`: True/false values. Desktop UI shows dropdown with "True"/"False" options +- `date`: Date values. Currently renders as text input +- `file`: The parameter value should be a file path. goose reads the file contents and substitutes the actual content (not the path) into the template +- `select`: Dropdown selection with predefined options. Requires `options` field +**Example:** ```yaml -settings: - goose_provider: "anthropic" - goose_model: "claude-sonnet-4-20250514" - temperature: 0.7 +parameters: + - key: max_files + input_type: number + requirement: optional + default: "10" + description: "Maximum files to process" + + - key: output_format + input_type: select + requirement: required + description: "Choose output format" + options: + - json + - markdown + - csv + + - key: enable_debug + input_type: boolean + requirement: optional + default: "false" + description: "Enable debug mode" + + - key: source_code + input_type: file + requirement: required + description: "Path to the source code file to analyze" + +prompt: "Process {{ max_files }} files in {{ output_format }} format. Debug: {{ enable_debug }}. Code:\n\n{{ source_code }}" ``` -```yaml -settings: - goose_provider: "openai" - goose_model: "gpt-4o" - temperature: 0.3 -``` +:::important +- Optional parameters MUST have a default value specified +- Required parameters cannot have default values +- File parameters cannot have default values regardless of requirement type to prevent unintended importing of sensitive files +- Select parameters MUST have an `options` field with available choices +- Parameter keys must match any template variables used in instructions, prompt, or activities +::: + +#### Parameter Substitution in Desktop + +When a recipe with parameters is opened in goose Desktop, users are presented with a **Recipe Parameters** dialog where they can: +- Provide values for required parameters +- Modify or accept default values for optional parameters +- Enter values for `user_prompt` parameters + +Once parameter values are submitted, they are substituted into the recipe's `instructions`, `prompt`, and `activities` fields before the recipe starts. + +### Response + +The `response` field enables recipes to enforce a final structured JSON output. When you specify a `json_schema`, goose will: -:::note -Settings specified in a recipe will override your default goose configuration when that recipe is executed. If no settings are specified, goose will use your configured defaults. -::: +1. **Validate the output**: Validates the output JSON against your JSON schema with basic JSON schema validations +2. **Final structured output**: Ensure the final output of the agent is a response matching your JSON structure -## Subrecipes +This feature is designed for **non-interactive automation** to ensure consistent, parseable output. Recipes can produce structured output when run from either the goose CLI or goose Desktop. See [use cases and ideas for automation workflows](/docs/guides/recipes/session-recipes#response). -The `sub_recipes` field specifies the [subrecipes](/docs/guides/recipes/subrecipes) that the main recipe calls to perform specific tasks. Each subrecipe in the array has the following structure: +#### Response Schema -### Subrecipe Fields +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `json_schema` | Object | ✅ | [JSON schema](https://json-schema.org/) for output validation | -| Field | Type | Description | -|-------|------|-------------| -| `name` | String | Unique identifier for the subrecipe | -| `path` | String | Relative or absolute path to the subrecipe file | -| `values` | Object | (Optional) Pre-configured parameter values that are passed to the subrecipe | -| `sequential_when_repeated` | Boolean | (Optional) Forces sequential execution of multiple subrecipe instances. See [Running Subrecipes In Parallel](/docs/tutorials/subrecipes-in-parallel) for details | +#### Basic Structure + +```yaml +response: + json_schema: + type: object + properties: + # Define your fields here, with their type and description + required: + # List required field names +``` -### Example Subrecipe Configuration +#### Simple Example ```yaml -sub_recipes: - - name: "security_scan" - path: "./subrecipes/security-analysis.yaml" - values: # in key-value format: {parameter_name}: {parameter_value} - scan_level: "comprehensive" - include_dependencies: "true" - - - name: "quality_check" - path: "./subrecipes/quality-analysis.yaml" +version: "1.0.0" +title: "Task Summary" +description: "Summarize completed tasks" +prompt: "Summarize the tasks you completed" +response: + json_schema: + type: object + properties: + summary: + type: string + description: "Brief summary of work done" + tasks_completed: + type: number + description: "Number of tasks finished" + next_steps: + type: array + items: + type: string + description: "Recommended next actions" + required: + - summary + - tasks_completed ``` -## Automated Retry with Success Validation +### Retry The `retry` field enables recipes to automatically retry execution if success criteria are not met. This is useful for recipes that might need multiple attempts to achieve their goal, or for implementing automated validation and recovery workflows. -### Retry Configuration Fields +#### Retry Schema -| Field | Type | Description | -|-------|------|-------------| -| `max_retries` | Number | Maximum number of retry attempts (required) | -| `timeout_seconds` | Number | (Optional) Timeout for success check commands (default: 300 seconds) | -| `on_failure_timeout_seconds` | Number | (Optional) Timeout for on_failure commands (default: 600 seconds) | -| `checks` | Array | List of success check configurations (required) | -| `on_failure` | String | (Optional) Shell command to run when a retry attempt fails | +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `max_retries` | Number | ✅ | Maximum number of retry attempts | +| `checks` | Array | ✅ | List of success check configurations | +| `timeout_seconds` | Number | - | Timeout for success check commands (default: 300 seconds) | +| `on_failure_timeout_seconds` | Number | - | Timeout for on_failure commands (default: 600 seconds) | +| `on_failure` | String | - | Shell command to run when a retry attempt fails | -### Success Check Configuration +#### Success Check Configuration -Each success check in the `checks` array has the following structure: +Each success check in the `checks` array has the following schema: -| Field | Type | Description | -|-------|------|-------------| -| `type` | String | Type of check - currently only "shell" is supported | -| `command` | String | Shell command to execute for validation (must exit with code 0 for success) | +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | String | ✅ | Type of check - currently only "shell" is supported | +| `command` | String | ✅ | Shell command to execute for validation (must exit with code 0 for success) | -### How Retry Logic Works +#### How Retry Logic Works 1. **Recipe Execution**: The recipe runs normally with the provided instructions 2. **Success Validation**: After completion, all success checks are executed in order @@ -494,7 +460,7 @@ Each success check in the `checks` array has the following structure: - All success checks pass (success) - Maximum retry attempts are reached (failure) -### Basic Retry Example +#### Basic Retry Example ```yaml version: "1.0.0" @@ -511,7 +477,7 @@ retry: on_failure: "echo 'Counter is at:' $(cat /tmp/counter.txt 2>/dev/null || echo 0) '(need 3 to succeed)'" ``` -### Advanced Retry Example +#### Advanced Retry Example ```yaml version: "1.0.0" @@ -531,7 +497,7 @@ retry: on_failure: "systemctl stop web-service || killall web-service" ``` -### Environment Variables +#### Environment Variables You can configure retry behavior globally using environment variables: @@ -540,57 +506,160 @@ You can configure retry behavior globally using environment variables: These environment variables are overridden by recipe-specific timeout configurations. -## Structured Output with `response` +### Settings -The `response` field enables recipes to enforce a final structured JSON output from goose. When you specify a `json_schema`, goose will: +The `settings` field allows you to configure the AI model and provider settings for the recipe. This overrides the default configuration when the recipe is executed. -1. **Validate the output**: Validates the output JSON against your JSON schema with basic JSON schema validations -2. **Final structured output**: Ensure the final output of the agent is a response matching your JSON structure +#### Settings Schema -This feature is designed for **non-interactive automation** to ensure consistent, parseable output. Recipes can produce structured output when run from either the goose CLI or goose Desktop. See [use cases and ideas for automation workflows](/docs/guides/recipes/session-recipes#structured-output-for-automation). +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `goose_provider` | String | - | The AI provider to use (e.g., "anthropic", "openai") | +| `goose_model` | String | - | The specific model name to use | +| `temperature` | Number | - | The temperature setting for the model (typically 0.0-1.0) | -### Basic Structure +#### Example Settings Configuration ```yaml -response: - json_schema: - type: object - properties: - # Define your fields here, with their type and description - required: - # List required field names +settings: + goose_provider: "anthropic" + goose_model: "claude-sonnet-4-20250514" + temperature: 0.7 +``` + +```yaml +settings: + goose_provider: "openai" + goose_model: "gpt-4o" + temperature: 0.3 +``` + +:::note +Settings specified in a recipe will override your default goose configuration when that recipe is executed. If no settings are specified, goose will use your configured defaults. +::: + +### Subrecipes + +The `sub_recipes` field specifies the [subrecipes](/docs/guides/recipes/subrecipes) that the main recipe calls to perform specific tasks. Each subrecipe in the `sub_recipes` array has the following schema: + +#### Subrecipe Schema + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | String | ✅ | Unique identifier for the subrecipe | +| `path` | String | ✅ | Relative or absolute path to the subrecipe file | +| `values` | Object | - | Pre-configured parameter values that are passed to the subrecipe | +| `sequential_when_repeated` | Boolean | - | Forces sequential execution of multiple subrecipe instances. See [Running Subrecipes In Parallel](/docs/tutorials/subrecipes-in-parallel) for details | +| `description` | String | - | Optional description of the subrecipe | + +#### Example Subrecipe Configuration + +```yaml +sub_recipes: + - name: "security_scan" + path: "./subrecipes/security-analysis.yaml" + values: # in key-value format: {parameter_name}: {parameter_value} + scan_level: "comprehensive" + include_dependencies: "true" + + - name: "quality_check" + path: "./subrecipes/quality-analysis.yaml" + description: "Performs code quality analysis" ``` -### Simple Example +## Desktop Metadata Fields + +Recipes saved from goose Desktop include additional metadata fields. These fields are used by the Desktop app for organization and management but are ignored by CLI operations. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `recipe` | Object | ✅ | Contains all recipe fields (`title`, `description`, `instructions`, etc.) | +| `name` | String | ✅ | Display name used in Recipe Library | +| `isGlobal` | Boolean | ✅ | Whether the recipe is available globally or locally to a project | +| `lastModified` | String | ✅ | ISO timestamp of when the recipe was last modified | +| `isArchived` | Boolean | ✅ | Whether the recipe is archived in the Desktop interface | + +
+CLI and Desktop Format Examples + +**CLI Format** + + + ```yaml version: "1.0.0" -title: "Task Summary" -description: "Summarize completed tasks" -prompt: "Summarize the tasks you completed" -response: - json_schema: - type: object - properties: - summary: - type: string - description: "Brief summary of work done" - tasks_completed: - type: number - description: "Number of tasks finished" - next_steps: - type: array - items: - type: string - description: "Recommended next actions" - required: - - summary - - tasks_completed +title: "Code Review Assistant" +description: "Automated code review with best practices" +instructions: "You are a code reviewer..." +prompt: "Review the code in this repository" +extensions: [] +``` + + + + +```json +{ + "version": "1.0.0", + "title": "Code Review Assistant", + "description": "Automated code review with best practices", + "instructions": "You are a code reviewer...", + "prompt": "Review the code in this repository", + "extensions": [] +} +``` + + + + +**Desktop Format** + + + + +```yaml +name: "Code Review Assistant" +recipe: + version: "1.0.0" + title: "Code Review Assistant" + description: "Automated code review with best practices" + instructions: "You are a code reviewer..." + prompt: "Review the code in this repository" + extensions: [] +isGlobal: true +lastModified: 2025-07-02T03:46:46.778Z +isArchived: false +``` + + + + +```json +{ + "name": "Code Review Assistant", + "recipe": { + "version": "1.0.0", + "title": "Code Review Assistant", + "description": "Automated code review with best practices", + "instructions": "You are a code reviewer...", + "prompt": "Review the code in this repository", + "extensions": [] + }, + "isGlobal": true, + "lastModified": "2025-07-02T03:46:46.778Z", + "isArchived": false +} ``` + + + +
+ ## Template Support -Recipes support Jinja-style template syntax in `instructions`, `prompt`, and `activities` fields: +Recipes support Jinja-style template syntax in `instructions`, `prompt`, and `activities` fields for parameter substitution: ```yaml instructions: "Follow these steps with {{ parameter_name }}" @@ -600,14 +669,37 @@ activities: ``` Advanced template features include: -- Template inheritance using `{% extends "parent.yaml" %}` +- [Template inheritance](#template-inheritance) using `{% extends "parent.yaml" %}` - Blocks that can be defined and overridden: ```yaml {% block content %} Default content {% endblock %} ``` -- `indent()` template filter +- [`indent()` template filter](#indent-filter-for-multi-line-values) + +### Template Inheritance + +Use `{% extends "parent.yaml" %}` for template inheritance: + +**Parent recipe (`parent.yaml`):** +```yaml +version: "1.0.0" +title: "Parent Recipe" +description: "Base recipe template" +prompt: | + {% block prompt %} + Default prompt text + {% endblock %} +``` + +**Child recipe:** +```yaml +{% extends "parent.yaml" %} +{% block prompt %} +Modified prompt text +{% endblock %} +``` ### indent() Filter For Multi-Line Values @@ -622,15 +714,36 @@ sub_recipes: {{ raw_data | indent(2) }} ``` -## Built-in Parameters +### Built-in Parameters + +Built-in template parameters are automatically supported and don't need to be defined in the `parameters` array. | Parameter | Description | |-----------|-------------| -| `recipe_dir` | Automatically set to the directory containing the recipe file | +| `recipe_dir` | Automatically set to the directory containing the recipe file. Use it to reference companion files, for example: `{{ recipe_dir }}/style-guide.md` | + +## Validation Rules + +Validation rules from [`validate_recipe.rs`](https://github.com/block/goose/blob/main/crates/goose/src/recipe/validate_recipe.rs) are enforced when loading recipes and used by the [`goose recipe validate`](/docs/guides/goose-cli-commands#recipe) subcommand: + +### Recipe-Level Validation + +- `validate_prompt_or_instructions` - At least one of `instructions` or `prompt` must be present +- `validate_json_schema` - JSON response schema must be valid if `response.json_schema` is specified + +### Parameter Validation + +- `validate_parameters_in_template` - All template variables must have corresponding parameter definitions, and all defined parameters must be used (no unused parameters) +- `validate_optional_parameters` - Optional parameters must have default values +- `validate_optional_parameters` - File parameters cannot have default values to prevent importing sensitive files + +:::info +Basic field requirements (required fields, types, character limits) are documented in the [Core Recipe Schema](#core-recipe-schema) table. +::: ## Complete Recipe Example - + ```yaml @@ -795,52 +908,6 @@ response: -## Template Inheritance - -Parent recipe (`parent.yaml`): -```yaml -version: "1.0.0" -title: "Parent Recipe" -description: "Base recipe template" -prompt: | - {% block prompt %} - Default prompt text - {% endblock %} -``` - -Child recipe: -```yaml -{% extends "parent.yaml" %} -{% block prompt %} -Modified prompt text -{% endblock %} -``` - -## Recipe Location - -Recipes can be loaded from: - -1. Local filesystem: - - Current directory - - Directories specified in [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) environment variable - -2. GitHub repositories: - - Configure using [`GOOSE_RECIPE_GITHUB_REPO`](/docs/guides/environment-variables#recipe-configuration) configuration key - - Requires GitHub CLI (`gh`) to be installed and authenticated - -## Validation Rules - -Recipe files must be valid YAML or JSON. In addition, the following [validation rules](https://github.com/block/goose/blob/main/crates/goose/src/recipe/validate_recipe.rs) are enforced when loading recipes and are also checked by the [`goose recipe validate` subcommand](/docs/guides/goose-cli-commands#recipe): - -- Required `title` and `description` fields must be present -- At least one of `instructions` or `prompt` must be present -- All template variables must have corresponding parameter definitions -- Parameter keys must be unique (not enforced, but required for proper functionality) -- All defined parameters must be used in template variables (no unused parameters) -- Optional parameters must have default values -- File parameters cannot have default values (prevents importing sensitive files) -- `response.json_schema` must be a valid JSON schema if specified - ## Error Handling Common errors to watch for: diff --git a/documentation/docs/guides/recipes/session-recipes.md b/documentation/docs/guides/recipes/session-recipes.md index 444b071339dd..2cbe0f633509 100644 --- a/documentation/docs/guides/recipes/session-recipes.md +++ b/documentation/docs/guides/recipes/session-recipes.md @@ -588,11 +588,11 @@ retry: - Recipe execution starts over 4. Process continues until either success or max retries reached -See the [Recipe Reference Guide](/docs/guides/recipes/recipe-reference#automated-retry-with-success-validation) for complete retry configuration options and examples. +See the [Recipe Reference Guide](/docs/guides/recipes/recipe-reference#retry) for complete retry configuration options and examples. ### Structured Output for Automation -Recipes can enforce [structured JSON output](/docs/guides/recipes/recipe-reference#structured-output-with-response), making them ideal for automation workflows that need to parse and process agent responses reliably. Key benefits include: +Recipes can enforce [structured JSON output](/docs/guides/recipes/recipe-reference#response), making them ideal for automation workflows that need to parse and process agent responses reliably. Key benefits include: - **Reliable parsing**: Consistent JSON format for scripts, automation, and CI/CD pipelines - **Built-in validation**: Ensures output matches your requirements