# AGENTS.md

## Project Purpose

This repository is a plugin-based C++ video analytics system for RK3588. Development should follow the existing DAG + plugin architecture instead of adding feature-specific shortcuts into the main process.

## Build and Verification Constraints

- This repository does not use local cross-compilation in the current workflow.
- Final build, link, runtime verification, and hardware-dependent testing must be executed on the RK3588 target device.
- Do not assume the current workstation can build or run RKNN, RGA, MPP, ZLMediaKit, or full media pipelines.
- Do not run full project builds by default on the current workstation unless the task explicitly requires it and the needed dependencies are confirmed to exist locally.
- Prefer static inspection and targeted platform-independent tests over speculative local builds.
- If a task depends on RK3588-only capabilities, state clearly what was reviewed locally and what still must be verified on the device.
- Do not claim that a hardware-related change is verified unless it was actually built and exercised on RK3588.

## Local Development Expectations

- Local work should focus on architecture, plugin boundaries, data structures, configuration, documentation, code review, and platform-independent tests.
- Local build attempts are allowed only when they are clearly useful and do not depend on missing RK3588 runtime libraries or device-only features.
- If local compilation is attempted, keep it scoped to the smallest useful target.
- Do not distort production code to satisfy the local machine environment.
- Do not remove or weaken RK3588-specific paths just because they are not runnable on the current workstation.

## Shell Environment Rules

- For agent-run shell commands on this workstation, use PowerShell 7.6 instead of Windows PowerShell 5.1.
- Prefer explicit invocation via `C:\Program Files\WindowsApps\Microsoft.PowerShell_7.6.0.0_x64__8wekyb3d8bbwe\pwsh.exe` when running commands.
- Do not rely on the system-default `powershell.exe` resolving to the desired version.

## Plugin and Architecture Rules

- New analytics capabilities should be implemented as plugins when they represent pipeline nodes.
- Reuse existing shared frame metadata and plugin interfaces where possible.
- If a new feature introduces a new semantic output type, define an explicit data model instead of encoding it into unrelated existing fields.
- Keep node responsibilities narrow. Detection, tracking, event reasoning, visualization, and alarming should remain separated unless there is a strong architectural reason not to.

## Testing and Validation Rules

- Prefer targeted unit tests for platform-independent logic.
- For RK3588-only features, document a device-side validation checklist instead of pretending local validation is sufficient.
- When a test or build cannot run locally because of platform constraints, say so explicitly in the final report.
- Separate validation into two buckets:
  - local code-level validation
  - RK3588 device-side validation
- Do not merge those two buckets into a single vague statement such as "verified" or "tested" without saying where verification happened.

## Communication Rules for Agents

- Say what is known from code inspection versus what still requires RK3588 device verification.
- Favor root-cause fixes over environment-specific patches.
- Keep recommendations aligned with the shortest path that preserves the architecture.