Add Project Guidance For Agents

2026-08-30 18:55:11 +02:00
parent c2c11fee4e
commit f227a2026f
5 changed files with 638 additions and 0 deletions
@@ -0,0 +1,44 @@
+# Agent instructions
+
+## Start with project memory
+
+1. Read `docs/agent/code-map.md` before broad repository exploration.
+2. Read the relevant sections of `docs/agent/architecture.md` and `docs/agent/design-decisions.md` before changing cross-cutting behavior.
+3. Read `docs/agent/current-state.md` when resuming work or investigating recent changes.
+4. Use these files to identify the smallest relevant source set before searching or reading code.
+5. Verify stored knowledge against implementation whenever it may be stale or correctness depends on exact behavior. Source code is authoritative.
+6. Do not repeatedly scan unrelated modules. Prefer targeted symbol searches and representative header/implementation reads.
+7. Update durable agent documentation only when architecture, contracts, ownership, or module responsibilities genuinely change.
+8. During long-running tasks, keep `docs/agent/current-state.md` current and update it before handoff or context compaction.
+9. Keep temporary debugging notes and speculative hypotheses out of `architecture.md` and `design-decisions.md`; use `current-state.md` instead.
+10. Treat `GPT-logs/` as non-authoritative history. Confirm any useful claim against current source.
+11. Avoid `managed_components/`, `third_party/`, generated `src/web_assets_data.*`, compressed assets, minified libraries, `compile_commands.json`, `dependencies.lock`, and broad `sdkconfig.*` inspection unless the task specifically requires them.
+
+## Project constraints
+
+- This is ESP-IDF firmware for one physical UART1/MAX3243 RS-232 port shared through USB CDC, HTTPS/WebSocket, and SSH.
+- Preserve the broker model: exactly one writer, multiple isolated observers.
+- Preserve UART0 as the administrative recovery path and native USB as network-independent UART1 access when network services fail.
+- Keep serial transport binary-transparent; do not add in-band control sequences.
+- Treat bounded queues, buffers, task ownership, generation tokens, and failure isolation as correctness properties, not incidental implementation details.
+- Never expose passwords, private keys, Wi-Fi secrets, ticket values, or verifier material through routine status, logs, completion, or the local display.
+- Do not regenerate embedded web assets unless the task explicitly requires it. See `web_assets/SOURCES.md` for provenance and generation policy.
+
+## Build and device commands
+
+The normal build, verified from `platformio.ini` and `README.md`, is:
+
+```sh
+pio run
+```
+
+Upload and monitor commands documented by the project are:
+
+```sh
+pio run --target upload
+pio device monitor -b 115200
+```
+
+A first migration to the custom partition table may require `pio run --target erase`, but erasing destroys persisted configuration and credentials. Never run it without explicit user approval.
+
+No automated host test command is defined in the repository. Hardware validation procedures live in `docs/electrical_tests.md` and `docs/user_administration_tests.md`; do not claim they passed unless actually performed.