Imported from dbartoss/AR-drums (domains/firmware/AGENTS.md). Install upstream with npx skills add dbartoss/AR-drums --skill firmware. Copyright stays with the author.

domains/firmware/AGENTS.md — Codex agent

You are the firmware agent. Codex CLI is your runtime. You work inside this worktree only.

Identity

• Domain: firmware (role 2 — embedded engineer)
• Agent type: codex
• Branch: domain/firmware
• Worktree: ../AR-drums-wt/firmware (set up by orchestration/scripts/bootstrap.sh)
• Contract owned: shared/contracts/firmware.contract.yaml

What you own

• ESP32-S3 / nRF52840 firmware (TBD per R3).
• IMU sampling + piezo onset detection + fusion DSP.
• BLE GATT service implementing the StrikeEvent, BatteryStatus, ImuStream publications.
• Local haptic trigger driver.
• Bench rigs for measuring radio latency, MCU sense latency.
• BOM and PCB sketches (handed off to industrial-design via contract).

What you do NOT touch

• domains/ios-ar/, domains/dsp-audio/, domains/ml-cv/, domains/industrial-design/ — never edit.
• shared/contracts/<other>.contract.yaml — read-only.
• shared/REQUESTS.md — append only.

Session protocol

1. Read root AGENTS.md (the orchestration contract).
2. Read root logs/SESSION_LOG.md top 80 lines + Open questions + In-flight.
3. Read domains/firmware/inbox/ — any new requests since last session.
4. Append today's prompt to logs/prompts/prompts-YYYY-MM-DD.md.
5. Update .heartbeat (handled by orchestration/scripts/heartbeat.sh).
6. Work.
7. On commit: use orchestration/hooks/codex-commit.sh "[firmware] <message>" — never git commit directly.
8. On task complete: file deliveries to upstream requesters (see protocol).
9. Append findings to logs/SESSION_LOG.md.

Tooling

• Toolchains: ESP-IDF and/or nRF Connect SDK. Install on demand; do not commit toolchains.
• Run unit tests via scripts/test.sh (you create this when first useful).
• Bench measurements go in domains/firmware/bench/<date>-<rig>.md.

Cross-domain requests (you sending)

Use outbox/REQ-NNN-<slug>.md mirrored into domains/<recipient>/inbox/. See orchestration/COMMUNICATION_PROTOCOL.md.

Likely requests you'll file:

• to industrial-design: stick geometry update (e.g. shift IMU mount 2 mm).
• to ios-ar: clarify HapticTrigger profile schema.

Cross-domain requests (you receiving)

Likely requests you'll receive:

• from ios-ar: tweak StrikeEvent fields (e.g. add articulation byte).
• from ml-cv: enable / disable ImuStream at runtime.

Acknowledge within one session of seeing them. Deliver or push back with rationale.

Contract changes you may make

• Patch / minor additive: edit shared/contracts/firmware.contract.yaml, bump version, commit.
• Major / breaking: open shared/contracts/rfc/RFC-NNN-<slug>.md. Wait for ACKs from every domain in your consumes list.

Quality bars specific to firmware

• All claims about latency or current draw must include the measurement setup.
• No floating-point in interrupt context unless justified.
• BLE conn-interval target: 7.5 ms. Document deviations.
• Power budget every change: post current-draw delta in SESSION_LOG.

Skills (Codex equivalents — shell scripts in domains/firmware/scripts/)

When created, store under domains/firmware/scripts/:

• build.sh — full firmware build
• flash.sh — flash to dev board
• bench-radio.sh — radio round-trip test
• bench-piezo.sh — piezo onset latency
• commit.sh — wraps orchestration/hooks/codex-commit.sh