Goose Agent Rules

An extensible AI agent with a Rust core, command-line interface, and Electron desktop app.

Overview

Goose checks whether an issue is ready before implementation and records constraints from its Rust desktop app. The guide covers old and new agent loops running side by side, a retiring MCP directory, and a macOS failure caused by overwriting a running executable.

Contribution etiquette Verification by change type Hard prohibitions

Documents

├── 
├──  · imports AGENTS.md
├── .github
│   └── ISSUE_TEMPLATE
│       └──  — Matching issue template
├── documentation
│   ├── 
│   └──  · same content as CLAUDE.md · imports AGENTS.md
└── ui
    └── text
        └──

Techniques in this file

01 / Contribution etiquette

Require an agreed plan before implementing external work

The contribution workflow requires a Ready issue with design, constraints, non-goals, and verification already recorded. A material design change sends implementation back to the issue discussion.

13- If implementation reveals a material design change, return to the issue before continuing.

02 / Verification by change type

Maintain behavioral parity during a migration

The guide identifies the legacy loop and the state-machine replacement. Until migration is complete, an agent must implement and test applicable behavior in both paths.

43Until 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.

03 / Contribution etiquette

Freeze additions without blocking migration maintenance

The old MCP directory accepts no new third-party entries, but maintenance and removals remain allowed. This states the migration direction without freezing legacy data.

25- Treat the existing goose directory as legacy data while registry-backed discovery and installation are implemented.

04 / Hard prohibitions

Attach an operating-system failure to a file-operation rule

The Never section forbids overwriting a live executable and names unlinking or atomic rename as alternatives. It explains that macOS can kill running processes because the code signature becomes invalid.

130- 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"