Esp Matter Mac

• Installation: references/01-installation.md
• Environment setup: references/02-environment-setup.md
• Commands: references/03-commands.md

📣 Emoji Output Rule (Mandatory)

For installer/setup/build command output:

• every line containing an emoji must be returned to the user
• do not collapse or hide emoji status lines

🔒 Mandatory Execution Context (Not Optional)

For every build/flash action:

• run environment setup and all idf.py commands in the same shell session
• do not split setup and build across separate shells

🔒 Mandatory Python Selection (Not Optional)

Before sourcing ESP scripts:

• ensure python3 resolves to a stable Homebrew/system Python (prefer /opt/homebrew/bin/python3.14, then 3.13/3.12/3.11)
• set ESP_PYTHON to that interpreter
• prepend the interpreter directory to PATH for the active shell session

🔒 Mandatory Command Order (Not Optional)

For all build and flash actions in ESP-Matter projects, apply the ESP-IDF mandatory sequence exactly.

Mandatory Build Sequence

1. Navigate to the target directory.
2. Run idf.py fullclean.
3. Resolve mandatory build parameters (see section below).
4. Run idf.py set-target with mandatory CMake args.
5. Run the requested build command with the same mandatory CMake args.

Mandatory Flash Sequence

1. Run idf.py erase-flash.
2. Run the flash command.
3. Run monitor (if requested).

Do not skip or reorder these steps.

🔒 fullclean Recovery Rule (Not Optional)

If idf.py fullclean fails with a non-CMake build directory message:

• delete <project>/build
• rerun idf.py fullclean
• then continue with set-target and build

🔒 Mandatory Build Parameters (Not Optional)

For Embedded Swift ESP-Matter builds, include these parameters in both set-target and build command:

• -DIDF_TARGET=<target>
• -DCMAKE_Swift_COMPILER=$HOME/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin/swiftc

For esp32c6, also set:

• ESP_MATTER_DEVICE_PATH=$HOME/esp/esp-matter/device_hal/device/esp32c6_devkit_c

🔒 Build Timing Baseline Rule (Not Optional)

For every build action:

• capture a start timestamp immediately before the build sequence starts
• capture an end timestamp immediately after the build finishes or fails
• calculate the elapsed build time and store it in the repository-local file .codex/build-times.json

The stored timing record must include at least:

• target project path
• target name
• build command kind (build, app, or uf2)
• start timestamp
• end timestamp
• elapsed seconds

Storage rule:

• keep only one timing record for each unique combination of target project path, target name, and build command kind
• when a new build finishes, replace the existing record for that combination instead of appending a new history entry

Before starting any build:

• check whether a previous timing record exists for the same target project path, target name, and build command kind
• if a previous timing record exists, treat silent periods as normal until previous elapsed time + 60 seconds
• during that baseline window, do not report concern, ask follow-up questions, or take recovery actions based only on lack of output
• if no previous timing record exists, fall back to the quiet-period guidance in references/03-commands.md

This timing baseline is for silence handling only:

• it does not permit ignoring real errors
• it does not skip required build steps
• it does not replace explicit process checks when a build appears hung past the baseline window

✅ Minimal Sequence

• enforce dependency order
• perform first-run install checks
• setup both environments for each build request
• enforce mandatory build/flash sequence from this skill and references/03-commands.md
• run requested command actions