vrr/goose
2
0
Fork 0
mirror of https://github.com/block/goose.git synced 2026-04-26 10:40:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Update contributing.md (#7927)

Browse source 
Signed-off-by: Angie Jones <angie@Angies-MBP.lan>
Co-authored-by: Douwe Osinga <douwe@squareup.com>
Co-authored-by: Angie Jones <jones.angie@gmail.com>
This commit is contained in:
Douwe Osinga 2026-03-17 02:35:27 -04:00 • committed by GitHub
parent 7e36ebcc66
commit a0835be10f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 88 additions and 375 deletions
Download patch file Download diff file Expand all files Collapse all files

1
.github/copilot-instructions.md vendored
View file

@ -43,7 +43,6 @@
- Core crates: `goose` (agent logic), `goose-cli` (CLI), `goose-server` (backend), `goose-mcp` (MCP servers)
- Error handling: Use `anyhow::Result`, not `unwrap()` in production code
- Async runtime: tokio
- See HOWTOAI.md for AI-assisted code standards
- MCP protocol implementations require extra scrutiny
- Naming convention: In `documentation/docs` and `documentation/blog`, always refer to the project as "goose" (lowercase), never "Goose" (even at the start of sentences)

17
.github/pull_request_template.md vendored
View file

@ -1,23 +1,6 @@
## Summary
<!-- Describe your change -->
### Type of Change
<!-- Select all that apply -->
- [ ] Feature
- [ ] Bug fix
- [ ] Refactor / Code quality
- [ ] Performance improvement
- [ ] Documentation
- [ ] Tests
- [ ] Security fix
- [ ] Build / Release
- [ ] Other (specify below)
### AI Assistance
<!-- great that you got assistance 🔥, just check out the HOWTOAI guidance: https://github.com/block/goose/blob/main/HOWTOAI.md-->
- [ ] This PR was created or reviewed with AI assistance
### Testing
<!-- How have this change been tested? Unit/integration tests? Manual testing? -->

125
CONTRIBUTING.md
View file

@ -2,43 +2,97 @@
goose is open source!
We welcome pull requests for general contributions! If you have a larger new feature or any questions on how to develop a fix, we recommend you open an issue before starting.
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.
> [!TIP]
> Beyond code, check out [other ways to contribute](#other-ways-to-contribute)
---
## 🤖 Quick Responsible AI Tips
If you use Goose, Copilot, Claude, or other AI tools to help with your PRs:
**✅ Good Uses**
- Boilerplate code and common patterns
- Test generation
- Docs and comments
- Refactoring for clarity
- Utility functions/helpers
**❌ Avoid AI For**
- Security-critical logic
- Complex business rules you don’t understand
- Large architectural or schema changes
**Quality Checklist**
- Understand every line of code you submit
- All tests pass locally
- Code follows Goose’s patterns
- Document your changes
- Ask for review if security or core code is involved
👉 Full guide here: [Responsible AI-Assisted Coding Guide](./HOWTOAI.md)
---
## Getting Started
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.
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.
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.
## Discussions, Issues and PRs
### Issues
If you spot a bug or have a concrete proposal for a feature, please open an issue. This shows the community and
the maintainers the direction of your thinking.
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.
### Discussions
If you have an idea but are not yet sure how it should work, open a discussion instead. Discussions are a good
place to explore design questions, alternatives, and whether something fits the goals of the project.
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.
### Pull Requests
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.
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.
### 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.
## AI Code Reviews
We use codex as an AI code reviewer. AI code reviewing has come a long way and more often than not points
out real issues. So we expect you to address all of them by either fixing the code or adding a one-line
answer as to why this is not an issue or not worth fixing.
If not, we might close the PR and/or reply with a link to this section. Once you address the comments, you
can always reopen.
## Quick Responsible AI Tips
There's no need to tell us you used AI in your work. You are contributing to an agent, it would be odd if
you had not. Our general thinking is, use AI anyway you want, but until the robot revolution comes, you
are responsible for the final code. Before submitting a PR for review, make sure you have reviewed it yourself.
We'll close any vibe coded submissions that obviously skip this step.
You can use whatever agent and whatever methodology you like as long as you stick to that principle. We hope
you like goose of course and use that. One thing to watch out for is LLM eagerness. They like to please and
are in a hurry.
* **Think first**. Agents tend to jump straight to code writing. Explain the architecture you want first to
avoid this behavior, based on your own understanding of the code, or have the agent explore the code first and
suggest approaches. If the first implementation doesn't look quite right, just start over and use
what you learned to do better next time.
* **Spot the laziness**. LLMs will make their job easy. They'll write trivial tests, make types wide and
optional so the compiler doesn't complain, catch exceptions and just log instead of handling errors
and copy local patterns whether appropriate or not. Push back!
* **Spot the uncertainty**. As much as the bots declare I see the issue now clearly, they often do not. Call
them on it, if you see the agent flailing. Another telltale sign is if the agent starts listing the
number of ways it fixed an issue or starts writing overly defensive code.
* **Spot the bloat**. Agents like to insert redundant comments or worse, commenting on the change at hand,
not the resulting code. They create loads of tests that don't really test anything and if they do,
test the implementation, not the intention. They also like to log anything, just in case.
## Prerequisites
goose includes Rust binaries alongside an electron app for the GUI.
@ -108,12 +162,6 @@ cargo clippy --all-targets -- -D warnings # run the linter
### Node
> [!NOTE]
> This project uses **pnpm** (not npm). If you previously had `node_modules` installed via npm, remove them first:
> ```bash
> rm -rf ui/desktop/node_modules
> ```
To run the app:
```
@ -206,7 +254,8 @@ git push origin my-feature-branch
## Keeping Your Fork Up-to-Date
To ensure a smooth integration of your contributions, it's important that your fork is kept up-to-date with the main repository. This helps avoid conflicts and allows us to merge your pull requests more quickly. Here’s how you can sync your fork:
To ensure a smooth integration of your contributions, it's important that your fork is kept up-to-date with the main
repository. This helps avoid conflicts and allows us to merge your pull requests more quickly. Here’s how you can sync your fork:
### Syncing Your Fork with the Main Repository

317
HOWTOAI.md
View file

@ -1,317 +0,0 @@
# How to Use AI with goose
_A practical guide for contributing to goose using AI coding assistants_
goose benefits from thoughtful AI-assisted development, but contributors must maintain high standards for code quality, security, and collaboration. Whether you use goose itself, GitHub Copilot, Cursor, Claude, or other AI tools, this guide will help you contribute effectively.
---
## Core Principles
- **Human Oversight**: You are accountable for all code you submit. Never commit code you don’t understand or can’t maintain.
- **Quality Standards**: AI code must meet the same standards as human written code—tests, docs, and patterns included.
- **Transparency**: Be open about significant AI usage in PRs and explain how you validated it.
---
## Best Practices
**✅ Recommended Uses**
- Generating boilerplate code and common patterns
- Creating comprehensive test suites
- Writing documentation and comments
- Refactoring existing code for clarity
- Generating utility functions and helpers
- Explaining existing code patterns
**❌ Avoid AI For**
- Complex business logic without thorough review
- Security critical authentication/authorization code
- Code you don’t fully understand
- Large architectural changes
- Database migrations or schema changes
**Workflow Tips**
- Start small and validate often. Build, lint, and test incrementally
- Study existing patterns before generating new code
- Always ask: "Is this secure? Does it follow project patterns? What edge cases need testing?"
**Security Considerations**
- Extra review required for MCP servers, network code, file system ops, user input, and credential handling
- Never expose secrets in prompts
- Sanitize inputs/outputs and follow goose’s security patterns
---
## Testing & Review
Before submitting AI assisted code, confirm that:
- You understand every line
- All tests pass locally (happy path + error cases)
- Docs are updated and accurate
- Code follows existing patterns
**Always get human review** for:
- Security sensitive code
- Core architecture changes
- Async/concurrency logic
- MCP protocol implementations
- Large refactors or anything you’re unsure about
---
## Using goose for goose development
- Protect sensitive files with `.gooseignore` (e.g., `.env*`, `*.key`, `target/`, `.git/`)
- Guide goose with `.goosehints` (patterns, error handling, formatting, tests, docs)
- Use `/plan` to structure work, and choose modes wisely:
- **Chat** for understanding
- **Smart Approval** for most dev work
- **Approval** for critical areas
- **Autonomous** only with safety nets
---
## Community & Collaboration
- In PRs, note significant AI use and how you validated results
- Share prompting tips, patterns, and pitfalls
- Be responsive to feedback and help improve this guide
---
## Remember
AI is a powerful assistant, not a replacement for your judgment. Use it to speed up development; while keeping your brain engaged, your standards high, and goose secure.
Questions? Join our [Discord](https://discord.gg/goose-oss) or [GitHub Discussions](https://github.com/block/goose/discussions) to talk more about responsible AI development.
---
## Getting Started with AI Tools
### Quick Setup
**Using goose (meta!):**
```bash
# Install goose
curl -fsSL https://github.com/block/goose/releases/latest/download/install.sh | bash
# Navigate to your goose clone
cd /path/to/goose
# Start goose in the repo
goose
```
**Using GitHub Copilot:**
- Install the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) for VS Code
- Enable Copilot for Rust files in your settings
- Recommended: Also install [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) for better code intelligence
**Using Cursor:**
- Download [Cursor](https://cursor.sh/) (VS Code fork with built-in AI)
- Open the goose repository
- Use Cmd/Ctrl+K for inline AI editing, Cmd/Ctrl+L for chat
**Using Claude or ChatGPT:**
- Copy relevant code sections into the chat interface
- Provide context about the goose architecture (see below)
- Always test generated code locally before committing
### Rust-Specific Configuration
If you're new to Rust, configure your AI tool to help you learn:
**VS Code settings.json:**
```json
{
"rust-analyzer.checkOnSave.command": "clippy",
"github.copilot.enable": {
"rust": true
}
}
```
**Cursor Rules (.cursorrules in repo root):**
```
This is a Rust project using cargo workspaces.
- Follow existing error handling patterns using anyhow::Result
- Use async/await for I/O operations
- Follow the project's clippy lints (see clippy.toml)
- Run cargo fmt before committing
```
---
## Understanding goose's Architecture
New to AI agents? Here are key questions to ask your AI tool:
### Essential Concepts
**"Explain the goose crate structure"**
```
Ask: "I'm looking at the goose repository. Can you explain the purpose of each crate
in the crates/ directory and how they relate to each other?"
Key insight: goose uses a workspace with specialized crates:
- goose: Core agent logic
- goose-cli: Command-line interface
- goose-server: Backend for desktop app (goosed)
- goose-mcp: MCP server implementations
```
**"How does the MCP protocol work in goose?"**
```
Ask: "What is the Model Context Protocol (MCP) and how does goose implement it?
Show me an example from crates/goose-mcp/"
Key insight: MCP allows goose to connect to external tools and data sources.
Each MCP server provides specific capabilities (developer tools, file access, etc.)
```
**"What's the agent execution flow?"**
```
Ask: "Walk me through what happens when a user sends a message to goose.
Start from crates/goose-cli/src/main.rs"
Key insight: Message → Agent → Provider (LLM) → Tool execution → Response
```
### Navigating the Codebase with AI
**Finding the right file:**
```
# Use ripgrep with AI assistance
Ask: "I want to add a new shell command tool. Where should I look?"
AI might suggest: rg "shell" crates/goose-mcp/ -l
Then ask: "Explain the structure of crates/goose-mcp/src/developer/tools/shell.rs"
```
**Understanding patterns:**
```
Ask: "Show me the pattern for implementing a new Provider in goose"
Then: "What's the difference between streaming and non-streaming providers?"
```
---
## Practical Examples
### Example 1: Understanding How to Add a New MCP Tool
**Scenario:** You want to add a new tool to the developer MCP server.
**Step 1 - Explore existing tools:**
```bash
# Ask AI: "Show me the structure of an existing MCP tool"
ls crates/goose-mcp/src/developer/tools/
# Pick a simple one to study
# Ask AI: "Explain this tool implementation line by line"
cat crates/goose-mcp/src/developer/tools/shell.rs
```
**Step 2 - Ask AI to draft your new tool:**
```
Prompt: "I want to add a new MCP tool called 'git_status' that runs git status
and returns the output. Based on the pattern in shell.rs, draft the implementation."
```
**Step 3 - Validate with AI:**
```
Ask: "Review this code for:
1. Proper error handling using anyhow::Result
2. Security concerns (command injection, etc.)
3. Async/await patterns matching the codebase
4. Test coverage needs"
```
**Step 4 - Test locally:**
```bash
# Build and test
cargo build -p goose-mcp
cargo test -p goose-mcp
# Run clippy
cargo clippy --all-targets -- -D warnings
```
### Example 2: Fixing a Rust Compiler Error
**Scenario:** You're getting a lifetime error you don't understand.
**Step 1 - Copy the full error:**
```bash
cargo build 2>&1 | pbcopy # macOS
cargo build 2>&1 | xclip # Linux
```
**Step 2 - Ask AI with context:**
```
Prompt: "I'm getting this Rust compiler error in the goose project:
[paste error]
Here's the relevant code:
[paste code section]
Explain what's wrong and how to fix it following Rust best practices."
```
**Step 3 - Understand the fix:**
```
Ask: "Explain why this fix works and what I should learn about Rust lifetimes"
```
**Step 4 - Apply and verify:**
```bash
# Apply the fix
# Then verify it compiles and tests pass
cargo build
cargo test
```
### Example 3: Adding a Feature to the CLI
**Scenario:** You want to add a new command-line flag to goose-cli.
**Step 1 - Find the CLI argument parsing:**
```bash
# Ask AI: "Where does goose-cli parse command line arguments?"
rg "clap" crates/goose-cli/src/ -l
```
**Step 2 - Study the pattern:**
```
Ask: "Explain how goose-cli uses clap for argument parsing.
Show me how existing flags are defined."
```
**Step 3 - Draft your addition:**
```
Prompt: "I want to add a --verbose flag that enables debug logging.
Based on the existing patterns in goose-cli, show me:
1. How to add the flag to the CLI args struct
2. How to pass it to the goose core
3. How to use it to control log levels"
```
**Step 4 - Implement with validation:**
```bash
# Make changes
# Build both crates
cargo build -p goose-cli -p goose
# Test the new flag
./target/debug/goose --verbose session
# Run tests
cargo test -p goose-cli
```

1
README.md
View file

@ -27,7 +27,6 @@ Designed for maximum flexibility, goose works with any LLM and supports multi-mo
- [Installation](https://block.github.io/goose/docs/getting-started/installation)
- [Tutorials](https://block.github.io/goose/docs/category/tutorials)
- [Documentation](https://block.github.io/goose/docs/category/getting-started)
- [Responsible AI-Assisted Coding Guide](https://github.com/block/goose/blob/main/HOWTOAI.md)
- [Governance](https://github.com/block/goose/blob/main/GOVERNANCE.md)
- [Custom Distributions](https://github.com/block/goose/blob/main/CUSTOM_DISTROS.md) - build your own goose distro with preconfigured providers, extensions, and branding

2
documentation/blog/2025-09-26-hacktoberfest-2025/index.md
View file

@ -34,7 +34,7 @@ To help you make the most of each of your contributions, below is a quick guide
## ✅ Key Rules
1. Read the [code of conduct](https://github.com/block/.github/blob/main/CODE_OF_CONDUCT.md).
2. Refer to the [Responsible AI-Assisted Coding Guide](https://github.com/block/goose/blob/main/HOWTOAI.md), [Contributing Guide](https://github.com/block/goose/blob/main/CONTRIBUTING.md) & [README](https://github.com/block/goose/blob/main/README.md) for your contributions.
2. Refer to the [Responsible AI-Assisted Coding Guide](https://web.archive.org/web/20260305122657/https://github.com/block/goose/blob/main/HOWTOAI.md), [Contributing Guide](https://github.com/block/goose/blob/main/CONTRIBUTING.md) & [README](https://github.com/block/goose/blob/main/README.md) for your contributions.
3. Choose a task from this project's Hacktoberfest [Project Hub](https://github.com/block/goose/issues/4705). Each issue has the 🏷️ `hacktoberfest` label.
4. Comment ".take" on the corresponding issue to get assigned the task.
5. Fork the repository and create a new branch for your work.