mecha: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working in this repository.

Read CLAUDE.md first, in full. It holds the cross-cutting invariants any session needs on any run, and this file deliberately does not duplicate it. docs/ARCHITECTURE.md records why each subsystem is shaped the way it is — the incident behind each invariant, and the bug that reappears when one is undone; read its section before changing a subsystem. That reasoning is what you need in order to change something safely, and it is not recoverable from the code alone.

CONTRIBUTING.md covers build commands, the testing layers, and pull request expectations.

Orientation

mecha-core/     the library; knows nothing about any CLI or application
mecha-cli/      the `mecha` binary; thin, all logic belongs in core
mecha-mail/     library plus three MCP binaries for mail and calendar
mecha-slack/    the Slack transport; has no mecha-core dependency, and must
                never gain one — that is why it is a crate and not a module
eval/           the case set and its fixtures
website/        the Docusaurus documentation site
docs/           design and research notes, not user documentation
results/        local only (untracked since 2026-10-04): run output and scorecards, on the operator's disk

Four workspace members, all published to crates.io. A new one that anything published depends on must be added to the release workflow's publish list in the same change that introduces it.

Before you start

cargo build --workspace --all-targets
cargo test --workspace

Both should pass on a clean checkout. If they do not, fix that before making changes — you cannot tell your breakage from pre-existing breakage otherwise.

Before you finish

cargo fmt --all
cargo clippy --all-targets --all-features
cargo test --workspace

CI treats warnings as errors, so a clippy warning will fail the build.

The traps