From 56ada0cc4ac4efd8c072105da829a166256fea60 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 29 Sep 2025 11:18:10 -0400
Subject: [PATCH] Add AGENTS.md documentation for AI agent development
 guidelines

---
 documentation/AGENTS.md | 98 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 documentation/AGENTS.md

diff --git a/documentation/AGENTS.md b/documentation/AGENTS.md
new file mode 100644
index 0000000000..228bd49757
--- /dev/null
+++ b/documentation/AGENTS.md
@@ -0,0 +1,98 @@
+# AGENTS Instructions
+
+goose is an AI agent framework in Rust with CLI and Electron desktop interfaces.
+
+## Setup
+```bash
+source bin/activate-hermit
+cargo build
+```
+
+## Commands
+
+### Build
+```bash
+cargo build                   # debug
+cargo build --release         # release  
+just release-binary           # release + openapi
+```
+
+### Test
+```bash
+cargo test                   # all tests
+cargo test -p goose          # specific crate
+cargo test --package goose --test mcp_integration_test
+just record-mcp-tests        # record MCP
+```
+
+### Lint/Format
+```bash
+cargo fmt
+./scripts/clippy-lint.sh
+cargo clippy --fix
+```
+
+### UI
+```bash
+just generate-openapi        # after server changes
+just run-ui                  # start desktop
+cd ui/desktop && npm test    # test UI
+```
+
+## Structure
+```
+crates/
+├── goose             # core logic
+├── goose-bench       # benchmarking
+├── goose-cli         # CLI entry
+├── goose-server      # backend (binary: goosed)
+├── goose-mcp         # MCP extensions
+├── goose-test        # test utilities
+├── mcp-client        # MCP client
+├── mcp-core          # MCP shared
+└── mcp-server        # MCP server
+
+temporal-service/     # Go scheduler
+ui/desktop/           # Electron app
+```
+
+## Development Loop
+```bash
+# 1. source bin/activate-hermit
+# 2. Make changes
+# 3. cargo fmt
+# 4. cargo build
+# 5. cargo test -p <crate>
+# 6. ./scripts/clippy-lint.sh
+# 7. [if server] just generate-openapi
+```
+
+## Rules
+
+Test: Prefer tests/ folder, e.g. crates/goose/tests/
+Error: Use anyhow::Result
+Provider: Implement Provider trait see providers/base.rs
+MCP: Extensions in crates/goose-mcp/
+Server: Changes need just generate-openapi
+
+## Never
+
+Never: Edit ui/desktop/openapi.json manually
+Never: Edit Cargo.toml use cargo add
+Never: Skip cargo fmt
+Never: Merge without ./scripts/clippy-lint.sh
+
+## Entry Points
+- CLI: crates/goose-cli/src/main.rs
+- Server: crates/goose-server/src/main.rs
+- UI: ui/desktop/src/main.ts
+- Agent: crates/goose/src/agents/agent.rs
+
+## Brand Guidelines
+
+**IMPORTANT**: The product name "goose" should ALWAYS be written in lowercase "g" in all documentation, code comments, and user-facing content.
+
+- ✅ Correct: "goose", "using goose", "goose provides"
+- ❌ Incorrect: "Goose", "using Goose", "Goose provides"
+
+This is a brand guideline that must be strictly followed across all project content.