# EVOLV Agent Guide (AGENTS.md)

## Project Summary
EVOLV is a modular Node-RED package bundling multiple custom control/automation nodes (primarily under `nodes/`) for wastewater/process applications.

## Repository Layout
- `package.json`: Root package metadata + `node-red.nodes` map that tells Node-RED which node entrypoints to load.
- `nodes/<nodeName>/`: A Node-RED node module (often a git submodule).
  - `<nodeName>.js`: Node-RED runtime entry (registers the node and exposes admin endpoints).
  - `<nodeName>.html`: Node-RED editor UI definition for the node.
  - `src/`: Node implementation classes and logic.
  - `test/`: Node-level tests (`basic/`, `integration/`, `edge/`, optional `helpers/`).
  - `examples/`: Import-ready Node-RED example flows (`basic.flow.json`, `integration.flow.json`, `edge.flow.json`) and `examples/README.md`.
- `nodes/generalFunctions/`: Shared utilities used by most nodes (logger/config/menu helpers, etc).
- `node_modules/`: Local install output; do not edit.

## Agent Knowledge Base
- `.agents/`: Root directory for repository-specific agent definitions and knowledge base content (non-runtime/support assets, not Node-RED production code).
- `.agents/skills/`: EVOLV specialist skills (domain instructions, workflows, and orchestrator logic).
- When tasks involve domain reasoning or specialist routing, prefer `.agents/skills/*/SKILL.md` as the primary in-repo source of guidance.

## Agent Invocation Policy
- Default: always invoke orchestrator first via `.agents/skills/evolv-orchestrator/SKILL.md`.
- Orchestrator decides specialist selection, task decomposition, execution order, and integration checks.
- `team` keyword policy:
  - When the user says `team`, treat the request as orchestrator-led multi-specialist work.
  - The orchestrator must choose the best-fit specialists for the task (minimum set that covers all required domains).
  - Specialists must perform an internal alignment pass before any user-facing conclusion:
    - share assumptions
    - reconcile conflicts/tradeoffs
    - agree on a single integrated recommendation (or document explicit dissent)
  - Return one consolidated conclusion with:
    - recommended plan
    - risks and tradeoffs
    - unresolved disagreements (if any)
- For any change inside `nodes/*` that affects Node-RED runtime/editor behavior, always load `.agents/skills/evolv-frontend-node-red/SKILL.md` before editing.
- For dashboard graphics/charts work, also load `manuals/node-red/flowfuse-ui-chart-manual.md` and `manuals/node-red/flowfuse-dashboard-layout-manual.md`.
  - FlowFuse `ui-chart` baseline for EVOLV: use series by `msg.topic` (`category: "topic"`, `categoryType: "msg"`). Avoid leaving `category` blank.
- Direct specialist invocation is allowed only when all are true:
  - task is clearly single-domain
  - expected impact is local (single node/module concern)
  - no cross-node contract/topic/schema/security implications
- If uncertainty exists, fall back to orchestrator.

## Harness Engineering Adaptation (EVOLV)
Treat the repository as the operating map. Avoid broad static instructions that are not anchored to concrete files, interfaces, or tests.

Execution loop for agent work:
1. Build an impact map from the current repo state (files, contracts, tests, and runtime touchpoints).
2. Define non-negotiable invariants before editing (topic contracts, safety limits, schema/API compatibility, security posture).
3. Implement minimum-scoped changes with explicit acceptance criteria.
4. Verify with local evidence (tests, smoke checks, static checks, or endpoint/output validation).
5. Capture durable learnings by updating the relevant `SKILL.md` and decision logs.

Progressive disclosure policy:
- Load only the primary skill file first.
- Open referenced files/manuals only when needed by the active task.
- Prefer small, auditable diffs over large speculative rewrites.

Decision interview policy (owner-controlled gates):
- Interview the user before finalizing changes that alter any of:
  - Released `msg.topic` contracts or payload schemas
  - Safety/availability envelopes or fail-safe behavior
  - Security defaults, endpoint exposure, or trust boundaries
  - Influx retention/backfill semantics or dashboard query contracts
  - Dependency strategy with operational rollout risk
- Ask at most 3 questions per batch and proceed immediately after answers.

Current owner-approved defaults (February 16, 2026):
- Compatibility posture: `controlled`
  - Breaking `msg.topic`/payload changes are allowed only with explicit migration/deprecation notes.
- Safety posture: `availability-first`
  - Prefer continuity of operation with bounded safeguards over early protective trips.
- Decision logging: `required for all decision-gate changes`
  - Every decision-gate outcome must be recorded in `.agents/decisions/`.

Decision log:
- Record important decisions in `.agents/decisions/DECISION-YYYYMMDD-<slug>.md`.
- Include context, options, decision, consequences, and rollback/migration notes.

Functional/architectural improvements backlog:
- Track deferred functional/runtime/architecture improvements in `.agents/improvements/IMPROVEMENTS_BACKLOG.md`.
- If an improvement is discovered during non-functional work, add it to this backlog before closing the task.
- Keep the top priority review list in `.agents/improvements/TOP10_PRODUCTION_PRIORITIES_YYYY-MM-DD.md` when requested.
- When an item is implemented after review, remove it from `.agents/improvements/IMPROVEMENTS_BACKLOG.md` and note the fix in session notes/PR context.

## Agent Routing Table
Use this table after orchestrator triage, or for approved single-domain direct calls.

| Task Pattern | Primary Skill | Path |
|---|---|---|
| Multi-domain feature, ambiguous ownership, or cross-node integration planning | Orchestrator | `.agents/skills/evolv-orchestrator/SKILL.md` |
| Node-RED editor HTML, form defaults, menu/config endpoints, UI/runtime config parity | Frontend + Node-RED expert | `.agents/skills/evolv-frontend-node-red/SKILL.md` |
| Rotating machine behavior, pump curves, operating envelopes, mechanical plausibility | Mechanical rotating equipment engineer | `.agents/skills/evolv-mechanical-rotating-equipment/SKILL.md` |
| Sensor/measurement semantics, units, validation, quality flags, measurement assets | Instrumentation engineer | `.agents/skills/evolv-instrumentation-assets/SKILL.md` |
| System-wide control architecture, sequencing, mode transitions, parent-child topic contracts | System/process control engineer | `.agents/skills/evolv-process-systems-control/SKILL.md` |
| Biological process modeling, ASM kinetics, oxygen demand, sludge/retention assumptions | Biological process engineer | `.agents/skills/evolv-biological-process-engineering/SKILL.md` |
| InfluxDB telemetry model, tags/fields, retention, Grafana query compatibility | Database/Influx architect | `.agents/skills/evolv-database-influx-architecture/SKILL.md` |
| Sensor/analyzer product behavior, warmup/drift/fouling, device quality semantics | Measurement product specialist | `.agents/skills/evolv-measurement-product-specialist/SKILL.md` |
| OT edge protocol integration (OPC UA/PLC/fieldbus mapping), reconnect and handshake behavior | OT edge PLC integration specialist | `.agents/skills/evolv-ot-edge-plc-integration/SKILL.md` |
| OT/IT threat review, secure defaults, endpoint hardening, control-message safety | OT/IT security engineer | `.agents/skills/evolv-ot-it-security/SKILL.md` |
| Alarm strategy, interlocks, permissives, trip/reset behavior | Alarms/interlocks engineer | `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md` |
| Hydraulics and cross-node mass/volume balance plausibility | Process hydraulics engineer | `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md` |
| Telemetry KPI contract design, dashboard/query compatibility, operator diagnostics | Telemetry/analytics specialist | `.agents/skills/evolv-telemetry-analytics-dashboards/SKILL.md` |
| Wastewater compliance/reporting impact and auditability | Regulatory compliance specialist | `.agents/skills/evolv-regulatory-compliance-wastewater/SKILL.md` |
| FAT/SAT planning, commissioning evidence, rollout readiness gates | Commissioning and validation specialist | `.agents/skills/evolv-commissioning-validation/SKILL.md` |
| Code quality review, regression risk, test gaps, technical debt prioritization | Quality/debt engineer | `.agents/skills/evolv-quality-technical-debt/SKILL.md` |

## Shared Engineering Baseline
- Dependencies: prefer `npm ci` at repo root (uses `package-lock.json`). Avoid changing `package.json` without updating the lockfile.
- Node-RED integration (local dev):
  - Ensure Node-RED can see this repo as a nodes directory (e.g., `settings.js` with `nodesDir: './nodes'`) or copy/link the repo into `~/.node-red/nodes/`.
  - Restart Node-RED after changes so nodes reload.

## Submodules
Many `nodes/*` directories are git submodules.
- Prefer making changes in the appropriate submodule directory and keep edits scoped to that node.
- Avoid editing `nodes/*/.git` files directly.
- If the task is “update a node submodule”, update the submodule pointer in this repo rather than copying code across nodes.

## Safety / Hygiene
- Do not modify generated or vendored content unless explicitly requested:
  - `node_modules/`
  - `EVOLV-*.tgz`
- Exclude `node_modules/` when searching or refactoring (`rg --glob '!**/node_modules/**'`).
- Network access may be restricted in automated runs; avoid installing from git/NPM without approval.
- Node-RED Function node scripts: avoid declaring local variables named `flow`, `global`, `context`, `env`, `RED`, or `node` (these are runtime-provided objects and can trigger redeclare/runtime errors).
  - Use explicit alternatives like `flowValue`, `flowRate`, or `flowMetric` for process data variables.

## Validation
No centralized test runner is configured at the root.
- Prefer targeted smoke checks: Node-RED starts, nodes load, node editor renders, and admin endpoints respond.
- If a node has its own `package.json` scripts, run them from that node directory only when they actually execute in your environment.

## Node Artifact Standard (Required For All Nodes)
Each node under `nodes/<nodeName>/` must include:
- Runtime/editor implementation:
  - `<nodeName>.js`
  - `<nodeName>.html`
  - `src/`
- Test structure:
  - `test/basic/*.test.js`
  - `test/integration/*.test.js`
  - `test/edge/*.test.js`
- Example flow package:
  - `examples/README.md`
  - `examples/basic.flow.json`
  - `examples/integration.flow.json`
  - `examples/edge.flow.json`

Enforcement:
- Do not close node-level work items without maintaining both test and examples structure.
- If legacy nodes are missing these artifacts, treat as technical debt and bring to parity during related work.

## Skill Ownership Of Detailed Standards
- Node-RED structure, file responsibilities, admin endpoints, and new-node checklist: `.agents/skills/evolv-frontend-node-red/SKILL.md`
- Message/port conventions and topic contract behavior: `.agents/skills/evolv-process-systems-control/SKILL.md`
- Biological/kinetic modeling assumptions and plausibility constraints: `.agents/skills/evolv-biological-process-engineering/SKILL.md`
- Sensor/analyzer product behavior and quality-state semantics: `.agents/skills/evolv-measurement-product-specialist/SKILL.md`
- PLC/OPC UA edge protocol mapping and reconnect semantics: `.agents/skills/evolv-ot-edge-plc-integration/SKILL.md`
- Alarm/interlock/permissive design standards: `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md`
- Hydraulics and mass-balance consistency rules: `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
- Telemetry KPI and dashboard/query contract standards: `.agents/skills/evolv-telemetry-analytics-dashboards/SKILL.md`
- Wastewater compliance and auditability constraints: `.agents/skills/evolv-regulatory-compliance-wastewater/SKILL.md`
- Commissioning/FAT/SAT validation standards: `.agents/skills/evolv-commissioning-validation/SKILL.md`
- Test policy depth and quality gates: `.agents/skills/evolv-quality-technical-debt/SKILL.md`
- Multi-skill decomposition/integration and interview protocol: `.agents/skills/evolv-orchestrator/SKILL.md`