EVOLV/AGENTS.md

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