# 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.
- `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.
- 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.

## 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` |
| InfluxDB telemetry model, tags/fields, retention, Grafana query compatibility | Database/Influx architect | `.agents/skills/evolv-database-influx-architecture/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` |
| 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.

## 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.

## 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`
- 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`