CLAUDE.md - third_party/github/hathach/tinyusb - Git at Google

 # TinyUSB Agent Instructions

 ## Working Rules

 Bias toward caution over speed. For trivial tasks, use judgment.

 - Think first — state assumptions; ask if unclear; when a choice matters, name it and recommend one rather than picking silently or surveying every option.
 - Simplicity — Follow YAGNI. Reuse existing code, standard-library, and native-platform features before adding dependencies or abstractions. Prefer the smallest clear solution, but never sacrifice correctness, safety, or necessary tests.
 - Surgical changes — touch only what the task requires; match existing style; don't refactor working code; mention unrelated dead code rather than deleting it. Remove only orphans your changes created.
 - Goal-driven — turn tasks into verifiable goals ("write failing test, make it pass"). For multi-step work, state a brief `step → verify` plan.
 - Assume the dev machine is configured. Run commands directly; troubleshoot setup only when a command fails.
 - **Worktrees** — For branch or multi-step work: `git worktree add .worktrees/<branch> -b <branch>`; never switch the primary checkout. Symlink `deps_all` paths from `tools/get_deps.py` to the primary checkout; replace a symlink and rerun `get_deps.py` only for a different revision.
 - Hardware references — before register/bitfield/pinout/errata/timing claims or DCD/HCD changes, use `read-doc` to check Calibre first; report missing documents. Search its database, never the library tree.
 - Open-source behavior — when investigating an issue or understanding behavior (e.g. kernel, libusb, OpenOCD; usbfs, usbtest, sysfs attributes, device locks, D state), read the source for the version in use rather than infer from symptoms.
 - Code references — boards: `hw/bsp/`, `docs/reference/boards.rst`; classes: `src/class/`; core/config: `src/tusb.h`, `src/tusb_option.h`, each example's `src/tusb_config.h`; build/deps: `tools/build.py`, `tools/get_deps.py`; unit tests: `test/unit-test/project.yml`.

 ## Code Rules

 - C99, 2-space indent, no tabs; `snake_case` helpers, `UPPER_CASE` macros, `tud_`/`tuh_` public APIs, `TU_` macros.
 - No dynamic allocation. Defer ISR work to task context. Use `TU_ASSERT()` for error checks; check return values.
 - Keep headers self-contained with `#if CFG_TUSB_MCU` guards. Include order: C stdlib → tusb common → drivers → classes.

 ## Skills

 - When creating or editing skills, put deterministic, checkable mechanics in `.claude/skills/<name>/scripts/`; keep judgment and usage in `SKILL.md`, without duplicating script logic.
 - Scripts must fail explicitly rather than guess; report ambiguous alternatives for the caller to choose.
 - Test new or substantially changed scripts in `.claude/test/test_*.py`; add tests to untested older scripts when touched.

 ## Claude and Codex Collaboration

 - Keep `CLAUDE.md` and `.claude/{agents,skills,workflows}` canonical; preserve `AGENTS.md -> CLAUDE.md` and `.agents -> .claude`.
 - For a standalone Codex session, use `.codex/agents/<role>.toml` to load `.claude/agents/<role>.md`; keep adapters thin and never duplicate role bodies.
 - Exception: `code-simplifier` wraps bundled `/simplify` in Claude; Codex keeps its standalone equivalent in TOML.
 - Use `/codex:review` for independent read-only review, `/codex:adversarial-review` to challenge a design, and `/codex:rescue` for bounded implementation or diagnosis.
 - Concurrent writers need separate worktrees; otherwise yield the worktree until delegated edits finish.
 - Use `peer-agent` for read-only consultation with another agent session in this worktree; it is a peer, not a subagent.
 - Keep orchestration in `.claude/workflows/`. Use `code-verify` with `provider: 'codex'` (default), `'claude'`, or `'all'`; `validate`/`full-check` use `reviewProvider`; `pr-babysit` has an independent model challenge every dismissal before it is posted. Keep workflow nesting to one level.
 - Delegate Codex workflow jobs through `.claude/agents/codex-agent.md`; `.claude/codex-agent.py` enforces the allowed roles. Its read-only sandbox has no network: jobs must use local evidence, since failed network reads can produce false empty results. Write-capable roles need worktree isolation first.

 ## Build and Validate

 Build all examples for a board from the repo root; preserve `cmake-build-<board>` for HIL:

 ```bash
 cmake -S examples -B examples/cmake-build-adafruit_metro_rp2350 -DBOARD=adafruit_metro_rp2350 -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel
 cmake --build examples/cmake-build-adafruit_metro_rp2350
 ninja -C examples/cmake-build-adafruit_metro_rp2350 cdc_msc-jlink    # Flash with J-Link
 ninja -C examples/cmake-build-adafruit_metro_rp2350 cdc_msc-openocd  # Or OpenOCD
 ```

 - Single example after configuring above: `cmake --build examples/cmake-build-adafruit_metro_rp2350 --target cdc_msc`.
 - ESP-IDF: `. "$IDF_PATH/export.sh"` before build/flash/monitor; run `idf.py -DBOARD=<board> build` in the ESP-IDF example.
 - Debug/logging: `-DCMAKE_BUILD_TYPE=Debug -DLOG=2 -DLOGGER=rtt`.
 - Before submitting: `pre-commit run --all-files` (includes unit tests).
 - For code changes: build the full example set for boards that exercise the changed modules. Add fuzz/HIL coverage for parsers or protocol state machines.
 - Validate device runtime on hardware; a successful build alone does not establish runtime correctness.
 - After board/dependency changes, regenerate docs with `build-doc`.
 - Before committing code changes, verify size impact with `code-size`.

 ## PRs and Follow-ups

 - Before opening or updating a PR, follow Build and Validate; use `pre-pr` when workflows are available.
 - Use imperative commit/PR subjects; keep scope focused, link relevant issues, and include test/build evidence.
 - After opening a PR, use `pr-babysit` (`.claude/workflows/pr-babysit.js`) to drive reviews and CI to green. If workflows are unavailable, use `gh pr checks <num>` and `gh pr view <num> --comments`; fix failures, push, and resolve review threads.
 - **Deferred work** — Separate scope gets a separate PR/session. Create one GitHub issue per topic with `gh issue create --label followup`; link the originating PR and preserve the full handoff in the issue body, including evidence, remaining work, and why deferred. Add revalidation, new findings, and changes to remaining work as issue comments. Close the issue when its implementing PR lands.
	# TinyUSB Agent Instructions

	## Working Rules

	Bias toward caution over speed. For trivial tasks, use judgment.

	- Think first — state assumptions; ask if unclear; when a choice matters, name it and recommend one rather than picking silently or surveying every option.
	- Simplicity — Follow YAGNI. Reuse existing code, standard-library, and native-platform features before adding dependencies or abstractions. Prefer the smallest clear solution, but never sacrifice correctness, safety, or necessary tests.
	- Surgical changes — touch only what the task requires; match existing style; don't refactor working code; mention unrelated dead code rather than deleting it. Remove only orphans your changes created.
	- Goal-driven — turn tasks into verifiable goals ("write failing test, make it pass"). For multi-step work, state a brief `step → verify` plan.
	- Assume the dev machine is configured. Run commands directly; troubleshoot setup only when a command fails.
	- Worktrees — For branch or multi-step work: `git worktree add .worktrees/<branch> -b <branch>`; never switch the primary checkout. Symlink `deps_all` paths from `tools/get_deps.py` to the primary checkout; replace a symlink and rerun `get_deps.py` only for a different revision.
	- Hardware references — before register/bitfield/pinout/errata/timing claims or DCD/HCD changes, use `read-doc` to check Calibre first; report missing documents. Search its database, never the library tree.
	- Open-source behavior — when investigating an issue or understanding behavior (e.g. kernel, libusb, OpenOCD; usbfs, usbtest, sysfs attributes, device locks, D state), read the source for the version in use rather than infer from symptoms.
	- Code references — boards: `hw/bsp/`, `docs/reference/boards.rst`; classes: `src/class/`; core/config: `src/tusb.h`, `src/tusb_option.h`, each example's `src/tusb_config.h`; build/deps: `tools/build.py`, `tools/get_deps.py`; unit tests: `test/unit-test/project.yml`.

	## Code Rules

	- C99, 2-space indent, no tabs; `snake_case` helpers, `UPPER_CASE` macros, `tud_`/`tuh_` public APIs, `TU_` macros.
	- No dynamic allocation. Defer ISR work to task context. Use `TU_ASSERT()` for error checks; check return values.
	- Keep headers self-contained with `#if CFG_TUSB_MCU` guards. Include order: C stdlib → tusb common → drivers → classes.

	## Skills

	- When creating or editing skills, put deterministic, checkable mechanics in `.claude/skills/<name>/scripts/`; keep judgment and usage in `SKILL.md`, without duplicating script logic.
	- Scripts must fail explicitly rather than guess; report ambiguous alternatives for the caller to choose.
	- Test new or substantially changed scripts in `.claude/test/test_*.py`; add tests to untested older scripts when touched.

	## Claude and Codex Collaboration

	- Keep `CLAUDE.md` and `.claude/{agents,skills,workflows}` canonical; preserve `AGENTS.md -> CLAUDE.md` and `.agents -> .claude`.
	- For a standalone Codex session, use `.codex/agents/<role>.toml` to load `.claude/agents/<role>.md`; keep adapters thin and never duplicate role bodies.
	- Exception: `code-simplifier` wraps bundled `/simplify` in Claude; Codex keeps its standalone equivalent in TOML.
	- Use `/codex:review` for independent read-only review, `/codex:adversarial-review` to challenge a design, and `/codex:rescue` for bounded implementation or diagnosis.
	- Concurrent writers need separate worktrees; otherwise yield the worktree until delegated edits finish.
	- Use `peer-agent` for read-only consultation with another agent session in this worktree; it is a peer, not a subagent.
	- Keep orchestration in `.claude/workflows/`. Use `code-verify` with `provider: 'codex'` (default), `'claude'`, or `'all'`; `validate`/`full-check` use `reviewProvider`; `pr-babysit` has an independent model challenge every dismissal before it is posted. Keep workflow nesting to one level.
	- Delegate Codex workflow jobs through `.claude/agents/codex-agent.md`; `.claude/codex-agent.py` enforces the allowed roles. Its read-only sandbox has no network: jobs must use local evidence, since failed network reads can produce false empty results. Write-capable roles need worktree isolation first.

	## Build and Validate

	Build all examples for a board from the repo root; preserve `cmake-build-<board>` for HIL:

	```bash
	cmake -S examples -B examples/cmake-build-adafruit_metro_rp2350 -DBOARD=adafruit_metro_rp2350 -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel
	cmake --build examples/cmake-build-adafruit_metro_rp2350
	ninja -C examples/cmake-build-adafruit_metro_rp2350 cdc_msc-jlink # Flash with J-Link
	ninja -C examples/cmake-build-adafruit_metro_rp2350 cdc_msc-openocd # Or OpenOCD
	```

	- Single example after configuring above: `cmake --build examples/cmake-build-adafruit_metro_rp2350 --target cdc_msc`.
	- ESP-IDF: `. "$IDF_PATH/export.sh"` before build/flash/monitor; run `idf.py -DBOARD=<board> build` in the ESP-IDF example.
	- Debug/logging: `-DCMAKE_BUILD_TYPE=Debug -DLOG=2 -DLOGGER=rtt`.
	- Before submitting: `pre-commit run --all-files` (includes unit tests).
	- For code changes: build the full example set for boards that exercise the changed modules. Add fuzz/HIL coverage for parsers or protocol state machines.
	- Validate device runtime on hardware; a successful build alone does not establish runtime correctness.
	- After board/dependency changes, regenerate docs with `build-doc`.
	- Before committing code changes, verify size impact with `code-size`.

	## PRs and Follow-ups

	- Before opening or updating a PR, follow Build and Validate; use `pre-pr` when workflows are available.
	- Use imperative commit/PR subjects; keep scope focused, link relevant issues, and include test/build evidence.
	- After opening a PR, use `pr-babysit` (`.claude/workflows/pr-babysit.js`) to drive reviews and CI to green. If workflows are unavailable, use `gh pr checks <num>` and `gh pr view <num> --comments`; fix failures, push, and resolve review threads.
	- Deferred work — Separate scope gets a separate PR/session. Create one GitHub issue per topic with `gh issue create --label followup`; link the originating PR and preserve the full handoff in the issue body, including evidence, remaining work, and why deferred. Add revalidation, new findings, and changes to remaining work as issue comments. Close the issue when its implementing PR lands.