diff --git a/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md b/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md index 4cc6e54f3e75..cac82f308d6c 100644 --- a/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md +++ b/documentation/blog/2025-07-28-streamlining-detection-development-with-goose-recipes/index.md @@ -9,7 +9,7 @@ authors: Creating effective security detections in Panther traditionally requires deep knowledge of detection logic, testing frameworks, and development workflows. The detection engineering team at Block has streamlined this process by building Goose recipes that automate the entire detection creation lifecycle from initial repository setup to pull request creation. -This blog post explores how to leverage Goose's [recipe](https://block.github.io/goose/docs/guides/recipes/) and [sub-recipe](https://block.github.io/goose/docs/guides/recipes/sub-recipes) system to create new detections in Panther with minimal manual intervention, ensuring consistency, quality, and adherence to team standards. +This blog post explores how to leverage Goose's [recipe](https://block.github.io/goose/docs/guides/recipes/) and [subrecipe](https://block.github.io/goose/docs/guides/recipes/subrecipes) system to create new detections in Panther with minimal manual intervention, ensuring consistency, quality, and adherence to team standards. @@ -60,7 +60,7 @@ prompt: | -The detection creation recipe demonstrates the power of this approach by coordinating six specialized sub-recipes, each handling a specific aspect of detection development: +The detection creation recipe demonstrates the power of this approach by coordinating six specialized subrecipes, each handling a specific aspect of detection development: 1. [**workflow_setup**](#1-workflow_setup-foundation-first) - Repository preparation and environment validation 2. [**similar_rule_analyzer**](#2-similar_rule_analyzer-learning-from-existing-patterns) - Finding and analyzing existing detection patterns @@ -88,22 +88,22 @@ This centralized approach through `AGENTS.md` becomes the foundation for our rec ## The Architecture ### Design Principles -1. **Single Responsibility**: Each sub-recipe has one clear job +1. **Single Responsibility**: Each subrecipe has one clear job 2. **Explicit Data Flow**: No hidden state or implicit dependencies 3. **Fail-Fast**: Stop immediately when critical steps fail 4. **Graceful Degradation**: Continue with reduced functionality when possible 5. **Comprehensive Testing**: Validate everything before deployment -### Why Sub-Recipes Matter +### Why Subrecipes Matter The traditional approach to AI-assisted detection creation often involves a single, monolithic prompt (AKA “single-shot prompting”) that tries to handle everything at once. This leads to several problems: - **Context confusion**: The AI loses focus when juggling multiple responsibilities -- **Inconsistent outputs**: Without clear boundaries, results vary significantly (e.g. one sub-recipe may try to complete the task that we're expecting another sub-recipe to accomplish) +- **Inconsistent outputs**: Without clear boundaries, results vary significantly (e.g. one subrecipe may try to complete the task that we're expecting another subrecipe to accomplish) - **Difficult debugging**: When something fails, it's hard to identify the specific issue - **Poor maintainability**: Changes to one aspect affect the entire workflow -The sub-recipe architecture solves these problems through strict separation of concerns, setting boundaries and providing exit criteria. +The subrecipe architecture solves these problems through strict separation of concerns, setting boundaries and providing exit criteria. -Each sub-recipe operates in isolation with: +Each subrecipe operates in isolation with: - Clearly defined inputs and outputs - Specific scope boundaries (what it MUST and MUST NOT do) - Standardized JSON response schemas @@ -130,7 +130,7 @@ Workflow visualized ## Data Flow and State Management -Since sub-recipes currently run in isolation, data must be explicitly passed between them. The main recipe orchestrates this flow: +Since subrecipes currently run in isolation, data must be explicitly passed between them. The main recipe orchestrates this flow: Example of how this would be defined in the recipe: ``` @@ -192,7 +192,7 @@ The workflow makes intelligent decisions based on results from previous steps: - skip_panther_mcp: Controls schema_and_sample_events_analyzer execution - create_pr: Controls pr_creator execution -# Runtime conditions (based on sub-recipe results): +# Runtime conditions (based on subrecipe results): - schema_and_sample_events_analyzer runs only if: * skip_panther_mcp is false AND * (similar_rules_found is empty OR mcp_panther.access_test_successful is false) @@ -223,13 +223,13 @@ Additionally, Jinja support enables the codification of event triggers, ensuring {% endif %} ``` -## Deep Dive: Key Sub-Recipes +## Deep Dive: Key Subrecipes ### 1. `workflow_setup`: Foundation First |Input | Output --- | --- `rule_description` | `branch_name`, `standards_summary`, `repo_ready`, `mcp_panther` -This sub-recipe handles all the foundational work: +This subrecipe handles all the foundational work: **Key responsibilities**: - Repository access verification @@ -256,7 +256,7 @@ Input | Output --- | --- `rule_description`, `standards_summary`, `rule_type` | `similar_rules_found`, `rule_analysis`, `suggested_approach` -This sub-recipe searches the repository for similar detection patterns: +This subrecipe searches the repository for similar detection patterns: ``` # Search strategy by rule type: @@ -281,7 +281,7 @@ Input | Output --- | --- `rule_description`, `similar_rules_found` | `log_schemas`, `example_logs`, `field_mapping`, `panther_mcp_usage` -This sub-recipe bridges the gap between detection requirements and implementation by leveraging Panther's MCP integration: +This subrecipe bridges the gap between detection requirements and implementation by leveraging Panther's MCP integration: **Key responsibilities**: - Log schema analysis using Panther MCP @@ -326,7 +326,7 @@ Input | Output --- | --- `rule_description`, `similar_rules_found`, `rule_analysis`, `log_schemas`, `standards_summary` | `rule_files_created`, `rule_implementation`, `test_cases_created` -This is where the magic happens - this sub-recipe generates the required files containing the detection logic, metadata and unit tests. +This is where the magic happens - this subrecipe generates the required files containing the detection logic, metadata and unit tests. **Smart log source validation**: - If schema analysis ran successfully → Use validated log types @@ -374,7 +374,7 @@ Input | Output --- | --- `rule_files_created` | `test_results`, `validation_status`, `issues_found` -This sub-recipe serves as the critical quality gate, executing the mandatory testing pipeline that ensures every detection meets production standards. +This subrecipe serves as the critical quality gate, executing the mandatory testing pipeline that ensures every detection meets production standards. **Key responsibilities**: - Execute all mandatory testing commands from `AGENTS.md` (e.g. linting, formatting and both unit and pytests) @@ -384,7 +384,7 @@ This sub-recipe serves as the critical quality gate, executing the mandatory tes These checks ensure detections meet our standards, preventing subpar code from being merged. Should a check fail, the LLM will iterate, identifying and implementing necessary changes until compliance is achieved as part of the same recipe run. -**Intelligent failure analysis**: The sub-recipe doesn't just run tests - it analyzes failures and provides specific guidance: +**Intelligent failure analysis**: The subrecipe doesn't just run tests - it analyzes failures and provides specific guidance: ```json { "test_results": { @@ -429,7 +429,7 @@ Input | Output --- | --- `rule_files_created`, `rule_description`, `branch_name`, `create_pr`, `panther_mcp_usage` | `pr_created`, `pr_url`, `pr_number`, `summary` -This sub-recipe handles the final workflow step with full adherence to team standards: +This subrecipe handles the final workflow step with full adherence to team standards: **Key responsibilities**: - Git branch management and commits @@ -461,13 +461,13 @@ This sub-recipe handles the final workflow step with full adherence to team stan } ``` -_Quality assurance_: This sub-recipe includes comprehensive error handling for git failures, PR creation issues, and template population problems, providing clear fallback instructions when automation fails. +_Quality assurance_: This subrecipe includes comprehensive error handling for git failures, PR creation issues, and template population problems, providing clear fallback instructions when automation fails. ## Error Handling and Fail-Fast Design This workflow implements sophisticated error handling with intelligent stopping points: ### Standardized Response Schema -Every sub-recipe uses a consistent JSON response format: +Every subrecipe uses a consistent JSON response format: ```json { "status": { @@ -481,7 +481,7 @@ Every sub-recipe uses a consistent JSON response format: ``` ### Failures -This workflow distinguishes between different types of failures. For example, each sub-recipe’s response has an `error_code` field. When a failure occurs, the LLM categorizes the type of error encountered and surfaces this information to the main recipe so it can make a determination on what to do next. +This workflow distinguishes between different types of failures. For example, each subrecipe’s response has an `error_code` field. When a failure occurs, the LLM categorizes the type of error encountered and surfaces this information to the main recipe so it can make a determination on what to do next. As an example, `rule_creator` is configured with these error categories: ``` @@ -500,7 +500,7 @@ response: ... ``` -If this sub-recipe returns `file_creation_failed`, we shouldn’t move on to the `testing_validator` or `pr_creator` steps. +If this subrecipe returns `file_creation_failed`, we shouldn’t move on to the `testing_validator` or `pr_creator` steps. This fail-fast approach prevents wasted effort on meaningless subsequent steps. @@ -528,7 +528,7 @@ goose run --recipe recipe.yaml --interactive \ The recipe system ensures compliance with team standards through: ### Automated Standards Extraction -The `workflow_setup` sub-recipe extracts key requirements from `AGENTS.md`: +The `workflow_setup` subrecipe extracts key requirements from `AGENTS.md`: - File naming conventions (`ai_` prefix for AI-created rules) - Required Python functions and error handling patterns - Testing requirements and validation commands @@ -542,7 +542,7 @@ The `workflow_setup` sub-recipe extracts key requirements from `AGENTS.md`: - **Consistency**: Standardized file structures and naming ### Pull Request Automation -The `pr_creator` sub-recipe follows team standards: +The `pr_creator` subrecipe follows team standards: - Proper branch naming (e.g. `ai/`) - Template-based PR descriptions - Draft mode for review @@ -575,7 +575,7 @@ For Organizations - **Compliance**: Adherence to security and development standards ## Conclusion -Goose's recipe and sub-recipe system represents a significant advancement in AI-assisted security detection development. By breaking complex workflows into specialized, composable components, teams can achieve: +Goose's recipe and subrecipe system represents a significant advancement in AI-assisted security detection development. By breaking complex workflows into specialized, composable components, teams can achieve: - **Higher quality detections** through automated testing and validation - **Faster development cycles** with intelligent optimization - **Better consistency** through standardized processes diff --git a/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md b/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md index 3f28f0519aaa..3d9aadb43186 100644 --- a/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md +++ b/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md @@ -1,6 +1,6 @@ --- title: "How PulseMCP Automated Their Newsletter Workflow with Goose" -description: PulseMCP used Goose recipes, subagents, and sub-recipes to automate the boring parts of their newsletter workflow +description: PulseMCP used Goose recipes, subagents, and subrecipes to automate the boring parts of their newsletter workflow authors: - rizel --- @@ -21,7 +21,7 @@ Every week, the PulseMCP team faced the same time-consuming workflow: sourcing r ## The Solution: Why Sequential Beats Monolithic -Instead of building one massive "do-everything" agent (which inevitably fails on complex tasks), PulseMCP broke their workflow into six distinct phases. Each phase gets handled by focused [recipes](/docs/guides/recipes/session-recipes), [sub-recipes](/docs/guides/recipes/sub-recipes) and [subagents](/docs/experimental/subagents) with clear inputs, outputs, and a single job. +Instead of building one massive "do-everything" agent (which inevitably fails on complex tasks), PulseMCP broke their workflow into six distinct phases. Each phase gets handled by focused [recipes](/docs/guides/recipes/session-recipes), [subrecipes](/docs/guides/recipes/subrecipes) and [subagents](/docs/experimental/subagents) with clear inputs, outputs, and a single job. This approach has three main benefits: debugging becomes easier when agents have single responsibilities, results become more predictable with clear handoffs between stages, and humans stay in control of the editorial process while automating the tedious work. @@ -81,11 +81,11 @@ The PulseMCP implementation proves we're past the demo phase of AI agents. Real - + - + \ No newline at end of file diff --git a/documentation/blog/2025-08-18-understanding-context-windows/index.md b/documentation/blog/2025-08-18-understanding-context-windows/index.md index 171d471f4142..4ed2107e5e72 100644 --- a/documentation/blog/2025-08-18-understanding-context-windows/index.md +++ b/documentation/blog/2025-08-18-understanding-context-windows/index.md @@ -77,7 +77,7 @@ The [Memory extension](https://block.github.io/goose/docs/mcp/memory-mcp) stores **4. Recipes** -[Recipes](https://block.github.io/goose/docs/guides/recipes/) package complete task setups into reusable configurations, eliminating the need to provide lengthy instructions repeatedly. Instead of consuming tokens explaining complex workflows in every session, recipes contain all necessary instructions, extensions, and parameters upfront. This is particularly valuable for repetitive tasks where you'd otherwise spend significant tokens on setup and explanation. And if your recipe starts to feel overly lengthy, you can break the tasks up into [sub-recipes](https://block.github.io/goose/docs/guides/recipes/sub-recipes). +[Recipes](https://block.github.io/goose/docs/guides/recipes/) package complete task setups into reusable configurations, eliminating the need to provide lengthy instructions repeatedly. Instead of consuming tokens explaining complex workflows in every session, recipes contain all necessary instructions, extensions, and parameters upfront. This is particularly valuable for repetitive tasks where you'd otherwise spend significant tokens on setup and explanation. And if your recipe starts to feel overly lengthy, you can break the tasks up into [subrecipes](https://block.github.io/goose/docs/guides/recipes/subrecipes). **5. Subagents** diff --git a/documentation/blog/2025-09-15-subrecipes-in-goose/index.md b/documentation/blog/2025-09-15-subrecipes-in-goose/index.md index 38e0e9d0b4af..533f82918213 100644 --- a/documentation/blog/2025-09-15-subrecipes-in-goose/index.md +++ b/documentation/blog/2025-09-15-subrecipes-in-goose/index.md @@ -9,7 +9,7 @@ authors: Remember when you first learned to cook? You probably started with simple recipes like scrambled eggs or toast. But eventually you wanted to make something more complex, like a full dinner with multiple dishes. That's how subrecipes work in goose: each recipe can run stand-alone for a dedicated task, and a main recipe can orchestrate how they run. -Let's explore [goose subrecipes](/docs/tutorials/sub-recipes-in-parallel) together! You're about to learn know how to orchestrate multiple AI models, coordinate tasks, and build workflows that will turn you into a "head chef" user with goose. +Let's explore [goose subrecipes](/docs/tutorials/subrecipes-in-parallel) together! You're about to learn know how to orchestrate multiple AI models, coordinate tasks, and build workflows that will turn you into a "head chef" user with goose. diff --git a/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md b/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md index fa2174062da0..ada986579a9d 100644 --- a/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md +++ b/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md @@ -7,7 +7,7 @@ authors: ![Subagents vs Subrecipes](subrecipes-vs-subagents.png) -When you're working on complex projects with goose, you'll often need to break work into multiple tasks and run them with AI agents. Goose gives you two powerful ways to do this: [subagents](/docs/experimental/subagents/) and [subrecipes](/docs/tutorials/sub-recipes-in-parallel/). Both can run multiple AI instances in parallel, but they work differently. Picking which one to use can be confusing, so we're going to guide you to a decision. +When you're working on complex projects with goose, you'll often need to break work into multiple tasks and run them with AI agents. Goose gives you two powerful ways to do this: [subagents](/docs/experimental/subagents/) and [subrecipes](/docs/tutorials/subrecipes-in-parallel/). Both can run multiple AI instances in parallel, but they work differently. Picking which one to use can be confusing, so we're going to guide you to a decision. I've been using both approaches, and the choice between them depends on what you're trying to accomplish. Let me break down when to use each method and show you real examples. diff --git a/documentation/docs/guides/recipes/index.mdx b/documentation/docs/guides/recipes/index.mdx index 3e77aecff7fa..1469e6a554e7 100644 --- a/documentation/docs/guides/recipes/index.mdx +++ b/documentation/docs/guides/recipes/index.mdx @@ -44,9 +44,9 @@ import VideoCarousel from '@site/src/components/VideoCarousel'; link="/docs/tutorials/recipes-tutorial" /> @@ -102,8 +102,8 @@ import VideoCarousel from '@site/src/components/VideoCarousel'; { type: 'iframe', src: 'https://youtube.com/embed/1szmJSKInnU', - title: 'Advanced Tips for Recipes/Sub-Recipes in Goose', - description: 'Advanced tips for using recipes and sub-recipes in goose', + title: 'Advanced Tips for Recipes/Subrecipes in Goose', + description: 'Advanced tips for using recipes and subrecipes in goose', duration: '10:07' }, { diff --git a/documentation/docs/guides/recipes/recipe-reference.md b/documentation/docs/guides/recipes/recipe-reference.md index 5ae27570c21c..3704423ab73d 100644 --- a/documentation/docs/guides/recipes/recipe-reference.md +++ b/documentation/docs/guides/recipes/recipe-reference.md @@ -80,7 +80,7 @@ Goose automatically adds metadata fields to recipes saved from the Desktop app. | `parameters` | Array | List of parameter definitions | | `extensions` | Array | List of extension configurations | | `settings` | Object | Configuration for model provider, model name, and other settings | -| `sub_recipes` | Array | List of sub-recipes | +| `sub_recipes` | Array | List of subrecipes | | `response` | Object | Configuration for structured output validation | | `retry` | Object | Configuration for automated retry logic with success validation | @@ -205,7 +205,7 @@ This feature is only available through the CLI. If a recipe uses an extension that requires a secret, Goose can prompt users to provide the secret when running the recipe: -1. When a recipe is loaded, Goose scans all extensions (including those in sub-recipes) for `env_keys` fields +1. When a recipe is loaded, Goose scans all extensions (including those in subrecipes) for `env_keys` fields 2. If any required environment variables are missing from the secure keyring, Goose prompts the user to enter them 3. Values are stored securely in the system keyring and reused for subsequent runs @@ -249,31 +249,31 @@ settings: 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. ::: -## Sub-Recipes +## Subrecipes -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: +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: -### Sub-Recipe Fields +### Subrecipe 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 | -| `sequential_when_repeated` | Boolean | (Optional) Forces sequential execution of multiple sub-recipe instances. See [Running Sub-Recipes In Parallel](/docs/tutorials/sub-recipes-in-parallel) for details | +| `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 | -### Example Sub-Recipe Configuration +### Example Subrecipe Configuration ```yaml sub_recipes: - name: "security_scan" - path: "./sub-recipes/security-analysis.yaml" + path: "./subrecipes/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" + path: "./subrecipes/quality-analysis.yaml" ``` ## Automated Retry with Success Validation @@ -426,7 +426,7 @@ Advanced template features include: ### indent() Filter For Multi-Line Values -Use the `indent()` filter to ensure multi-line parameter values are properly indented and can be resolved as valid JSON or YAML format. This example uses `{{ raw_data | indent(2) }}` to specify an indentation of two spaces when passing data to a sub-recipe: +Use the `indent()` filter to ensure multi-line parameter values are properly indented and can be resolved as valid JSON or YAML format. This example uses `{{ raw_data | indent(2) }}` to specify an indentation of two spaces when passing data to a subrecipe: ```yaml sub_recipes: diff --git a/documentation/docs/guides/recipes/sub-recipes.md b/documentation/docs/guides/recipes/subrecipes.md similarity index 76% rename from documentation/docs/guides/recipes/sub-recipes.md rename to documentation/docs/guides/recipes/subrecipes.md index d4662e74e5e8..d36231ded716 100644 --- a/documentation/docs/guides/recipes/sub-recipes.md +++ b/documentation/docs/guides/recipes/subrecipes.md @@ -1,51 +1,51 @@ --- sidebar_position: 4 -title: Sub-Recipes For Specialized Tasks -sidebar_label: Sub-Recipes -description: Learn how a recipe can use sub-recipes to perform specific tasks +title: Subrecipes For Specialized Tasks +sidebar_label: Subrecipes +description: Learn how a recipe can use subrecipes to perform specific tasks --- -Sub-recipes are recipes that are used by another recipe to perform specific tasks. They enable: +Subrecipes 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 :::warning Experimental Feature -Sub-recipes are an experimental feature in active development. Behavior and configuration may change in future releases. +Subrecipes are an experimental feature in active development. Behavior and configuration may change in future releases. ::: -## How Sub-Recipes Work +## How Subrecipes Work -The "main recipe" registers its sub-recipes in the `sub_recipes` field, which contains the following fields: +The "main recipe" registers its subrecipes 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 +- `name`: Unique identifier for the subrecipe, used to generate the tool name +- `path`: File path to the subrecipe file (relative or absolute) +- `values`: (Optional) Pre-configured parameter values that are always passed to the subrecipe -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 +When the main recipe is run, Goose generates a tool for each subrecipe that: +- Accepts parameters defined by the subrecipe +- Executes the subrecipe 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). +Sub-recipe sessions run in isolation - they don't share conversation history, memory, or state with the main recipe or other subrecipes. Additionally, subrecipes cannot define their own subrecipes (no nesting allowed). ### Parameter Handling -Parameters received by sub-recipes can be used in prompts and instructions using `{{ parameter_name }}` syntax. Sub-recipes receive parameters in two ways: +Parameters received by subrecipes can be used in prompts and instructions using `{{ parameter_name }}` syntax. Subrecipes 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. **Context-based parameters**: The AI agent can extract parameter values from the conversation context, including results from previous sub-recipes +2. **Context-based parameters**: The AI agent can extract parameter values from the conversation context, including results from previous subrecipes Pre-set values take precedence over context-based parameters. If both the conversation context and `values` field provide the same parameter, the `values` version is used. :::tip -Use the `indent()` filter to maintain valid YAML format when passing multi-line parameter values to sub-recipes, for example: `{{ content | indent(2) }}`. See [Template Support](/docs/guides/recipes/recipe-reference#template-support) for more details. +Use the `indent()` filter to maintain valid YAML format when passing multi-line parameter values to subrecipes, for example: `{{ content | indent(2) }}`. See [Template Support](/docs/guides/recipes/recipe-reference#template-support) for more details. ::: ## Examples ### Sequential Processing -This Code Review Pipeline example shows a main recipe that uses two sub-recipes to perform a comprehensive code review: +This Code Review Pipeline example shows a main recipe that uses two subrecipes to perform a comprehensive code review: **Usage:** ```bash @@ -58,9 +58,9 @@ goose run --recipe code-review-pipeline.yaml --params repository_path=/path/to/r # code-review-pipeline.yaml version: "1.0.0" title: "Code Review Pipeline" -description: "Automated code review using sub-recipes" +description: "Automated code review using subrecipes" instructions: | - Perform a code review using the available sub-recipe tools. + Perform a code review using the available subrecipe tools. Run security analysis first, then code quality analysis. parameters: @@ -71,12 +71,12 @@ parameters: sub_recipes: - name: "security_scan" - path: "./sub-recipes/security-analysis.yaml" + path: "./subrecipes/security-analysis.yaml" values: scan_level: "comprehensive" - name: "quality_check" - path: "./sub-recipes/quality-analysis.yaml" + path: "./subrecipes/quality-analysis.yaml" extensions: - type: builtin @@ -85,16 +85,16 @@ extensions: bundled: true prompt: | - Review the code at {{ repository_path }} using the sub-recipe tools. + Review the code at {{ repository_path }} using the subrecipe tools. Run security scan first, then quality analysis. ``` -**Sub-Recipes:** +**Subrecipes:**
security_scan ```yaml - # sub-recipes/security-analysis.yaml + # subrecipes/security-analysis.yaml version: "1.0.0" title: "Security Scanner" description: "Analyze code for security vulnerabilities" @@ -129,7 +129,7 @@ prompt: |
quality_check ```yaml - # sub-recipes/quality-analysis.yaml + # subrecipes/quality-analysis.yaml version: "1.0.0" title: "Code Quality Analyzer" description: "Analyze code quality and best practices" @@ -156,12 +156,12 @@ prompt: |
:::tip -For faster execution when sub-recipes are independent, see [Running Sub-Recipes In Parallel](/docs/tutorials/sub-recipes-in-parallel) to execute multiple sub-recipes concurrently. +For faster execution when subrecipes are independent, see [Running Subrecipes In Parallel](/docs/tutorials/subrecipes-in-parallel) to execute multiple subrecipes concurrently. ::: ### Conditional Processing -This Smart Project Analyzer example shows conditional logic that chooses between different sub-recipes based on analysis: +This Smart Project Analyzer example shows conditional logic that chooses between different subrecipes based on analysis: **Usage:** ```bash @@ -178,9 +178,9 @@ 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. + - If it's a web application, use the web_security_audit subrecipe + - If it's a CLI tool or library, use the api_documentation subrecipe + Only run one subrecipe based on your analysis. parameters: - key: repository_path @@ -190,13 +190,13 @@ parameters: sub_recipes: - name: "web_security_audit" - path: "./sub-recipes/web-security.yaml" + path: "./subrecipes/web-security.yaml" values: check_cors: "true" check_csrf: "true" - name: "api_documentation" - path: "./sub-recipes/api-docs.yaml" + path: "./subrecipes/api-docs.yaml" values: format: "markdown" @@ -208,15 +208,15 @@ extensions: prompt: | Analyze the project at {{ repository_path }} and determine its type. - Then run the appropriate sub-recipe tool based on your findings. + Then run the appropriate subrecipe tool based on your findings. ``` -**Sub-Recipes:** +**Subrecipes:**
web_security_audit ```yaml - # sub-recipes/web-security.yaml + # subrecipes/web-security.yaml version: "1.0.0" title: "Web Security Auditor" description: "Security audit for web applications" @@ -259,7 +259,7 @@ prompt: |
api_documentation ```yaml - # sub-recipes/api-docs.yaml + # subrecipes/api-docs.yaml version: "1.0.0" title: "API Documentation Generator" description: "Generate documentation for APIs and libraries" @@ -294,7 +294,7 @@ prompt: | ### Context-Based Parameter Passing -This Travel Planner example shows how sub-recipes can receive parameters from conversation context, including results from previous sub-recipes: +This Travel Planner example shows how subrecipes can receive parameters from conversation context, including results from previous subrecipes: **Usage:** ```bash @@ -316,11 +316,11 @@ prompt: | sub_recipes: - name: weather_data - path: "./sub-recipes/weather-data.yaml" + path: "./subrecipes/weather-data.yaml" # No values - location parameter comes from prompt context - name: activity_suggestions - path: "./sub-recipes/activity-suggestions.yaml" + path: "./subrecipes/activity-suggestions.yaml" # weather_conditions parameter comes from conversation context extensions: @@ -330,12 +330,12 @@ extensions: bundled: true ``` -**Sub-Recipes:** +**Subrecipes:**
weather_data ```yaml - # sub-recipes/weather-data.yaml + # subrecipes/weather-data.yaml version: "1.0.0" title: "Weather Data Collector" description: "Fetch current weather conditions for a location" @@ -372,7 +372,7 @@ extensions:
activity_suggestions ```yaml - # sub-recipes/activity-suggestions.yaml + # subrecipes/activity-suggestions.yaml version: "1.0.0" title: "Activity Recommender" description: "Suggest activities based on weather conditions" @@ -400,14 +400,14 @@ extensions:
In this example: -- The `weather_data` sub-recipe gets the location from the prompt context (the AI extracts "Sydney" from the natural language prompt) -- The `activity_suggestions` sub-recipe gets weather conditions from the conversation context (the AI uses the weather results from the first sub-recipe) +- The `weather_data` subrecipe gets the location from the prompt context (the AI extracts "Sydney" from the natural language prompt) +- The `activity_suggestions` subrecipe gets weather conditions from the conversation context (the AI uses the weather results from the first subrecipe) ## Best Practices -- **Single responsibility**: Each sub-recipe should have one clear purpose +- **Single responsibility**: Each subrecipe 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 +- **Test independently**: Verify subrecipes 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. diff --git a/documentation/docs/tutorials/sub-recipes-in-parallel.md b/documentation/docs/tutorials/subrecipes-in-parallel.md similarity index 64% rename from documentation/docs/tutorials/sub-recipes-in-parallel.md rename to documentation/docs/tutorials/subrecipes-in-parallel.md index 5d8e1af6a486..b61a19b79dda 100644 --- a/documentation/docs/tutorials/sub-recipes-in-parallel.md +++ b/documentation/docs/tutorials/subrecipes-in-parallel.md @@ -1,60 +1,60 @@ --- -title: Running Sub-Recipes In Parallel -sidebar_label: Sub-Recipes In Parallel -description: Run multiple sub-recipes instances concurrently with real-time progress tracking +title: Running Subrecipes In Parallel +sidebar_label: Subrecipes In Parallel +description: Run multiple subrecipes instances concurrently with real-time progress tracking --- -Goose recipes can execute multiple [sub-recipe](/docs/guides/recipes/sub-recipes) instances concurrently using isolated worker processes. This feature enables efficient batch operations, parallel processing of different tasks, and faster completion of complex workflows. +Goose recipes can execute multiple [subrecipe](/docs/guides/recipes/subrecipes) instances concurrently using isolated worker processes. This feature enables efficient batch operations, parallel processing of different tasks, and faster completion of complex workflows. :::warning Experimental Feature -Running sub-recipes in parallel is an experimental feature in active development. Behavior and configuration may change in future releases. +Running subrecipes in parallel is an experimental feature in active development. Behavior and configuration may change in future releases. ::: Here are some common use cases: -- **Monorepo build failures**: When 3 services fail in a monorepo build, use a "diagnose failure" sub-recipe with each build URL to diagnose all failures in parallel -- **Document summarization**: Process a CSV file with document links by running a "summarize document" sub-recipe for each link simultaneously +- **Monorepo build failures**: When 3 services fail in a monorepo build, use a "diagnose failure" subrecipe with each build URL to diagnose all failures in parallel +- **Document summarization**: Process a CSV file with document links by running a "summarize document" subrecipe for each link simultaneously - **Code analysis across repositories**: Run security, quality, and performance analysis on multiple codebases simultaneously ## How It Works -Parallel sub-recipe execution uses an isolated worker system that automatically manages concurrent task execution. Goose creates individual tasks for each sub-recipe instance and distributes them across up to 10 concurrent workers. +Parallel subrecipe execution uses an isolated worker system that automatically manages concurrent task execution. Goose creates individual tasks for each subrecipe instance and distributes them across up to 10 concurrent workers. | Scenario | Default Behavior | Override Options | |----------|------------------|------------------| -| **Different sub-recipes** | Sequential | Add "in parallel" to prompt | -| **Same sub-recipe** with different parameters | Parallel | • Set `sequential_when_repeated: true`
• Add "sequentially" to prompt | +| **Different subrecipes** | Sequential | Add "in parallel" to prompt | +| **Same subrecipe** with different parameters | Parallel | • Set `sequential_when_repeated: true`
• Add "sequentially" to prompt | -### Different Sub-Recipes +### Different Subrecipes -When running different sub-recipes, Goose determines the execution mode based on: +When running different subrecipes, Goose determines the execution mode based on: 1. **Explicit user request** in the prompt ("in parallel", "sequentially") -2. **Sequential execution by default**: Different sub-recipes run one after another unless explicitly requested to run in parallel +2. **Sequential execution by default**: Different subrecipes run one after another unless explicitly requested to run in parallel -In your prompt, you can simply mention "in parallel" in your prompt when calling different sub-recipes: +In your prompt, you can simply mention "in parallel" in your prompt when calling different subrecipes: ```yaml prompt: | - run the following sub-recipes in parallel: - - use weather sub-recipe to get the weather for Sydney - - use things-to-do sub-recipe to find activities in Sydney + run the following subrecipes in parallel: + - use weather subrecipe to get the weather for Sydney + - use things-to-do subrecipe to find activities in Sydney ``` -### Same Sub-Recipe +### Same Subrecipe -When running the same sub-recipe with different parameters, Goose determines the execution mode based on: +When running the same subrecipe with different parameters, Goose determines the execution mode based on: 1. **[Recipe-level configuration](#choosing-between-execution-modes)** (`sequential_when_repeated` flag) - when set to true, this forces sequential execution 2. **User request** in the prompt ("sequentially" to override default parallel behavior) -3. **Parallel execution by default**: Multiple instances of the same sub-recipe run concurrently +3. **Parallel execution by default**: Multiple instances of the same subrecipe run concurrently -If your prompt implies multiple executions of the same sub-recipe, Goose will automatically create parallel instances: +If your prompt implies multiple executions of the same subrecipe, Goose will automatically create parallel instances: ```yaml prompt: | get the weather for three biggest cities in Australia ``` -In this example, Goose recognizes that "three biggest cities" requires running the weather sub-recipe multiple times for different cities, so it executes them in parallel. +In this example, Goose recognizes that "three biggest cities" requires running the weather subrecipe multiple times for different cities, so it executes them in parallel. If you wanted to run them sequentially, you can just tell Goose: @@ -71,9 +71,9 @@ When running multiple tasks in parallel from the CLI, you can track progress thr ## Examples -### Running Different Sub-Recipes in Parallel +### Running Different Subrecipes in Parallel -This example runs the `weather` and `things-to-do` sub-recipes in parallel: +This example runs the `weather` and `things-to-do` subrecipes in parallel: ```yaml # plan_trip.yaml @@ -82,16 +82,16 @@ title: Plan Your Trip description: Get weather forecast and find things to do for your destination instructions: You are a travel planning assistant that helps users prepare for their trips. prompt: | - run the following sub-recipes in parallel to plan my trip: - - use weather sub-recipe to get the weather forecast for Sydney - - use things-to-do sub-recipe to find activities and attractions in Sydney + run the following subrecipes in parallel to plan my trip: + - use weather subrecipe to get the weather forecast for Sydney + - use things-to-do subrecipe to find activities and attractions in Sydney sub_recipes: - name: weather - path: "./sub-recipes/weather.yaml" + path: "./subrecipes/weather.yaml" values: city: Sydney - name: things-to-do - path: "./sub-recipes/things-to-do.yaml" + path: "./subrecipes/things-to-do.yaml" values: city: Sydney duration: "3 days" @@ -102,9 +102,9 @@ extensions: bundled: true ``` -### Running the Same Sub-Recipe in Parallel (with Different Parameters) +### Running the Same Subrecipe in Parallel (with Different Parameters) -This example runs three instances of the `weather` sub-recipe in parallel for different cities: +This example runs three instances of the `weather` subrecipe in parallel for different cities: ```yaml # multi_city_weather.yaml @@ -117,7 +117,7 @@ prompt: | to help me decide where to visit sub_recipes: - name: weather - path: "./sub-recipes/weather.yaml" + path: "./subrecipes/weather.yaml" extensions: - type: builtin name: developer @@ -125,12 +125,12 @@ extensions: bundled: true ``` -**Sub-Recipes:** +**Subrecipes:**
weather ```yaml - # sub-recipes/weather.yaml + # subrecipes/weather.yaml version: 1.0.0 title: Find weather description: Get weather data for a city @@ -155,7 +155,7 @@ extensions:
things-to-do ```yaml - # sub-recipes/things-to-do.yaml + # subrecipes/things-to-do.yaml version: 1.0.0 title: Things to do in a city description: Find activities and attractions for travelers @@ -201,12 +201,12 @@ While parallel execution offers speed benefits, sequential execution is sometime **Recipe-Level Configuration:** -For sub-recipes that should never run in parallel, set `sequential_when_repeated: true` to override user requests: +For subrecipes that should never run in parallel, set `sequential_when_repeated: true` to override user requests: ```yaml sub_recipes: - name: database-migration - path: "./sub-recipes/migrate.yaml" + path: "./subrecipes/migrate.yaml" sequential_when_repeated: true # Always sequential ``` diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts index 881fb7540cf5..a3b94c21910c 100644 --- a/documentation/docusaurus.config.ts +++ b/documentation/docusaurus.config.ts @@ -134,6 +134,14 @@ const config: Config = { from: '/docs/guides/recipe-reference', to: '/docs/guides/recipes/recipe-reference' }, + { + from: '/docs/guides/recipes/sub-recipes', + to: '/docs/guides/recipes/subrecipes' + }, + { + from: '/docs/tutorials/sub-recipes-in-parallel', + to: '/docs/tutorials/subrecipes-in-parallel' + }, { from: '/docs/guides/tool-permissions', to: '/docs/guides/managing-tools/tool-permissions'