Two files, one repository
aaif-goose/goose ships 2 formats across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 22 | 3 | 0% |
| Commands | 0 | 12 | 0 | 0% |
| Section tags | 2 | 9 | 1 | 17% |
What each file covers
Sections
0 shared · 22 only in A · 3 only in B- − AGENTS Instructions
- − Contribution Workflow
- − Agent Loop Migration
- − Setup
- − Commands
- − Build
- − Test
- − Lint/Format
- − UI
- − Structure
- − Development Loop
- − 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
- − Code Quality
- − Never
- − Entry Points
- + Documentation Style Guide
- + Brand Guidelines
- + Context
Commands
0 shared · 12 only in A · 0 only in B- − cargo build
- − cargo build --release
- − just release-binary
- − cargo test
- − cargo test -p goose
- − cargo test --package goose --test mcp_integration_test
- − just record-mcp-tests
- − cargo fmt
- − cargo clippy --all-targets -- -D warnings
- − just run-ui
- − gh issue create
- − cargo add
Section tags
2 shared · 9 only in A · 1 only in B- − setup
- − build
- − test
- − architecture
- − git-pr
- − database
- − ui
- − do-not
- − agent-behaviour
- + docs
- lint-format
- code-style
Line diff
aaif-goose/goose · AGENTS.md
@@ −1 @@
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- Structure new issues on the matching template in `.github/ISSUE_TEMPLATE/` and set the issue type (e.g. Bug, Feature). `gh issue create` does not apply templates automatically.
16
17Maintainer-directed work, urgent security fixes, release automation, and local or exploratory changes do not require a Ready issue.
18
19## Agent Loop Migration
20
21We are replacing the legacy agent loop in `crates/goose/src/agents/agent.rs` with the state machine in `crates/goose/src/agents/state_machine/`. The state-machine path is enabled with `GOOSE_STATE_MACHINE=1`.
22
23Until the migration is complete, changes to agent-loop behavior must be implemented and tested in both paths. When reviewing code, check whether a change to either path also applies to the other and flag missing parity.
24
25## Setup
26```bash
27source bin/activate-hermit
28cargo build
29```
30
31## Commands
32
33### Build
34```bash
35cargo build # debug
36cargo build --release # release
37just release-binary # release binary
38```
39
40### Test
41```bash
42cargo test # all tests
43cargo test -p goose # specific crate
44cargo test --package goose --test mcp_integration_test
45just record-mcp-tests # record MCP
46```
47
48### Lint/Format
49```bash
50cargo fmt
51cargo clippy --all-targets -- -D warnings
52```
53
54### UI
55```bash
56just run-ui # start desktop
57cd ui/desktop && pnpm run typecheck
58cd ui/desktop && pnpm test # test UI
59```
60
61## Structure
62```
63crates/
64├── goose # core logic
65├── goose-acp-macros # ACP proc macros
66├── goose-cli # CLI entry
67├── goose-mcp # MCP extensions
68├── goose-test # test utilities
69└── goose-test-support # test helpers
70
71ui/desktop/ # Electron app
72```
73
74## Development Loop
75```bash
76# 1. source bin/activate-hermit
77# 2. Make changes
78# 3. cargo fmt
79```
80
81### Run these only if the user has asked you to build/test your changes:
82```
83# 1. cargo build
84# 2. cargo test -p <crate>
85# 3. cargo clippy --all-targets -- -D warnings
86```
87
88## Rules
89
90- Test: Prefer tests/ folder, e.g. crates/goose/tests/
91- Test: When adding features, update goose-self-test.yaml, rebuild, then run `goose run --recipe goose-self-test.yaml` to validate
92- Error: Use anyhow::Result
93- Provider: Implement Provider trait see providers/base.rs
94- MCP: Extensions in crates/goose-mcp/
95- UI Desktop: Use ACP SDK types or local `src/types/*` types. Do not import generated OpenAPI types/client code from `ui/desktop/src/api`
96
97## Code Quality
98
99- Comments: Write self-documenting code - prefer clear names over comments
100- Comments: Never add comments that restate what code does
101- Comments: Only comment for complex algorithms, non-obvious business logic, or "why" not "what"
102- Simplicity: Don't make things optional that don't need to be - the compiler will enforce
103- Simplicity: Booleans should default to false, not be optional
104- Errors: Don't add error context that doesn't add useful information (e.g., `.context("Failed to X")` when error already says it failed)
105- Simplicity: Avoid overly defensive code - trust Rust's type system
106- Logging: Clean up existing logs, don't add more unless for errors or security events
107
108## Never
109
110- Never: Recreate `ui/desktop/src/api` or add `@hey-api/openapi-ts` to `ui/desktop`
111- Cargo.toml: For human-authored dependency changes, use `cargo add` instead of manually editing dependency entries unless there is a specific reason not to.
112- Cargo.toml: Automated dependency bump PRs are exempt; when manual edits are necessary, keep `Cargo.lock` consistent.
113- Never: Skip cargo fmt
114- Never: Merge without running clippy
115- Never: Comment self-evident operations (`// Initialize`, `// Return result`), getters/setters, constructors, or standard Rust idioms
116- 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"
117
118## Entry Points
119- CLI: crates/goose-cli/src/main.rs
120- UI: ui/desktop/src/main.ts
121- Agent: crates/goose/src/agents/agent.rs
122
aaif-goose/goose · documentation/AGENTS.md
@@ +1 @@
1# Documentation Style Guide
2
3## Brand Guidelines
4
5**IMPORTANT**: The product name "goose" should ALWAYS be written in lowercase "g" in all documentation, blog posts, and any content within this documentation directory.
6
7- ✅ Correct: "goose", "using goose", "goose provides"
8- ❌ Incorrect: "Goose", "using Goose", "Goose provides"
9
10This is a brand guideline that must be strictly followed.
11
12## Context
13
14This rule applies to:
15- All markdown files in `/docs/`
16- All blog posts in `/blog/`
17- README files
18- Configuration files with user-facing text
19- Any other documentation content
20
21When editing or creating content in this documentation directory, always ensure "goose" uses a lowercase "g".
22
@@ −1 +1 @@
1−# AGENTS Instructions
1+# Documentation Style Guide
22
3−goose is an AI agent framework in Rust with CLI and Electron desktop interfaces.
3+## Brand Guidelines
44
5−## Contribution Workflow
5+**IMPORTANT**: The product name "goose" should ALWAYS be written in lowercase "g" in all documentation, blog posts, and any content within this documentation directory.
66
7−The 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).
7+- ✅ Correct: "goose", "using goose", "goose provides"
8+- ❌ Incorrect: "Goose", "using Goose", "Goose provides"
89
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−- Structure new issues on the matching template in `.github/ISSUE_TEMPLATE/` and set the issue type (e.g. Bug, Feature). `gh issue create` does not apply templates automatically.
10+This is a brand guideline that must be strictly followed.
1611
17−Maintainer-directed work, urgent security fixes, release automation, and local or exploratory changes do not require a Ready issue.
12+## Context
1813
19−## Agent Loop Migration
14+This rule applies to:
15+- All markdown files in `/docs/`
16+- All blog posts in `/blog/`
17+- README files
18+- Configuration files with user-facing text
19+- Any other documentation content
2020
21−We are replacing the legacy agent loop in `crates/goose/src/agents/agent.rs` with the state machine in `crates/goose/src/agents/state_machine/`. The state-machine path is enabled with `GOOSE_STATE_MACHINE=1`.
22−
23−Until the migration is complete, changes to agent-loop behavior must be implemented and tested in both paths. When reviewing code, check whether a change to either path also applies to the other and flag missing parity.
24−
25−## Setup
26−```bash
27−source bin/activate-hermit
28−cargo build
29−```
30−
31−## Commands
32−
33−### Build
34−```bash
35−cargo build # debug
36−cargo build --release # release
37−just release-binary # release binary
38−```
39−
40−### Test
41−```bash
42−cargo test # all tests
43−cargo test -p goose # specific crate
44−cargo test --package goose --test mcp_integration_test
45−just record-mcp-tests # record MCP
46−```
47−
48−### Lint/Format
49−```bash
50−cargo fmt
51−cargo clippy --all-targets -- -D warnings
52−```
53−
54−### UI
55−```bash
56−just run-ui # start desktop
57−cd ui/desktop && pnpm run typecheck
58−cd ui/desktop && pnpm test # test UI
59−```
60−
61−## Structure
62−```
63−crates/
64−├── goose # core logic
65−├── goose-acp-macros # ACP proc macros
66−├── goose-cli # CLI entry
67−├── goose-mcp # MCP extensions
68−├── goose-test # test utilities
69−└── goose-test-support # test helpers
70−
71−ui/desktop/ # Electron app
72−```
73−
74−## Development Loop
75−```bash
76−# 1. source bin/activate-hermit
77−# 2. Make changes
78−# 3. cargo fmt
79−```
80−
81−### Run these only if the user has asked you to build/test your changes:
82−```
83−# 1. cargo build
84−# 2. cargo test -p <crate>
85−# 3. cargo clippy --all-targets -- -D warnings
86−```
87−
88−## Rules
89−
90−- Test: Prefer tests/ folder, e.g. crates/goose/tests/
91−- Test: When adding features, update goose-self-test.yaml, rebuild, then run `goose run --recipe goose-self-test.yaml` to validate
92−- Error: Use anyhow::Result
93−- Provider: Implement Provider trait see providers/base.rs
94−- MCP: Extensions in crates/goose-mcp/
95−- UI Desktop: Use ACP SDK types or local `src/types/*` types. Do not import generated OpenAPI types/client code from `ui/desktop/src/api`
96−
97−## Code Quality
98−
99−- Comments: Write self-documenting code - prefer clear names over comments
100−- Comments: Never add comments that restate what code does
101−- Comments: Only comment for complex algorithms, non-obvious business logic, or "why" not "what"
102−- Simplicity: Don't make things optional that don't need to be - the compiler will enforce
103−- Simplicity: Booleans should default to false, not be optional
104−- Errors: Don't add error context that doesn't add useful information (e.g., `.context("Failed to X")` when error already says it failed)
105−- Simplicity: Avoid overly defensive code - trust Rust's type system
106−- Logging: Clean up existing logs, don't add more unless for errors or security events
107−
108−## Never
109−
110−- Never: Recreate `ui/desktop/src/api` or add `@hey-api/openapi-ts` to `ui/desktop`
111−- Cargo.toml: For human-authored dependency changes, use `cargo add` instead of manually editing dependency entries unless there is a specific reason not to.
112−- Cargo.toml: Automated dependency bump PRs are exempt; when manual edits are necessary, keep `Cargo.lock` consistent.
113−- Never: Skip cargo fmt
114−- Never: Merge without running clippy
115−- Never: Comment self-evident operations (`// Initialize`, `// Return result`), getters/setters, constructors, or standard Rust idioms
116−- 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"
117−
118−## Entry Points
119−- CLI: crates/goose-cli/src/main.rs
120−- UI: ui/desktop/src/main.ts
121−- Agent: crates/goose/src/agents/agent.rs
21+When editing or creating content in this documentation directory, always ensure "goose" uses a lowercase "g".
12222
