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

Correctness and safety.
Backward-compatible behavior.
Maintainability and clarity.
Build/test reproducibility.
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

Read the request and identify touched modules and contracts.
Inspect current code and existing patterns in those modules.
Implement the smallest coherent patch that preserves contracts.
Run targeted validation commands.
Report changes, validation evidence, and residual risks.
Commit hygiene: make small commits and push frequently when progress needs to be traceable by commit SHA across sessions/roles.

Commit hygiene scope:

each role Codex runtime is responsible for commit hygiene in its own repository (product repo for arch, infra repo for infra, runner repo for runner)

Ownership Contract (Arch Closure Rule)

When arch:codex is explicitly asked to "take ownership" of a task or workstream, arch:codex is accountable for driving it to closure:

closure means either:
- done with acceptance met and evidence recorded, or
- blocked with concrete blockers, owners, operator gates, and next actions recorded (not vague "waiting")
arch:codex may delegate execution to infra:codex / runner:codex, but must actively steer until closure (handoffs updated, blockers cleared or escalated, and the workstream status stabilized)
do not stop at "prepared a packet"; prepared packets are inputs to closure, not closure themselves

Exception:

arch:codex may stop early when a pivot is required or a problem solving loop is stalled, but only after recording a stable closure state:
- action_type=replan with the pivot proposal and updated next actions, or
- blocked with the specific stalled hypothesis, what was tried, and what new information is needed to proceed

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
- documentation/agents/ci_lane_contract.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.
For doc-only cleanup tasks, follow documentation/agents/document_gardening.md.

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/.
For progressive context discovery, start with:
- documentation/agents/start_here.md
For remote-role delegation (infra/runner), follow:
- documentation/agents/remote_delegation_contract.md (autonomous delegation + handshake + thread_ref correlation)
Add module-specific guidance in local AGENTS.md files when needed (closest file to changed code takes precedence).

Short-Term Goal Tracking (Ephemeral)

Active multi-agent implementation goals live under:
- documentation/short-term/active/
Coordination files live under:
- documentation/short-term/coordination/workstream_board.md
- documentation/short-term/coordination/handoff_log.md
When prompted to continue pending multi-agent work, read those files first and update them before ending the session.
Use role-based owner values in short-term boards:
- arch:<agent-id> for architecture/control-plane work
- infra:<agent-id> for infrastructure/host/VM work
- runner:<agent-id> for VM CI/CD execution work
Handoff entries for short-term goals should include:
- context (arch-local | infra-live | runner-live)
- action_type (scaffold | delegate | execute | replan)
- operator_required (yes | no)
Role-origin evidence naming should use prefixes where feasible:
- arch_*, infra_*, runner_*
User/operator reprioritization or path-shift requests (e.g. "we missed...", "easier way...", "we should prioritize...") should trigger a formal short-term replan update before continuing execution.
For ad-hoc user requests, proactively ask whether to track as a ticket (yes/no) and, when accepted, record it in documentation/short-term/coordination/ad_hoc_ticket_queue.md.
For local GitLab usage (git.lecsys.net), keep role secrets only in ${XDG_CONFIG_HOME:-$HOME/.config}/codex/credentials/gitlab/git.lecsys.net/ with directory mode 0700 and file mode 0600; never commit credential files or paste secret values in handoff logs.
Preserve CI lane boundary:
- upstream GitHub lane for build/non-hardware tests
- local LXD lane for hardware-in-loop execution
Repository boundary enforcement (strict):
- never edit or run role execution from arch against runner/infra repositories on this machine (for example /workspaces/codex-runner-agent, /workspaces/codex-infra-agent)
- all runner and infra workstreams must be executed by their remote Codex runtimes and reported back via handoff logs
Completion gate:
- Workstream done means that workstream acceptance is met.
- Goal completion is separate and requires every item in the goal deliverables checklist to be checked with evidence.
- Do not mark a goal complete or archive it while any deliverable checklist item remains unchecked.

7.6 KiB Raw Blame History