AGENTS.md

1# AGENTS Instructions
2 
3goose is an AI agent framework in Rust with CLI and Electron desktop interfaces.
4 
5## Contribution Workflow
6 
7The 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).
8 
9- Before implementing an issue for a pull request, confirm that it is on the board with Status **Ready**.
10- Do not implement issues in **Inbox**, **Needs info**, or **Accepted / design**. Help resolve the issue discussion instead.
11- Read the agreed design, constraints, non-goals, and verification plan before changing code.
12- Keep the implementation within the issue's agreed scope.
13- If implementation reveals a material design change, return to the issue before continuing.
14- Every external pull request must link the Ready issue it implements and explain how the verification plan was performed.
15 
16Maintainer-directed work, urgent security fixes, release automation, and local or exploratory changes do not require a Ready issue.
17 
18## Setup
19```bash
20source bin/activate-hermit
21cargo build
22```
23 
24## Commands
25 
26### Build
27```bash
28cargo build                   # debug
29cargo build --release         # release  
30just release-binary           # release binary
31```
32 
33### Test
34```bash
35cargo test                   # all tests
36cargo test -p goose          # specific crate
37cargo test --package goose --test mcp_integration_test
38just record-mcp-tests        # record MCP
39```
40 
41### Lint/Format
42```bash
43cargo fmt
44cargo clippy --all-targets -- -D warnings
45```
46 
47### UI
48```bash
49just run-ui                  # start desktop
50cd ui/desktop && pnpm run typecheck
51cd ui/desktop && pnpm test   # test UI
52```
53 
54## Structure
55```
56crates/
57├── goose              # core logic
58├── goose-acp-macros   # ACP proc macros
59├── goose-cli          # CLI entry
60├── goose-mcp          # MCP extensions
61├── goose-test         # test utilities
62└── goose-test-support # test helpers
63 
64ui/desktop/            # Electron app
65```
66 
67## Development Loop
68```bash
69# 1. source bin/activate-hermit
70# 2. Make changes
71# 3. cargo fmt
72```
73 
74### Run these only if the user has asked you to build/test your changes:
75```
76# 1. cargo build
77# 2. cargo test -p <crate>
78# 3. cargo clippy --all-targets -- -D warnings
79```
80 
81## Rules
82 
83- Test: Prefer tests/ folder, e.g. crates/goose/tests/
84- Test: When adding features, update goose-self-test.yaml, rebuild, then run `goose run --recipe goose-self-test.yaml` to validate
85- Error: Use anyhow::Result
86- Provider: Implement Provider trait see providers/base.rs
87- MCP: Extensions in crates/goose-mcp/
88- UI Desktop: Use ACP SDK types or local `src/types/*` types. Do not import generated OpenAPI types/client code from `ui/desktop/src/api`
89 
90## Code Quality
91 
92- Comments: Write self-documenting code - prefer clear names over comments
93- Comments: Never add comments that restate what code does
94- Comments: Only comment for complex algorithms, non-obvious business logic, or "why" not "what"
95- Simplicity: Don't make things optional that don't need to be - the compiler will enforce
96- Simplicity: Booleans should default to false, not be optional
97- Errors: Don't add error context that doesn't add useful information (e.g., `.context("Failed to X")` when error already says it failed)
98- Simplicity: Avoid overly defensive code - trust Rust's type system
99- Logging: Clean up existing logs, don't add more unless for errors or security events
100 
101## Never
102 
103- Never: Recreate `ui/desktop/src/api` or add `@hey-api/openapi-ts` to `ui/desktop`
104- Cargo.toml: For human-authored dependency changes, use `cargo add` instead of manually editing dependency entries unless there is a specific reason not to.
105- Cargo.toml: Automated dependency bump PRs are exempt; when manual edits are necessary, keep `Cargo.lock` consistent.
106- Never: Skip cargo fmt
107- Never: Merge without running clippy
108- Never: Comment self-evident operations (`// Initialize`, `// Return result`), getters/setters, constructors, or standard Rust idioms
109- Never: Overwrite a live binary in place (e.g. `cp`/`fs.copyFileSync` onto an existing executable) - unlink or atomic-rename the destination first, otherwise macOS SIGKILLs running processes with "Code Signature Invalid"
110 
111## Entry Points
112- CLI: crates/goose-cli/src/main.rs
113- UI: ui/desktop/src/main.ts
114- Agent: crates/goose/src/agents/agent.rs
115