EVOLV/.agents/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.
  • 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

• .claude/skills/: EVOLV domain skills — Claude-Code-native, auto-discovered, invokable via the Skill tool. Use for domain reasoning (rotating equipment, biology, telemetry, security, …).
• .claude/agents/: Claude Code subagents — auto-discovered, invokable via the Agent tool with subagent_type:. Use for spawnable independent work.
• .agents/: Holds this AGENTS.md routing table, function-anchors (per-node behavioural contracts in .agents/function-anchors/), and the improvements backlog (.agents/improvements/). No skills live here — the skill surface was migrated to .claude/skills/ in 2026-05.

Skills vs Subagents — when to use which

Surface	Path	Loaded by	When to use
Claude Code skills	.claude/skills/*/SKILL.md	Auto-discovered; invokable via the Skill tool	Domain knowledge / workflow recipes the active agent should read before deciding
Claude Code subagents	.claude/agents/*.md	Auto-discovered; invokable via the Agent tool	Spawnable independent work (audits, parallel exploration, focused tasks)

The orchestrator lives only as a subagent (.claude/agents/evolv-orchestrator.md); there is no orchestrator skill.

Agent Invocation Policy

• Default: always invoke the orchestrator subagent first (Agent(subagent_type: 'evolv-orchestrator')).
• 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 .claude/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: record load-bearing decisions in the commit message and PR description. Live open items belong in .claude/refactor/OPEN_QUESTIONS.md. Superseded plan artifacts live in .agents/improvements/Archive/ and .claude/refactor/Archive/.

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.
• 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	.claude/agents/evolv-orchestrator.md (subagent — spawn via Agent tool)
Node-RED editor HTML, form defaults, menu/config endpoints, UI/runtime config parity	Frontend + Node-RED expert	.claude/skills/evolv-frontend-node-red/SKILL.md
Rotating machine behavior, pump curves, operating envelopes, mechanical plausibility	Mechanical rotating equipment engineer	.claude/skills/evolv-mechanical-rotating-equipment/SKILL.md
Sensor/measurement semantics, units, validation, quality flags, measurement assets	Instrumentation engineer	.claude/skills/evolv-instrumentation-assets/SKILL.md
System-wide control architecture, sequencing, mode transitions, parent-child topic contracts	System/process control engineer	.claude/skills/evolv-process-systems-control/SKILL.md
Biological process modeling, ASM kinetics, oxygen demand, sludge/retention assumptions	Biological process engineer	.claude/skills/evolv-biological-process-engineering/SKILL.md
InfluxDB telemetry model, tags/fields, retention, Grafana query compatibility	Database/Influx architect	.claude/skills/evolv-database-influx-architecture/SKILL.md
Sensor/analyzer product behavior, warmup/drift/fouling, device quality semantics	Measurement product specialist	.claude/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	.claude/skills/evolv-ot-edge-plc-integration/SKILL.md
OT/IT threat review, secure defaults, endpoint hardening, control-message safety	OT/IT security engineer	.claude/skills/evolv-ot-it-security/SKILL.md
Alarm strategy, interlocks, permissives, trip/reset behavior	Alarms/interlocks engineer	.claude/skills/evolv-alarms-interlocks-permissives/SKILL.md
Hydraulics and cross-node mass/volume balance plausibility	Process hydraulics engineer	.claude/skills/evolv-process-hydraulics-mass-balance/SKILL.md
Telemetry KPI contract design, dashboard/query compatibility, operator diagnostics	Telemetry/analytics specialist	.claude/skills/evolv-telemetry-analytics-dashboards/SKILL.md
Wastewater compliance/reporting impact and auditability	Regulatory compliance specialist	.claude/skills/evolv-regulatory-compliance-wastewater/SKILL.md
FAT/SAT planning, commissioning evidence, rollout readiness gates	Commissioning and validation specialist	.claude/skills/evolv-commissioning-validation/SKILL.md
Code quality review, regression risk, test gaps, technical debt prioritization	Quality/debt engineer	.claude/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: .claude/skills/evolv-frontend-node-red/SKILL.md
• Message/port conventions and topic contract behavior: .claude/skills/evolv-process-systems-control/SKILL.md
• Biological/kinetic modeling assumptions and plausibility constraints: .claude/skills/evolv-biological-process-engineering/SKILL.md
• Sensor/analyzer product behavior and quality-state semantics: .claude/skills/evolv-measurement-product-specialist/SKILL.md
• PLC/OPC UA edge protocol mapping and reconnect semantics: .claude/skills/evolv-ot-edge-plc-integration/SKILL.md
• Alarm/interlock/permissive design standards: .claude/skills/evolv-alarms-interlocks-permissives/SKILL.md
• Hydraulics and mass-balance consistency rules: .claude/skills/evolv-process-hydraulics-mass-balance/SKILL.md
• Telemetry KPI and dashboard/query contract standards: .claude/skills/evolv-telemetry-analytics-dashboards/SKILL.md
• Wastewater compliance and auditability constraints: .claude/skills/evolv-regulatory-compliance-wastewater/SKILL.md
• Commissioning/FAT/SAT validation standards: .claude/skills/evolv-commissioning-validation/SKILL.md
• Test policy depth and quality gates: .claude/skills/evolv-quality-technical-debt/SKILL.md
• Multi-skill decomposition/integration and interview protocol: .claude/agents/evolv-orchestrator.md (subagent)