agodianel/esp32-workbench

Reviews ESP32 firmware architecture for FreeRTOS safety, memory and stack sizing, ISR rules, error handling, peripheral and pin safety, networking, storage, logging and build configuration, and returns a PASS / PASS WITH NOTES / FAIL report. Use when the user asks to "review the architecture", "code review this firmware", "is this RTOS-safe", "check for race conditions", "audit task stacks", "memory leak", "heap fragmentation", "stack overflow risk", "/arch-review", or before merging a significant ESP-IDF change or inheriting an existing ESP32 project.

Diagnoses and fixes ESP-IDF build, link, CMake/Kconfig, component-manager and flashing failures, using the build log to classify the error before changing anything. Use when "idf.py build fails", "undefined reference to", "No such file or directory" for a header, "Failed to resolve component", "CMake Error", "multiple definition of", "region `iram0_0_seg' overflowed", "app partition is too small", "implicit declaration of function", "esptool Failed to connect", "Wrong boot mode detected", "No serial data received", "Permission denied /dev/ttyUSB0", "A fatal error occurred", "set-target", or after an ESP-IDF version upgrade (v4 → v5) breaks the build.

Decodes and analyses ESP32-family panics — Guru Meditation errors, register dumps, backtraces, aborts, stack overflows and watchdog timeouts on both Xtensa (ESP32, S2, S3) and RISC-V (C2, C3, C5, C6, H2, P4) chips — to find the root cause and recommend a fix plus diagnostic config. Use when the user pastes a crash or says "Guru Meditation", "LoadProhibited", "StoreProhibited", "InstrFetchProhibited", "IllegalInstruction", "Load access fault", "Store access fault", "MEPC", "MTVAL", "EXCVADDR", "Backtrace:", "abort() was called", "Stack canary watchpoint triggered", "Interrupt wdt timeout", "Task watchdog got triggered", "crash loop", "/review-crash", or "decode this backtrace".

Creates a mission file and an implementation contract (scope, affected files, risks, tests, rollback) that must be accepted before any ESP32 firmware code is changed. Use when the user asks to "add a feature", "implement", "fix a bug", "refactor", "write a contract", "start a mission", "plan this change", "/contract", or "resume the mission" in an ESP-IDF, ESP32, ESP32-S3, ESP32-C3 or ESP32-C6 project, and before editing any firmware source.

Parses and classifies ESP32 serial monitor output — reset reasons, boot loops, panics, watchdog messages, brownouts, heap failures, Wi-Fi/BLE/MQTT errors and peripheral timeouts — and produces a triage report with a root-cause hypothesis and next steps. Use when the user pastes "idf.py monitor" output or a serial log, or says "boot loop", "keeps rebooting", "rst:0x", "Brownout detector was triggered", "Task watchdog got triggered", "Wi-Fi keeps disconnecting", "WIFI_EVENT_STA_DISCONNECTED", "BLE won't connect", "MQTT disconnects", "/triage-log", or "what does this log mean" for any ESP32-family chip.

Guides bring-up and debugging of ESP32 peripherals — I2C, SPI, UART, ADC and LEDC/PWM — using the ESP-IDF v5 driver APIs, chip-correct pin choices, and a step-by-step wiring → config → probe → speed-up procedure. Use when the user says "I2C sensor not responding", "i2c ESP_ERR_TIMEOUT", "no ACK", "I2C scan finds nothing", "SPI returns 0xFF", "SPI display blank", "UART garbage characters", "uart_read_bytes returns nothing", "ADC reads wrong value", "adc_oneshot", "analogRead with Wi-Fi", "PWM / LEDC not working", "set duty", "bring up a new sensor", or "connect a peripheral" on ESP32, ESP32-S3, ESP32-C3, ESP32-C6 or other Espressif chips.

Audits GPIO assignments in ESP32-family firmware against the verified pin facts of the actual target chip and board, flagging flash/PSRAM pins, strapping pins, input-only pins, USB-Serial-JTAG and UART0 console pins, JTAG pins, ADC2/Wi-Fi conflicts, double assignments and pin-map drift. Use when the user asks "which pins can I use", "is GPIO 12 safe", "check my pinout", "pin conflict", "strapping pin", "board won't boot after wiring", "can't flash after connecting a sensor", "ADC2 with Wi-Fi", "input-only pin", "/pin-audit", or before adding any GPIO, I2C, SPI, UART, ADC or LEDC code on ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2 or ESP32-P4.

Prepares a reviewable pull request for an ESP32 firmware change with summary, affected files, target chip, test evidence, static-check output, risk assessment, rollback plan and links to the mission and implementation contract. Use when the user says "prepare the PR", "write the PR description", "open a pull request", "ready for review", "/prcraft", "summarize my changes for review", or "mark the mission done" after implementing and testing an ESP-IDF change.

Runs a production-readiness review of ESP32 firmware — sdkconfig hardening, partition table and app-size headroom, OTA and rollback, secure boot, flash and NVS encryption, debug interfaces, logging and versioning — and returns a GO / NO-GO report with evidence. Use when the user asks "is this ready to ship", "release checklist", "production build", "prepare firmware release", "review sdkconfig", "check partition table", "OTA rollback", "secure boot", "flash encryption", "disable JTAG", "app partition too small", "/release-check", or before tagging a firmware release for ESP32, ESP32-S3, ESP32-C3, ESP32-C6 or other Espressif chips.

Scans an ESP-IDF or PlatformIO firmware repository and produces a scout report of target chip, components, dependencies, pin usage, FreeRTOS tasks and risks before any change is planned. Use when the user says "scout the repo", "explain this firmware project", "what does this ESP32 project do", "map the components", "onboard me", "where is app_main", or before writing a mission or implementation contract on an unfamiliar ESP32, ESP32-S3, ESP32-C3, ESP32-C6 or other Espressif codebase.

Generates a layered test plan for an ESP32 firmware change — static checks, host-side pytest/C logic, ESP-IDF Unity tests on target, pytest-embedded integration — with positive, negative, boundary, concurrency and error cases and explicit pass/fail evidence. Use when the user asks for a "test plan", "how do I test this", "what tests do I need", "unit tests for this component", "pytest-embedded", "Unity test", "hardware-in-the-loop", "/test-plan", or after an implementation contract is accepted for ESP32, ESP32-S3, ESP32-C3, ESP32-C6 or other ESP-IDF projects.