aljaz/goose
1
0
Fork 0
mirror of https://github.com/aljazceru/goose.git synced 2025-12-17 14:14:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: add sub-recipes topic (#3241)

Browse Source 
Co-authored-by: Rizel Scarlett <rizel@squareup.com>
This commit is contained in:
dianed-square
2025-07-08 14:14:41 -07:00
committed by GitHub
parent f02be09fbb
commit 011a03d2b2
4 changed files with 328 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
documentation/docs/guides/recipes/index.md
View File

@@ -42,6 +42,11 @@ import styles from '@site/src/components/Card/styles.module.css';
description="Learn how to create and use Goose recipes with prompts, parameters, MCP servers, and more."
link="/docs/tutorials/recipes-tutorial"
/>
<Card
title="Sub-Recipes"
description="Learn how a recipe can use sub-recipes to do specific tasks."
link="/docs/guides/recipes/sub-recipes"
/>
</div>
</div>

27
documentation/docs/guides/recipes/recipe-reference.md
View File

@@ -36,6 +36,7 @@ After creating recipe files, you can use [`goose` CLI commands](/docs/guides/goo
| `prompt` | String | A template prompt that can include parameter substitutions; required in headless (non-interactive) mode |
| `parameters` | Array | List of parameter definitions |
| `extensions` | Array | List of extension configurations |
| `sub_recipes` | Array | List of sub-recipes |
| `response` | Object | Configuration for structured output validation |
## Parameters
@@ -107,6 +108,32 @@ extensions:
description: "For searching logs using Presidio"
```
## Sub-Recipes
The `sub_recipes` field specifies the [sub-recipes](/docs/guides/recipes/sub-recipes) that the main recipe calls to perform specific tasks. Each sub-recipe in the array has the following structure:
### Sub-Recipe Fields
| Field | Type | Description |
|-------|------|-------------|
| `name` | String | Unique identifier for the sub-recipe |
| `path` | String | Relative or absolute path to the sub-recipe file |
| `values` | Object | (Optional) Pre-configured parameter values that are passed to the sub-recipe |
### Example Sub-Recipe Configuration
```yaml
sub_recipes:
- name: "security_scan"
path: "./sub-recipes/security-analysis.yaml"
values: # in key-value format: {parameter_name}: {parameter_value}
scan_level: "comprehensive"
include_dependencies: "true"
- name: "quality_check"
path: "./sub-recipes/quality-analysis.yaml"
```
## Structured Output with `response`
The `response` field enables recipes to enforce a final structured JSON output from Goose. When you specify a `json_schema`, Goose will:

2
documentation/docs/guides/recipes/session-recipes.md
View File

@@ -68,6 +68,8 @@ You can turn your current Goose session into a reusable recipe that includes the
```
</details>
For detailed descriptions and example configurations of all recipe fields, see the [Recipe Reference Guide](/docs/guides/recipes/recipe-reference).
:::warning
You cannot create a recipe from an existing recipe session - the `/recipe` command will not work.
:::

294
documentation/docs/guides/recipes/sub-recipes.md Normal file
View File

@@ -0,0 +1,294 @@
---
sidebar_position: 3
title: Sub-Recipes For Specialized Tasks
sidebar_label: Sub-Recipes
description: Learn how a recipe can use sub-recipes to perform specific tasks
---
Sub-recipes are recipes that are used by another recipe to perform specific tasks. They enable:
- **Multi-step workflows** - Break complex tasks into distinct phases with specialized expertise
- **Reusable components** - Create common tasks that can be used in various workflows
## How Sub-Recipes Work
The "main recipe" registers its sub-recipes in the `sub_recipes` field, which contains the following fields:
- `name`: Unique identifier for the sub-recipe, used to generate the tool name
- `path`: File path to the sub-recipe file (relative or absolute)
- `values`: (Optional) Pre-configured parameter values that are always passed to the sub-recipe
When the main recipe is run, Goose generates a tool for each sub-recipe that:
- Accepts parameters defined by the sub-recipe
- Executes the sub-recipe in a separate session with its own context
- Returns output to the main recipe
Sub-recipe sessions run in isolation - they don't share conversation history, memory, or state with the main recipe or other sub-recipes. Additionally, sub-recipes cannot define their own sub-recipes (no nesting allowed).
### Parameter Handling
Sub-recipes receive parameters in two ways:
1. **Pre-set values**: Fixed parameter values defined in the `values` field are automatically provided and cannot be overridden at runtime
2. **Automatic parameter inheritance**: Sub-recipes automatically have access to all parameters passed to the main recipe at runtime.
Pre-set values take precedence over inherited parameters. If both the main recipe and `values` field provide the same parameter, the `values` version is used.
:::info Template Variables
Parameters received by sub-recipes can be used in prompts and instructions using `{{ parameter_name }}` syntax.
:::
## Examples
### Sequential Processing
This Code Review Pipeline example shows a main recipe that uses two sub-recipes to perform a comprehensive code review:
**Usage:**
```bash
goose run --recipe code-review-pipeline.yaml --params repository_path=/path/to/repo
```
**Main Recipe:**
```yaml
# code-review-pipeline.yaml
version: "1.0.0"
title: "Code Review Pipeline"
description: "Automated code review using sub-recipes"
instructions: |
Perform a code review using the available sub-recipe tools.
Run security analysis first, then code quality analysis.
parameters:
- key: repository_path
input_type: string
requirement: required
description: "Path to the repository to review"
sub_recipes:
- name: "security_scan"
path: "./sub-recipes/security-analysis.yaml"
values:
scan_level: "comprehensive"
- name: "quality_check"
path: "./sub-recipes/quality-analysis.yaml"
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Review the code at {{ repository_path }} using the sub-recipe tools.
Run security scan first, then quality analysis.
```
**Sub-Recipes:**
<details>
<summary>security_scan</summary>
```yaml
# sub-recipes/security-analysis.yaml
version: "1.0.0"
title: "Security Scanner"
description: "Analyze code for security vulnerabilities"
instructions: |
You are a security expert. Analyze the provided code for security issues.
Focus on common vulnerabilities like SQL injection, XSS, and authentication flaws.
parameters:
- key: repository_path
input_type: string
requirement: required
description: "Path to the code to analyze"
- key: scan_level
input_type: string
requirement: optional
default: "standard"
description: "Depth of security scan (basic, standard, comprehensive)"
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Perform a {{ scan_level }} security analysis on the code at {{ repository_path }}.
Report any security vulnerabilities found with severity levels and recommendations.
```
</details>
<details>
<summary>quality_check</summary>
```yaml
# sub-recipes/quality-analysis.yaml
version: "1.0.0"
title: "Code Quality Analyzer"
description: "Analyze code quality and best practices"
instructions: |
You are a code quality expert. Review code for maintainability,
readability, and adherence to best practices.
parameters:
- key: repository_path
input_type: string
requirement: required
description: "Path to the code to analyze"
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Analyze the code quality at {{ repository_path }}.
Check for code smells, complexity issues, and suggest improvements.
```
</details>
### Conditional Processing
This Smart Project Analyzer example shows conditional logic that chooses between different sub-recipes based on analysis:
**Usage:**
```bash
goose run --recipe smart-analyzer.yaml --params repository_path=/path/to/project
```
**Main Recipe:**
```yaml
# smart-analyzer.yaml
version: "1.0.0"
title: "Smart Project Analyzer"
description: "Analyze project and choose appropriate processing based on type"
instructions: |
First examine the repository to determine the project type (web app, CLI tool, library, etc.).
Based on what you find:
- If it's a web application, use the web_security_audit sub-recipe
- If it's a CLI tool or library, use the api_documentation sub-recipe
Only run one sub-recipe based on your analysis.
parameters:
- key: repository_path
input_type: string
requirement: required
description: "Path to the repository to analyze"
sub_recipes:
- name: "web_security_audit"
path: "./sub-recipes/web-security.yaml"
values:
check_cors: "true"
check_csrf: "true"
- name: "api_documentation"
path: "./sub-recipes/api-docs.yaml"
values:
format: "markdown"
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Analyze the project at {{ repository_path }} and determine its type.
Then run the appropriate sub-recipe tool based on your findings.
```
**Sub-Recipes:**
<details>
<summary>web_security_audit</summary>
```yaml
# sub-recipes/web-security.yaml
version: "1.0.0"
title: "Web Security Auditor"
description: "Security audit for web applications"
instructions: |
You are a web security specialist. Audit web applications for
security vulnerabilities specific to web technologies.
parameters:
- key: repository_path
input_type: string
requirement: required
description: "Path to the web application code"
- key: check_cors
input_type: string
requirement: optional
default: "false"
description: "Whether to check CORS configuration"
- key: check_csrf
input_type: string
requirement: optional
default: "false"
description: "Whether to check CSRF protection"
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Perform a web security audit on {{ repository_path }}.
{% if check_cors == "true" %}Check CORS configuration for security issues.{% endif %}
{% if check_csrf == "true" %}Verify CSRF protection is properly implemented.{% endif %}
Focus on web-specific vulnerabilities like XSS, authentication flaws, and session management.
```
</details>
<details>
<summary>api_documentation</summary>
```yaml
# sub-recipes/api-docs.yaml
version: "1.0.0"
title: "API Documentation Generator"
description: "Generate documentation for APIs and libraries"
instructions: |
You are a technical writer specializing in API documentation.
Create comprehensive documentation for code libraries and APIs.
parameters:
- key: repository_path
input_type: string
requirement: required
description: "Path to the code to document"
- key: format
input_type: string
requirement: optional
default: "markdown"
description: "Output format for documentation (markdown, html, rst)"
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Generate {{ format }} documentation for the code at {{ repository_path }}.
Include API endpoints, function signatures, usage examples, and installation instructions.
Focus on making it easy for developers to understand and use this code.
```
</details>
## Best Practices
- **Single responsibility**: Each sub-recipe should have one clear purpose
- **Clear parameters**: Use descriptive names and descriptions
- **Pre-set fixed values**: Use `values` for parameters that don't change
- **Test independently**: Verify sub-recipes work alone before combining
## Learn More
Check out the [Goose Recipes](/docs/guides/recipes) guide for more docs, tools, and resources to help you master Goose recipes.