maze32/AGENTS.md

ChatGPT project context

This directory is a local mirror of the ChatGPT project “maze32”.

• Treat every file under sources/ as read-only reference material.
• Do not edit, rename, move, or delete synced project files.
• These files may be replaced the next time a task is created from this ChatGPT project.

Project instructions

Language

• Write all canonical documentation in English.
• Write source comments, test names, protocol identifiers, and system log messages in English.
• Write all player-facing browser UI copy, game messages, and user-visible browser errors in Russian.

Canonical documents

• MVP.md defines product scope, gameplay rules, and MVP acceptance criteria.
• ARCHITECTURE.md defines implementation contracts and technical boundaries.
• PLANS.md defines the current implementation milestone and its evidence.
• docs/BOARD_PASSPORT.md defines confirmed hardware facts and explicit unknowns.
• docs/UI_STYLE.md defines the canonical browser visual language, responsive layout, controls, and presentation behavior.
• Files under sources/ remain read-only references and are never canonical implementation files.

When documents disagree, stop and resolve the conflict before implementation. Do not silently choose one requirement over another.

Milestone workflow

• Follow PLANS.md strictly.
• Milestones may be planned and added to PLANS.md in batches.
• Number milestones from 1 without gaps using Milestone 001, Milestone 002, and so on.
• Execute milestones strictly in ascending numerical order.
• Do not start a milestone until every preceding milestone is COMPLETE.
• Keep at most one milestone IN_PROGRESS.
• Append newly discovered milestones to the end of PLANS.md; do not insert or renumber existing milestones without explicit project-owner approval.
• Every milestone must include objective, scope, deliverables, acceptance criteria, evidence, and status.
• Do not mark a milestone COMPLETE without concrete recorded evidence for every acceptance criterion.

Commit message handoff

• After completing every user prompt, provide a proposed commit message for the resulting changes. This is mandatory when completing a milestone.
• Use the Conventional Commits format type(scope): imperative summary, or type: imperative summary when no meaningful scope exists.
• Choose exactly one appropriate type from feat, fix, refactor, perf, test, docs, style, build, ci, chore, or revert.
• Write the commit message in English, use an imperative summary beginning with a lowercase verb, keep the subject at 72 characters or fewer when practical, and do not end it with a period.
• Base the message on the actual completed changes and milestone outcome; do not use vague summaries such as update files or make changes.
• Present the proposed commit message in the final response, but do not create the Git commit unless the user explicitly requests it.

Locked platform baseline

• Target ESP32-C6FH4 with 4 MB Flash.
• Do not require PSRAM.
• Use PlatformIO with espressif32@7.0.1, ESP-IDF, and the compatible esp32-c6-devkitm-1 board profile.
• Use partitions.csv and sdkconfig.defaults from the project root.
• Do not add an OTA partition for MVP.
• Do not assume a board GPIO map, built-in LED, or exact commercial PCB model.

Architectural invariants

• The ESP is the sole authoritative owner of lobby and match state.
• Browsers send commands and render server-approved projections; they do not decide movement, inventory, timers, visibility, or results.
• Never serialize hidden maze or object state to player clients.
• Observer sessions are read-only.
• Bound all connection counts, message sizes, queues, retries, and allocations.
• Active game state need not survive reboot; Wi-Fi configuration must persist in NVS.

Code style

• Follow the repository .clang-format.
• Format all modified C and C++ files with clang-format.
• Prefer simple, explicit code that is easy for beginners to read.
• Avoid clever one-liners and unnecessary abstractions.
• Use braces for all non-trivial control-flow blocks.
• Prefer descriptive variable and function names.
• Keep functions reasonably small.

Build and verification

• Parse the project configuration with pio project config after changing platformio.ini.
• Build with pio run once firmware sources exist.
• Add host-side deterministic tests for portable game logic before relying only on device tests.
• Verify the final application and filesystem sizes against partitions.csv.
• Test on the physical board before recording hardware acceptance evidence.
• Preserve exact commands and relevant outputs in the active milestone's evidence section.