253ac93896
Establish CONTRACTS.md at the EVOLV root as the canonical map of where every contract, rule, and standard lives. Surface it from CLAUDE.md so every fresh agent or colleague lands there first. Reshape .claude/refactor/ to reflect that the platform refactor is done: live standards stay at the top level; the plan artifacts (CONTINUE_HERE.md, TASKS.md) move into Archive/ with WARNING banners. Drop content that drifted out of date or duplicated the new standards stack: - docs/DEVELOPER_GUIDE.md (pre-refactor walkthrough; superseded by wiki/Architecture, wiki/Getting-Started, .claude/rules/node-architecture, .claude/refactor/MODULE_SPLIT + per-node CONTRACT.md + src/commands/). - .agents/decisions/ (15 DECISION files): load-bearing decisions belong in commit messages and PR descriptions; live open items in OPEN_QUESTIONS.md. - .agents/improvements/TOP10_*.md: moved to Archive/. Bump generalFunctions to 49c77f2 — adds CONTRACT.md inside the library: different shape from per-node CONTRACT.md files (library API, not msg.topic), with stability tags and pointers to .claude/refactor/CONTRACTS.md §N. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
162 lines
12 KiB
Markdown
162 lines
12 KiB
Markdown
# 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: 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 | `.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`
|