mirror of
https://github.com/sle118/squeezelite-esp32.git
synced 2026-04-02 19:30:20 +03:00
95 lines
3.4 KiB
Markdown
95 lines
3.4 KiB
Markdown
# AGENTS.md
|
|
|
|
This file is the default startup brief for Codex sessions in this repository.
|
|
Keep it short, directive, and high-signal.
|
|
|
|
## Mission
|
|
|
|
- Preserve platform behavior and stability.
|
|
- Prefer small, reversible changes over broad rewrites.
|
|
- Keep behavior unchanged unless a request explicitly asks for behavior changes.
|
|
|
|
## Working Scope
|
|
|
|
- Primary source code: `components/`, `main/`, `test/`.
|
|
- Build and release scripts: `build-scripts/`, `docker/`, `.github/workflows/`.
|
|
- Documentation: `documentation/`.
|
|
|
|
## Engineering Priorities
|
|
|
|
1. Correctness and safety.
|
|
2. Backward-compatible behavior.
|
|
3. Maintainability and clarity.
|
|
4. Build/test reproducibility.
|
|
5. Performance and footprint optimization.
|
|
|
|
Optimize in this order unless the task explicitly changes priorities.
|
|
|
|
## Do Not Edit By Default
|
|
|
|
- Vendor/external code:
|
|
- `components/esp-dsp/`
|
|
- `components/spotify/cspot/`
|
|
- `components/telnet/libtelnet/`
|
|
- `managed_components/`
|
|
- Build outputs and generated artifacts:
|
|
- `build/`
|
|
- `components/wifi-manager/webapp/dist/`
|
|
|
|
Only modify these paths when the task explicitly requires it.
|
|
|
|
## Behavioral Invariants
|
|
|
|
- Treat OTA/recovery reliability as a product-level contract.
|
|
- Treat partition layout as a fixed contract unless explicitly requested otherwise.
|
|
- Do not introduce platform-specific compile-time branches when runtime/config solutions are sufficient.
|
|
- Avoid unrelated churn; keep patches tightly scoped to the request.
|
|
|
|
## Standard Workflow
|
|
|
|
1. Read the request and identify touched modules and contracts.
|
|
2. Inspect current code and existing patterns in those modules.
|
|
3. Implement the smallest coherent patch that preserves contracts.
|
|
4. Run targeted validation commands.
|
|
5. Report changes, validation evidence, and residual risks.
|
|
|
|
## Validation Commands
|
|
|
|
- Style check: `build-scripts/lint_style.sh check`
|
|
- Style normalize: `build-scripts/lint_style.sh format`
|
|
- Firmware build (example): `idf.py build`
|
|
- Recovery footprint (platform-specific): `build-scripts/build_recovery_size.sh <platform|defaults-file> [build-dir]`
|
|
|
|
Use targeted checks first; avoid full-matrix builds unless requested.
|
|
|
|
## Testing Rule (Grounding)
|
|
|
|
- Tests should validate behavior contracts and invariants, not implementation details.
|
|
- Prefer module-boundary and regression tests over private-internal assertions.
|
|
- Every bug fix should include a regression test at the highest stable boundary possible.
|
|
- Use:
|
|
- `documentation/TESTING_CHARTER.md`
|
|
- `documentation/CONTRACT_TEST_TEMPLATE.md`
|
|
- `documentation/HARDWARE_TEST_MATRIX.md`
|
|
|
|
## Style Baseline
|
|
|
|
- Use repository formatting/lint settings as the source of truth.
|
|
- Do not introduce style-only churn outside task scope unless requested.
|
|
- During refactors, normalization is acceptable when intentionally planned.
|
|
|
|
## Frontend Context (Required)
|
|
|
|
- For any UI/API work involving `components/wifi-manager/webapp/` or `components/wifi-manager/http_server_handlers.c`, read:
|
|
- `documentation/agents/frontend_requirements_context.md`
|
|
- Treat that file as requirements-first context and keep it current.
|
|
- When frontend payload, routes, or protobuf contract changes, run:
|
|
- `build-scripts/ui_footprint_snapshot.sh`
|
|
- Then update `documentation/agents/frontend_requirements_context.md` in the same change.
|
|
|
|
## Agent Docs Layout
|
|
|
|
- Keep this file concise and policy-focused.
|
|
- Put detailed playbooks under `documentation/agents/`.
|
|
- Add module-specific guidance in local `AGENTS.md` files when needed (closest file to changed code takes precedence).
|