From 51f68f04b0b3c99b9842a6d94107b15372007fbc Mon Sep 17 00:00:00 2001 From: angiejones Date: Sun, 2 Nov 2025 19:42:11 -0600 Subject: [PATCH 1/2] adding HOWTOAI.md --- CONTRIBUTING.md | 2 +- HOWTOAI.md | 317 ++++++++++++++++++ ai-assisted-coding-guide.md | 91 ----- .../2025-09-26-hacktoberfest-2025/index.md | 2 +- 4 files changed, 319 insertions(+), 93 deletions(-) create mode 100644 HOWTOAI.md delete mode 100644 ai-assisted-coding-guide.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf2074baadb0..7ec7a08c8268 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ If you use Goose, Copilot, Claude, or other AI tools to help with your PRs: - Document your changes - Ask for review if security or core code is involved -👉 Full guide here: [Responsible AI-Assisted Coding Guide](./ai-assisted-coding-guide.md) +👉 Full guide here: [Responsible AI-Assisted Coding Guide](./HOWTOAI.md) --- diff --git a/HOWTOAI.md b/HOWTOAI.md new file mode 100644 index 000000000000..faeb7b25b53d --- /dev/null +++ b/HOWTOAI.md @@ -0,0 +1,317 @@ +# 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-baselines/) +- 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 +./scripts/clippy-lint.sh +``` + +### 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 +``` \ No newline at end of file diff --git a/ai-assisted-coding-guide.md b/ai-assisted-coding-guide.md deleted file mode 100644 index 3464f0bb4d80..000000000000 --- a/ai-assisted-coding-guide.md +++ /dev/null @@ -1,91 +0,0 @@ -# Responsible AI-Assisted Coding Guide -_Guidelines for contributing responsibly to goose during Hacktoberfest_ - -goose benefits from thoughtful AI assisted development, but contributors must maintain high standards for code quality, security, and collaboration. Whether you use goose, Copilot, Claude, or other AI tools, these principles will help you avoid common pitfalls. - ---- - -## 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. diff --git a/documentation/blog/2025-09-26-hacktoberfest-2025/index.md b/documentation/blog/2025-09-26-hacktoberfest-2025/index.md index c55f2e291cf8..34240f7a8e7d 100644 --- a/documentation/blog/2025-09-26-hacktoberfest-2025/index.md +++ b/documentation/blog/2025-09-26-hacktoberfest-2025/index.md @@ -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/ai-assisted-coding-guide.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://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. From 07244974a2fd449778a11b1e56938321be327122 Mon Sep 17 00:00:00 2001 From: Angie Jones Date: Sun, 2 Nov 2025 19:47:08 -0600 Subject: [PATCH 2/2] Update HOWTOAI.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- HOWTOAI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HOWTOAI.md b/HOWTOAI.md index faeb7b25b53d..32efe2cb71d1 100644 --- a/HOWTOAI.md +++ b/HOWTOAI.md @@ -67,7 +67,7 @@ Before submitting AI assisted code, confirm that: ## 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) +- 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