blueclaw: Instructions file for Codex

AGENTS.md

These are the conventions this codebase holds itself to. Apply them to new code, and apply them to code you touch wherever that does not break consistency with its surroundings.

Core Principles

1. Readability is the highest priority - code should be self-explanatory
2. Functional style - prefer pure functions, avoid side effects
3. Efficiency - no redundant operations
4. Simplicity - minimal code that solves the problem

Single Source of Truth

• A shared vocabulary or contract (emoji names, enum options, capability names, component lists) consumed by more than one role, package, or service is defined exactly once; every consumer derives from that definition. Hand-maintained parallel copies are a defect: they drift (one list gains a value the other never sees) and every addition requires touching N places.
• When a consumer lives in another language and cannot import the definition, add a conformance test that reads the canonical source and fails on drift, instead of keeping a second hand-edited copy (chatd/tests/buzz-adapter.test.ts reads .dependency/blueprotocol/agentcontract/reaction_emoji.go).
• On discovering duplicated sources of truth, merge them as part of the change that touched them; do not extend a duplicate.

Working on this repository

Nothing lands on main by direct push. Branch, open a pull request, let the check run, merge.

Branch names

<type>/<subject-in-kebab-case> — the type is the same word the commit will carry, and the subject says what changes, not what you did to it.

feat/acp-context-injection
fix/approval-resume-after-restart
docs/tui-screenshots
refactor/turn-runner-split
test/completion-gate-evidence
chore/gofmt
ci/skip-docs-only-runs

Branch off main, rebase rather than merge when main moves under you, and delete the branch once the pull request is merged.

Commit messages

<type>: <what changes, imperative, lowercase, no trailing period>

<why it changes: the problem the reader would otherwise have to reconstruct.
Wrap at 72 columns. Say what you deliberately did not do.>