Alex Hancock
101 lines
3.1 KiB
Markdown
101 lines
3.1 KiB
Markdown
# 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 binary
|
|
```
|
|
|
|
### 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
|
|
cargo clippy --all-targets -- -D warnings
|
|
```
|
|
|
|
### UI
|
|
```bash
|
|
just run-ui # start desktop
|
|
cd ui/desktop && pnpm run typecheck
|
|
cd ui/desktop && pnpm test # test UI
|
|
```
|
|
|
|
## Structure
|
|
```
|
|
crates/
|
|
├── goose # core logic
|
|
├── goose-acp-macros # ACP proc macros
|
|
├── goose-cli # CLI entry
|
|
├── goose-mcp # MCP extensions
|
|
├── goose-test # test utilities
|
|
└── goose-test-support # test helpers
|
|
|
|
ui/desktop/ # Electron app
|
|
```
|
|
|
|
## Development Loop
|
|
```bash
|
|
# 1. source bin/activate-hermit
|
|
# 2. Make changes
|
|
# 3. cargo fmt
|
|
```
|
|
|
|
### Run these only if the user has asked you to build/test your changes:
|
|
```
|
|
# 1. cargo build
|
|
# 2. cargo test -p <crate>
|
|
# 3. cargo clippy --all-targets -- -D warnings
|
|
```
|
|
|
|
## Rules
|
|
|
|
- Test: Prefer tests/ folder, e.g. crates/goose/tests/
|
|
- Test: When adding features, update goose-self-test.yaml, rebuild, then run `goose run --recipe goose-self-test.yaml` to validate
|
|
- Error: Use anyhow::Result
|
|
- Provider: Implement Provider trait see providers/base.rs
|
|
- MCP: Extensions in crates/goose-mcp/
|
|
- UI Desktop: Use ACP SDK types or local `src/types/*` types. Do not import generated OpenAPI types/client code from `ui/desktop/src/api`
|
|
|
|
## Code Quality
|
|
|
|
- Comments: Write self-documenting code - prefer clear names over comments
|
|
- Comments: Never add comments that restate what code does
|
|
- Comments: Only comment for complex algorithms, non-obvious business logic, or "why" not "what"
|
|
- Simplicity: Don't make things optional that don't need to be - the compiler will enforce
|
|
- Simplicity: Booleans should default to false, not be optional
|
|
- Errors: Don't add error context that doesn't add useful information (e.g., `.context("Failed to X")` when error already says it failed)
|
|
- Simplicity: Avoid overly defensive code - trust Rust's type system
|
|
- Logging: Clean up existing logs, don't add more unless for errors or security events
|
|
|
|
## Never
|
|
|
|
- Never: Recreate `ui/desktop/src/api` or add `@hey-api/openapi-ts` to `ui/desktop`
|
|
- Cargo.toml: For human-authored dependency changes, use `cargo add` instead of manually editing dependency entries unless there is a specific reason not to.
|
|
- Cargo.toml: Automated dependency bump PRs are exempt; when manual edits are necessary, keep `Cargo.lock` consistent.
|
|
- Never: Skip cargo fmt
|
|
- Never: Merge without running clippy
|
|
- Never: Comment self-evident operations (`// Initialize`, `// Return result`), getters/setters, constructors, or standard Rust idioms
|
|
|
|
## Entry Points
|
|
- CLI: crates/goose-cli/src/main.rs
|
|
- UI: ui/desktop/src/main.ts
|
|
- Agent: crates/goose/src/agents/agent.rs
|