hird: Instructions file for Codex

AGENTS.md

This repository is maintained with help from AI coding agents (e.g. Codex/ChatGPT/Claude). This file defines how to make changes, what “done” means, and the project defaults we enforce.

North Star

• Keep core crates small, predictable, and long-lived.
• Prefer simple, explicit designs over clever ones.
• Avoid dependency creep; keep compile times and surface area under control.
• Optimize for long-term architecture over short-term compatibility; it’s OK to break callers to get the right core shape.

Non-negotiables (Definition of Done)

• cargo fmt passes.
• cargo clippy passes (-D warnings).
• Public APIs are documented (types/functions; public fields/variants where it matters).
• Tests updated/added when behavior changes.
• Examples/benchmarks live in separate top-level workspace crates (no extra dev-deps in core crates).
• Never reference tickets, ADRs, plans, phases, or agent sessions in code, comments, docstrings, or commit messages. These are project-management artifacts that rot. Code should justify itself; context belongs in the commit message or PR description, not in the source tree.

Suggested commands:

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

Before implementing a ticket

Before writing any code, read these files in order:

1. The assigned issue (bd show <id>).
2. DECISIONS.md — locked architecture constraints you must not violate.
3. phrasebook.md — canonical surface syntax conventions.
4. The parent epic ticket if one exists (for broader context and out-of-scope boundaries).

Rust workspace expectations

• MSRV is set in Cargo.toml (rust-version, currently 1.97); keep it compatible.
• Follow workspace lint policy (notably: unsafe_code = "deny" and missing_docs = "warn").

no_std policy (core crates)

• Default assumption for foundational crates: #![no_std] whenever practical (use extern crate alloc when needed).
• Keep std behind an explicit std feature flag when required.
• Avoid std collections in no_std crates; use hashbrown (and alloc types) instead.