From 9b06584e1598cfa5f123e89acc9ebdd5d18998fa Mon Sep 17 00:00:00 2001 From: Douwe M Osinga Date: Thu, 30 Jul 2026 14:59:38 +0200 Subject: [PATCH 1/5] docs: adopt issue-first contribution workflow --- AGENTS.md | 13 ++ CONTRIBUTING.md | 66 ++++----- CONTRIBUTING_RECIPES.md | 133 ------------------ .../2025-09-15-subrecipes-in-goose/index.md | 2 +- documentation/src/pages/recipes/index.tsx | 2 +- 5 files changed, 43 insertions(+), 173 deletions(-) delete mode 100644 CONTRIBUTING_RECIPES.md diff --git a/AGENTS.md b/AGENTS.md index 7f980606aa99..3ebf1c550ef4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,19 @@ goose is an AI agent framework in Rust with CLI and Electron desktop interfaces. +## Contribution Workflow + +The issue is the source of truth for work intended for an upstream pull request. Track issue status on the [Goose Issues board](https://github.com/orgs/aaif-goose/projects/1). + +- Before implementing an issue for a pull request, confirm that it is on the board with Status **Ready**. +- Do not implement issues in **Inbox**, **Needs info**, or **Accepted / design**. Help resolve the issue discussion instead. +- Read the agreed design, constraints, non-goals, and verification plan before changing code. +- Keep the implementation within the issue's agreed scope. +- If implementation reveals a material design change, return to the issue before continuing. +- Every external pull request must link the Ready issue it implements and explain how the verification plan was performed. + +Maintainer-directed work, urgent security fixes, release automation, and local or exploratory changes do not require a Ready issue. + ## Setup ```bash source bin/activate-hermit diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d1d8763fcc2..9937047d96cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,64 +1,54 @@ # Contribution Guide -goose is open source! +goose is open source, and code is only one way to contribute. Reporting a problem, reproducing it, sharing domain knowledge, shaping the design, implementing the solution, and verifying the result are all valuable work. -We welcome pull requests for general contributions! In these days of AI it is easier than ever to contribute, but -there are some pitfalls to avoid. This document describes the best practices for new and experienced contributors -to get work landed as smoothly as possible. +We organize this work on the public [Goose Issues board](https://github.com/orgs/aaif-goose/projects/1). The issue is the main record of a contribution, from the first report through design, implementation, and verification. > [!TIP] > Beyond code, check out [other ways to contribute](#other-ways-to-contribute) --- -## Getting Started +## Issue Workflow -Your first contribution to goose should probably be a small bug fix. The goose maintainers have a lot of incoming -PRs to review, and the reputation of the author is an important signal. While contributions to goose are generally -of remarkably high quality, we do get our fair share of AI slop. When a first-time contributor opens a -3k line PR touching 20 files, we have no easy way to tell whether it’s thoughtful work or -blindly AI-generated without doing a deep dive. +Every open issue is tracked on the [Goose Issues board](https://github.com/orgs/aaif-goose/projects/1): -So please start small to establish trust and work your way up from there. A small bug fix or performance improvement -is a good start. Linking your fix to an existing issue shows that you are responding to a community need. +- **Inbox**: The issue is waiting for triage. +- **Needs info**: More information is needed before the issue can progress. +- **Accepted / design**: We want to solve the problem and are working out the design, constraints, and verification plan. +- **Ready**: The intended solution is settled and implementation can begin. +- **In progress**: Implementation is underway. +- **Verification**: The implementation is ready for a human to confirm that it works. +- **Done**: The result has been verified and the issue is closed. -If your first PR gets closed with a link to this section, please don’t take it personally. -It just means the change was too large for a first contribution. Start with something smaller and try again. +Issues we do not plan to pursue are closed with an explanation. We do not use rejection labels. -## Discussions, Issues and PRs +Feature requests should describe a broadly useful problem rather than only a preferred implementation. Adding features is easy; maintaining them is a long-term cost, so we may decline features that add complexity without enough general benefit. -### Issues +Discord and GitHub Discussions remain useful for informal conversation, but decisions that affect an implementation should be captured in the issue. -If you spot a bug, please open an issue. This shows the community and the maintainers the direction of your -thinking. +## How to Contribute -For bugs, describe how to reproduce the problem as clearly as possible. If the issue involves an interaction -with an LLM, include a diagnostics report if possible. +If you find a bug or want a new feature, [open an issue](https://github.com/aaif-goose/goose/issues/new/choose). A good issue explains the problem, who it affects, and why it matters. For bugs, include clear reproduction steps and a diagnostics report when possible. -### Discussions +The best place to contribute is the discussion between **Accepted / design** and **Ready**. This is where the engineering happens: turning a worthwhile problem into a specific solution that an agent can implement. Take part in the issue discussion by bringing context and domain knowledge, challenging assumptions, comparing approaches, identifying constraints and trade-offs, and agreeing on how the result will be verified. -Before opening a feature request or beginning implementation, please start with a discussion in the -[goose-eng Discord channel](https://discord.com/channels/1287729918100246654/1514412780504088677). Discussions -are a good place to explore design questions, alternatives, and whether something fits the goals of the project. +Substantial contributors at any stage may be recognized as co-authors. The unit of contribution is taking a problem to a verified solution, not writing the patch. -If a change is large or touches multiple parts of the codebase, please start with a discussion before opening a PR. -This helps us align on direction before you spend time implementing something. +## From Issue to Pull Request -### Pull Requests +Do not begin implementation or open a pull request until the issue has reached **Ready** on the Goose Issues board. -Open a PR when you have a concrete change ready. For first contributions we strongly recommend starting small -(see [Getting Started](#getting-started)). Don't open many PRs in quick succession. Submit them in order of -your preference and wait for them to land before opening more. +Every external pull request must: -If the code is still evolving but useful for discussion, open the PR in draft mode. Draft PRs are for discussion, -not just unfinished work. If it’s not ready yet, keep the branch local. +- link the Ready issue it implements; +- stay within the design and scope agreed in the issue; +- explain how the issue's verification plan was carried out; and +- return material design changes to the issue for discussion. -### Feature Requests - -Before proposing a new feature, consider whether it is something broadly useful or mainly a personal preference. -Adding features is easy; maintaining them is a long-term cost, so we may decline features that add complexity -without clear general benefit. +Pull requests that do not implement a Ready issue will be closed. Automated dependency and release pull requests, urgent security fixes, and work explicitly directed by the core team are exempt. +Don't open many pull requests in quick succession. Submit them in order of preference and wait for them to land before opening more. ## AI Code Reviews @@ -120,7 +110,7 @@ sudo apt install build-essential # build-essential is a package that installs a sudo apt install libxcb1-dev # libxcb1-dev is the development package for the X C Binding (XCB) library on Linux ``` -## Getting Started +## Development Setup ### Rust diff --git a/CONTRIBUTING_RECIPES.md b/CONTRIBUTING_RECIPES.md deleted file mode 100644 index 55bf973b15e6..000000000000 --- a/CONTRIBUTING_RECIPES.md +++ /dev/null @@ -1,133 +0,0 @@ -# 🍳 Contributing Recipes to goose Cookbook - -Thank you for your interest in contributing to the goose Recipe Cookbook! This guide will walk you through the process of submitting your own recipe. - -## πŸš€ Quick Start - -1. [Fork this repository](https://github.com/aaif-goose/goose/fork) -2. Add your recipe file here: `documentation/src/pages/recipes/data/recipes/` -3. Create a pull request - -## πŸ“‹ Step-by-Step Guide - -### Step 1: Fork the Repository - -Click the **"Fork"** button at the top of this repository to create your own copy. - -### Step 2: Create Your Recipe File - -1. **Navigate to**: `documentation/src/pages/recipes/data/recipes/` -2. **Create a new file**: `your-recipe-name.yaml` -3. **Important**: Choose a unique filename that describes your recipe - -**Example**: For a web scraping recipe, create `web-scraper.yaml` - -### Step 3: Write Your Recipe - -Use this template structure: - -```yaml -# Required fields -version: 1.0.0 -title: "Your Recipe Name" # Should match your filename -description: "Brief description of what your recipe does" -instructions: "Detailed instructions for what the recipe should accomplish" -author: - contact: "your-github-username" -extensions: - - type: builtin - name: developer -activities: - - "Main activity 1" - - "Main activity 2" - - "Main activity 3" -prompt: | - Detailed prompt describing the task step by step. - - Use {{ parameter_name }} to reference parameters. - - Be specific and clear about what should be done. - -# Optional fields -parameters: - - key: parameter_name - input_type: string - requirement: required - description: "Description of this parameter" - value: "default_value" - - key: optional_param - input_type: string - requirement: optional - description: "Description of optional parameter" - default: "default_value" -``` - -πŸ“š **Need help with the format?** Check out the [Recipe Reference Guide](https://goose-docs.ai/docs/guides/recipes/recipe-reference) or [existing recipes](documentation/src/pages/recipes/data/recipes/) for examples. - -### Step 4: Create a Pull Request - -1. **Commit your changes** in your forked repository -2. **Go to the original repository** and click "New Pull Request" -3. **Fill out the PR template** - -### Step 5: Wait for Review - -Our team will: -1. βœ… **Validate** your recipe automatically -2. πŸ‘€ **Review** for quality and usefulness -3. πŸ”’ **Security scan** (if approved for review) -4. πŸŽ‰ **Merge** your recipe! - -## βœ… Recipe Requirements - -Your recipe should: - -- [ ] **Work correctly** - Test it before submitting -- [ ] **Be useful** - Solve a real problem or demonstrate a valuable workflow -- [ ] **Follow the format** - Refer to the [Recipe Reference Guide](https://goose-docs.ai/docs/guides/recipes/recipe-reference) -- [ ] **Have a unique filename** - No conflicts with existing recipe files - -### πŸ“ **Naming Guidelines:** -- **Filename**: Choose a descriptive, unique filename (e.g., `web-scraper.yaml`) -- **Title**: Should match your filename (e.g., `"Web Scraper"`) - -## πŸ” Recipe Validation - -Your recipe will be automatically validated for: - -- βœ… **Correct YAML syntax** -- βœ… **Required fields present** -- βœ… **Proper structure** -- βœ… **Security compliance** - -If validation fails, you'll get helpful feedback in the PR comments. - -## 🎯 Recipe Ideas - -Need inspiration? Consider recipes for: - -- **Web scraping** workflows -- **Data processing** pipelines -- **API integration** tasks -- **File management** automation -- **Code generation** helpers -- **Testing** and validation -- **Deployment** processes - -## πŸ†˜ Need Help? - -- πŸ“– **Browse existing recipes** for examples -- πŸ’¬ **Ask questions** in your PR -- πŸ› **Report issues** if something isn't working -- πŸ“š **Check the docs** at [goose-docs.ai](https://goose-docs.ai/docs/guides/recipes/) - -## 🀝 Community Guidelines - -- Keep recipes focused and practical -- Share knowledge and learn from others - ---- - -**Ready to contribute?** [Fork the repo](https://github.com/aaif-goose/goose/fork) and start creating! - -*Questions? Ask in your PR or hop into [discord](https://discord.gg/goose-oss) - we're here to help!* πŸ’™ 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 11265ad295d6..cfdfecec22ac 100644 --- a/documentation/blog/2025-09-15-subrecipes-in-goose/index.md +++ b/documentation/blog/2025-09-15-subrecipes-in-goose/index.md @@ -383,7 +383,7 @@ Do you have a recipe you'd like to share with the community? We'd love to featur **How to contribute:** 1. [Fork the goose repository](https://github.com/aaif-goose/goose/fork) 2. Add your recipe YAML file to the [`documentation/src/pages/recipes/data/recipes/`](https://github.com/aaif-goose/goose/tree/main/documentation/src/pages/recipes/data/recipes) directory -3. Create a pull request following our [Recipe Contribution Guide](https://github.com/aaif-goose/goose/blob/main/CONTRIBUTING_RECIPES.md) +3. Create a pull request following our [Contribution Guide](https://github.com/aaif-goose/goose/blob/main/CONTRIBUTING.md) Browse [existing recipes](https://github.com/aaif-goose/goose/tree/main/documentation/src/pages/recipes/data/recipes) for inspiration and formatting examples. diff --git a/documentation/src/pages/recipes/index.tsx b/documentation/src/pages/recipes/index.tsx index 8a0c50a27230..dde47e56b08b 100644 --- a/documentation/src/pages/recipes/index.tsx +++ b/documentation/src/pages/recipes/index.tsx @@ -95,7 +95,7 @@ export default function RecipePage() { Recipes Cookbook

Save time and skip setup. Launch any{" "} From 4e2b6686a7d51549526b47774cbe1f60b5cc2d9f Mon Sep 17 00:00:00 2001 From: Douwe M Osinga Date: Thu, 30 Jul 2026 17:33:25 +0200 Subject: [PATCH 4/5] docs: address contribution review feedback --- .github/ISSUE_TEMPLATE/bug_report.md | 2 ++ .../2025-08-25-goose-became-its-own-watchdog/index.md | 10 ++++++---- documentation/src/pages/recipes/index.tsx | 1 + 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d58649e65dbf..0892e3bf414a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -48,3 +48,5 @@ If applicable, add screenshots to help explain your problem. **Additional context** Add any other context about the problem here. + +Do not begin implementation until the issue reaches **Ready** on the [Goose Issues board](https://github.com/orgs/aaif-goose/projects/1). diff --git a/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md b/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md index 0942869c4197..9a282ac9c67f 100644 --- a/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md +++ b/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md @@ -7,6 +7,8 @@ authors: ![Goose Recipe Safety](goose-security-scanner.png) +> **Update:** This post is preserved for historical reference. The public Recipe Cookbook submission program has ended, and we are no longer accepting new recipe submissions. + Remember when people shared recipes by passing handwritten cards between neighbors? You trusted Grandma's apple pie recipe because you knew Grandma. But what happens when strangers start sharing recipes online? You need someone to taste-test them first. That's exactly the challenge we face with Goose recipes. We're building a community cookbook where you can try Goose recipes from other users with confidence that they're safe. But we needed a way to make sure every recipe was safe to run. @@ -33,9 +35,9 @@ In the end I crafted a series of recipes that were safe, some that were maybe a The process at a glance seems surprisingly simple but it's pretty complex -- picture the graceful goose swimming on the water but under the water the feet are thrashing around doing lots of work! -When someone submits a recipe via our GitHub issue template, it will start an automated scan. Goose spins up in an isolated Docker container, analyzes the recipe using its own security expertise plus some of our guidance, scores it for risk, and posts the results right back to the GitHub issue. - -The whole process takes minutes instead of days, and the submitter gets immediate, transparent feedback about their recipe's safety. If something looks off, our team can review what's going on, and take appropriate action. +When someone submitted a recipe via our GitHub issue template, it started an automated scan. Goose ran in an isolated Docker container, analyzed the recipe using its own security expertise plus some of our guidance, scored it for risk, and posted the results back to the GitHub issue. + +The whole process took minutes instead of days, and the submitter received immediate, transparent feedback about their recipe's safety. If something looked off, our team could review what was going on and take appropriate action. ## Goose in Headless Mode @@ -82,7 +84,7 @@ Goose catches edge cases that humans might miss, like subtle obfuscation techniq Sometimes the best way to solve a potential AI problem is with more AI. Goose understands Goose behavior patterns better than any human reviewer could. It knows the legitimate ways to automate tasks and can spot when something deviates from those patterns. Using Goose to build this scanner wasn't just a time-saver for making the tool, it's a productivity win for our team from manually review every recipe ourselves. -Anyone can submit a recipe knowing it'll get a fair, thorough review. And when you see a recipe get a security approval, remember: it was approved by Goose itself. +At the time, anyone could submit a recipe knowing it would get a fair, thorough review. And when a recipe received security approval, it was approved by Goose itself. diff --git a/documentation/src/pages/recipes/index.tsx b/documentation/src/pages/recipes/index.tsx index 7c2261a9b4e8..a46c065bd32d 100644 --- a/documentation/src/pages/recipes/index.tsx +++ b/documentation/src/pages/recipes/index.tsx @@ -4,6 +4,7 @@ import { useState, useEffect } from "react"; import { motion } from "framer-motion"; import Layout from "@theme/Layout"; import Admonition from "@theme/Admonition"; +import { Button } from "@site/src/components/ui/button"; import { SidebarFilter, type SidebarFilterGroup } from "@site/src/components/ui/sidebar-filter"; import { Menu, X } from "lucide-react"; import Link from '@docusaurus/Link'; From f0fb5bd27b46f85f7d3df47a2f7352b3641b0589 Mon Sep 17 00:00:00 2001 From: Douwe M Osinga Date: Thu, 30 Jul 2026 17:45:57 +0200 Subject: [PATCH 5/5] docs: retire remaining recipe submission copy --- .../index.md | 4 ++-- .../2025-10-08-recipe-cookbook-generator/index.md | 14 ++++++++------ 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md b/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md index 9a282ac9c67f..4438326b1649 100644 --- a/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md +++ b/documentation/blog/2025-08-25-goose-became-its-own-watchdog/index.md @@ -35,7 +35,7 @@ In the end I crafted a series of recipes that were safe, some that were maybe a The process at a glance seems surprisingly simple but it's pretty complex -- picture the graceful goose swimming on the water but under the water the feet are thrashing around doing lots of work! -When someone submitted a recipe via our GitHub issue template, it started an automated scan. Goose ran in an isolated Docker container, analyzed the recipe using its own security expertise plus some of our guidance, scored it for risk, and posted the results back to the GitHub issue. +When someone submitted a recipe via our GitHub issue template, it started an automated scan. goose ran in an isolated Docker container, analyzed the recipe using its own security expertise plus some of our guidance, scored it for risk, and posted the results back to the GitHub issue. The whole process took minutes instead of days, and the submitter received immediate, transparent feedback about their recipe's safety. If something looked off, our team could review what was going on and take appropriate action. @@ -84,7 +84,7 @@ Goose catches edge cases that humans might miss, like subtle obfuscation techniq Sometimes the best way to solve a potential AI problem is with more AI. Goose understands Goose behavior patterns better than any human reviewer could. It knows the legitimate ways to automate tasks and can spot when something deviates from those patterns. Using Goose to build this scanner wasn't just a time-saver for making the tool, it's a productivity win for our team from manually review every recipe ourselves. -At the time, anyone could submit a recipe knowing it would get a fair, thorough review. And when a recipe received security approval, it was approved by Goose itself. +At the time, anyone could submit a recipe knowing it would get a fair, thorough review. And when a recipe received security approval, it was approved by goose itself. diff --git a/documentation/blog/2025-10-08-recipe-cookbook-generator/index.md b/documentation/blog/2025-10-08-recipe-cookbook-generator/index.md index 986d24ebd9d2..cb1d1e7e965d 100644 --- a/documentation/blog/2025-10-08-recipe-cookbook-generator/index.md +++ b/documentation/blog/2025-10-08-recipe-cookbook-generator/index.md @@ -5,9 +5,11 @@ authors: - ian --- -![Recipe Cookbook Generator](recipe-cookbook-generator.png) - -You've been using goose for weeks, maybe months. You have dozens of successful [sessions](/docs/guides/sessions/) where you asked for help with blog posts, code reviews, documentation, or data analysis. Each time you think "Didn't I already do this?" but never get around to checking. Sound familiar? +![Recipe Cookbook Generator](recipe-cookbook-generator.png) + +> **Update:** This post is preserved for historical reference. The public Recipe Cookbook submission program has ended, and we are no longer accepting new recipe submissions. + +You've been using goose for weeks, maybe months. You have dozens of successful [sessions](/docs/guides/sessions/) where you asked for help with blog posts, code reviews, documentation, or data analysis. Each time you think "Didn't I already do this?" but never get around to checking. Sound familiar? I myself had over a hundred goose sessions and as many megabytes of conversation data. I was sitting on a goldmine of potential automation. A coworker suggested something brilliant: "What if goose could analyze your sessions and build recipes automatically?" Wait, wait, wait!! Create a personalized cookbook based on my own session history? Yes, please! Let's build a "cookbook generator" recipe! @@ -167,9 +169,9 @@ The key insight is that AI agents shouldn't just execute tasks -- they should le Start building your own cookbook generator, and stop doing the same work twice. Your future self will thank you for the automation you create today. -## Contribute to Our Community Cookbook - -Want to contribute your own recipes or improvements to the cookbook generator? Join our [Discord community](https://discord.gg/goose-oss) or check out our [GitHub repository](https://github.com/aaif-goose/goose) for more automation ideas. Join our [Hacktoberfest](https://github.com/aaif-goose/goose/issues/4705) event going on to contribute recipes and prompt ideas to get on our leaderboard to win some great prizes! +## Recipe Submissions Are Closed + +The Recipe Cookbook remains available to browse, but we are no longer accepting new community recipe submissions. ## My Own Cookbook Generator Recipe