docs: retire repo-mem MCP, migrate skills to .claude/skills, audit fixes
- Delete .mcp.json + .claude/rules/repo-mem.md; drop .repo-mem from .gitignore - Remove repo-mem / substrate_score / repo_search references from all .md - Move 15 EVOLV skills from .agents/skills/ to .claude/skills/ so they are auto-discovered by the Claude Code harness and invokable via the Skill tool - Retire .agents/skills/evolv-orchestrator (duplicate of the subagent at .claude/agents/evolv-orchestrator.md); orchestrator lives as a subagent only - Drop OpenAI-format agent yaml metadata from each skill (not needed for CC) - Update CLAUDE.md, CONTRACTS.md, AGENTS.md to point at the new locations and disambiguate skills (.claude/skills/) vs subagents (.claude/agents/) - Fix CLAUDE.md tick-loop wording (opt-in per-node, not a fixed 1000ms) - Widen .claude/rules/ paths frontmatter so node-architecture and telemetry rules trigger on more relevant files; add frontmatter to flow-layout rule - Bump CONTRACTS.md review date to 2026-05-19; add step 7 to the contract- change workflow (review example flows when topic usage changes) - Bump nodes/generalFunctions pin (Home.md substrate_score reference removed) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
@@ -15,12 +15,21 @@ EVOLV is a modular Node-RED package bundling multiple custom control/automation
|
||||
- `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.
|
||||
- `.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 orchestrator first via `.agents/skills/evolv-orchestrator/SKILL.md`.
|
||||
- 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.
|
||||
@@ -33,7 +42,7 @@ EVOLV is a modular Node-RED package bundling multiple custom control/automation
|
||||
- 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 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:
|
||||
@@ -83,22 +92,22 @@ Use this table after orchestrator triage, or for approved single-domain direct c
|
||||
|
||||
| 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` |
|
||||
| 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.
|
||||
@@ -147,15 +156,15 @@ Enforcement:
|
||||
- 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`
|
||||
- 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)
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
name: evolv-alarms-interlocks-permissives
|
||||
description: Design and review alarms, interlocks, and permissive logic for EVOLV control nodes. Use when implementing trip conditions, permissive checks, startup/shutdown guards, alarm priorities, latching/reset behavior, and operator-facing fault handling.
|
||||
---
|
||||
|
||||
# EVOLV Alarms Interlocks Permissives
|
||||
|
||||
## Mission
|
||||
Make alarm and interlock behavior explicit, testable, and operationally safe while preserving availability-first policy bounds.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Build alarm/interlock map from current node contracts and state logic.
|
||||
- Define invariants before edits:
|
||||
- trips/permissives are deterministic
|
||||
- latching/reset behavior is explicit
|
||||
- operator-visible diagnostics are preserved
|
||||
- Validate with sequence and fail-state tests.
|
||||
|
||||
## Scope
|
||||
- `nodes/pumpingStation/`
|
||||
- `nodes/machineGroupControl/`
|
||||
- `nodes/rotatingMachine/`
|
||||
- Any node with mode/state transitions and protective actions
|
||||
|
||||
## Workflow
|
||||
1. Enumerate alarm conditions and priority/severity.
|
||||
2. Define interlock and permissive truth tables.
|
||||
3. Verify startup/shutdown/emergency sequences.
|
||||
4. Confirm reset, auto-recovery, and manual acknowledgement behavior.
|
||||
5. Ensure outputs expose actionable fault context.
|
||||
|
||||
## Standards
|
||||
- Avoid hidden permissives; every gate should be observable.
|
||||
- Keep alarm naming stable and semantically clear.
|
||||
- Separate advisory warnings from trip-level protection.
|
||||
- Preserve controlled compatibility for released fault topics.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- trip activation and reset/latch behavior
|
||||
- permissive-denied and permissive-restored transitions
|
||||
- out-of-order signal handling in sequence transitions
|
||||
- degraded sensor quality paths and alarm escalation
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- alarm/interlock/permissive matrix
|
||||
- changed files/tests and evidence
|
||||
- unresolved protection-vs-availability tradeoffs
|
||||
|
||||
Decision interview triggers:
|
||||
- changed trip thresholds or permissive logic with operational impact
|
||||
- altered reset authority (auto vs manual)
|
||||
- alarm contract changes affecting external consumers
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Alarms Interlocks Permissives"
|
||||
short_description: "Protective logic and operator alarm specialist"
|
||||
default_prompt: "Map alarm/interlock/permissive behavior in the impacted EVOLV nodes, define deterministic trip and reset rules, validate sequence edge cases, and return test-backed recommendations with clear operational tradeoffs."
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
name: evolv-biological-process-engineering
|
||||
description: Engineer biological wastewater process behavior for EVOLV nodes. Use when implementing or reviewing reactor/settler biology, ASM-style kinetics, oxygen demand, nitrification/denitrification, sludge behavior, calibration assumptions, and biologically plausible constraints.
|
||||
---
|
||||
|
||||
# EVOLV Biological Process Engineering
|
||||
|
||||
## Mission
|
||||
Keep EVOLV biological process models physically plausible, calibratable, and operationally useful.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Ground changes in current biology/state variables and connected control topics.
|
||||
- Define invariants before edits:
|
||||
- biological mass-balance intent is preserved
|
||||
- model assumptions remain explicit and traceable
|
||||
- degraded behavior remains availability-first and bounded
|
||||
- Validate with deterministic tests and representative operating scenarios.
|
||||
|
||||
## Scope
|
||||
- `nodes/reactor/`
|
||||
- `nodes/settler/`
|
||||
- `nodes/pumpingStation/` (where biology interacts with flow/retention assumptions)
|
||||
- Related reaction modules and utilities under `nodes/*/src/`
|
||||
|
||||
## Workflow
|
||||
1. Identify biological state variables, units, and expected ranges.
|
||||
2. Map kinetic pathways (growth, decay, transfer, conversion) and rate constraints.
|
||||
3. Verify oxygen/temperature dependencies and fallback behavior.
|
||||
4. Check integration stability for configured time-step and resolution choices.
|
||||
5. Confirm outputs remain interpretable for control and dashboard consumers.
|
||||
|
||||
## Standards
|
||||
- Keep state vectors explicit and index mappings documented.
|
||||
- Avoid silent clipping/coercion without test coverage and rationale.
|
||||
- Preserve topic/payload compatibility unless migration is defined.
|
||||
- Record calibration assumptions and required field data.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- kinetic branch behavior under representative and boundary conditions
|
||||
- non-negativity and boundedness safeguards
|
||||
- temperature and oxygen transfer sensitivity
|
||||
- time-step/resolution edge behavior and stability warnings
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- biological assumptions and constraints used
|
||||
- changed files/tests and evidence
|
||||
- calibration notes and unresolved biological uncertainties
|
||||
|
||||
Decision interview triggers:
|
||||
- altered biology assumptions that can change plant behavior
|
||||
- parameter/default changes with startup or compliance impact
|
||||
- compatibility breaks in biological outputs or topic contracts
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Biological Process Engineering"
|
||||
short_description: "Wastewater biology and kinetics specialist"
|
||||
default_prompt: "Map biological state variables and kinetics in the impacted EVOLV nodes, define non-negotiable biological invariants, validate oxygen/temperature/time-step behavior, and return test-backed recommendations with calibration assumptions and risks."
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
name: evolv-commissioning-validation
|
||||
description: Plan and verify EVOLV commissioning readiness. Use when defining FAT/SAT test plans, acceptance criteria, loop checks, simulation-to-field validation, startup sequencing evidence, and rollout gates for operational deployment.
|
||||
---
|
||||
|
||||
# EVOLV Commissioning Validation
|
||||
|
||||
## Mission
|
||||
Convert implementation changes into deployment-ready evidence with clear acceptance gates.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from impacted contracts, modes, and site-operational constraints.
|
||||
- Define invariants before edits:
|
||||
- validation criteria are measurable and reproducible
|
||||
- startup and failover behavior is proven, not assumed
|
||||
- rollback path is explicit
|
||||
- Produce evidence artifacts tied to concrete tests/checks.
|
||||
|
||||
## Scope
|
||||
- Cross-node behavior spanning control, measurement, and integrations
|
||||
- Test plans and validation docs under repository documentation paths
|
||||
- Node-level suites where commissioning evidence is derived
|
||||
|
||||
## Workflow
|
||||
1. Build FAT/SAT matrix from impacted contracts and risk areas.
|
||||
2. Define pass/fail criteria and required instrumentation visibility.
|
||||
3. Execute or script reproducible validation checks.
|
||||
4. Capture evidence with timestamps, commands, and outcomes.
|
||||
5. Define rollout gates and rollback triggers.
|
||||
|
||||
## Standards
|
||||
- Prefer deterministic replayable checks over ad-hoc validation.
|
||||
- Include negative-path and recovery-path tests.
|
||||
- Tie each acceptance criterion to a concrete artifact.
|
||||
- Keep operator handoff notes concise and actionable.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- startup/shutdown commissioning sequences
|
||||
- failover and reconnect scenarios
|
||||
- alarm/interlock behavior under commissioning cases
|
||||
- post-deploy smoke checks and regression shortlist
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- FAT/SAT-style validation matrix
|
||||
- executed evidence summary
|
||||
- go/no-go risks and mitigations
|
||||
- rollback plan and monitoring checklist
|
||||
|
||||
Decision interview triggers:
|
||||
- reduced commissioning scope under schedule pressure
|
||||
- acceptance of unresolved high-severity risks
|
||||
- rollout sequencing choices with operational impact
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Commissioning Validation"
|
||||
short_description: "FAT/SAT and deployment-readiness specialist"
|
||||
default_prompt: "Create a commissioning evidence plan from impacted EVOLV contracts, define measurable FAT/SAT acceptance criteria, verify failure and recovery paths, and return go/no-go risks with rollback guidance."
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
name: evolv-database-influx-architecture
|
||||
description: Design and review EVOLV data modeling and storage architecture for telemetry and dashboard consumption. Use when deciding InfluxDB measurement/tag/field schemas, retention/downsampling strategy, write/read payload structures, and Grafana query compatibility for Node-RED outputs.
|
||||
---
|
||||
|
||||
# EVOLV Database Influx Architecture
|
||||
|
||||
## Mission
|
||||
Shape telemetry data so it is queryable, performant, and maintainable for operations dashboards and analytics.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from current measurement/tag/field usage and dashboard queries.
|
||||
- Define invariants before edits:
|
||||
- query compatibility for existing Grafana/consumer flows
|
||||
- bounded tag cardinality
|
||||
- explicit units and timestamp policy
|
||||
- Provide validation evidence using representative payloads and queries.
|
||||
|
||||
## Scope
|
||||
- Output payload structure from EVOLV nodes
|
||||
- InfluxDB write model: measurement, tags, fields, timestamp policy
|
||||
- Retention/downsampling implications for Grafana visualization
|
||||
|
||||
## Workflow
|
||||
1. Classify data by usage:
|
||||
- real-time control
|
||||
- operator dashboarding
|
||||
- long-term analytics
|
||||
2. Define stable schema conventions:
|
||||
- measurement naming
|
||||
- tag cardinality controls
|
||||
- numeric fields and units
|
||||
3. Validate that node outputs map cleanly to write model.
|
||||
4. Check query ergonomics for expected Grafana panels.
|
||||
5. Specify retention/downsampling and backfill behavior.
|
||||
|
||||
## Design Rules
|
||||
- Avoid high-cardinality tags for volatile identifiers.
|
||||
- Keep units explicit and consistent over time.
|
||||
- Prefer additive schema evolution; document breaking changes.
|
||||
- Include timestamps that are consistent across nodes.
|
||||
|
||||
## Test/Validation Expectations
|
||||
- Verify sample payloads produce intended point shape.
|
||||
- Check representative queries for latency and result correctness.
|
||||
- Include migration strategy when schema changes are unavoidable.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- proposed schema (measurement/tags/fields)
|
||||
- rationale tied to dashboard and analytics use
|
||||
- changed files/tests
|
||||
- migration and retention plan
|
||||
|
||||
Decision interview triggers:
|
||||
- schema changes that break existing queries/panels
|
||||
- retention/downsampling policies with data-loss tradeoffs
|
||||
- backfill rules that alter historical comparability
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Database + Influx Architect"
|
||||
short_description: "Design telemetry schema for Influx and Grafana"
|
||||
default_prompt: "Define EVOLV telemetry schema from current payload/query usage, enforce cardinality and compatibility invariants, validate with representative queries, and escalate decision-gate tradeoffs for retention/backfill or breaking schema changes."
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
name: evolv-frontend-node-red
|
||||
description: Design and implement Node-RED node editor UI and runtime-facing configuration for EVOLV. Use when editing node HTML editor files, `RED.nodes.registerType(...)` defaults, admin endpoint-driven menus/config scripts, and config mapping into `src/nodeClass.js` in JavaScript/CommonJS nodes.
|
||||
---
|
||||
|
||||
# EVOLV Frontend Node-RED
|
||||
|
||||
## Mission
|
||||
Implement robust Node-RED editor experiences that keep UI defaults, runtime config parsing, and behavior in lockstep.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from impacted files and active runtime/editor contracts.
|
||||
- Define invariants before editing:
|
||||
- `.html` defaults and runtime parsing parity
|
||||
- endpoint path stability (`/<nodeName>/menu.js`, `/<nodeName>/configData.js`)
|
||||
- released topic/output compatibility unless migration is declared
|
||||
- Provide evidence for changed behavior (tests or smoke checks).
|
||||
|
||||
## Repo-Specific Rules
|
||||
- Use CommonJS patterns in runtime files.
|
||||
- Keep node names aligned across `RED.nodes.registerType('<nodeName>', ...)`, runtime registration in `<nodeName>.js`, and package/node mapping.
|
||||
- Keep admin endpoint paths stable unless editor consumers are updated: `/<nodeName>/menu.js` and `/<nodeName>/configData.js`.
|
||||
- Prefer placeholder-driven UI composition when matching EVOLV patterns.
|
||||
|
||||
## Node Layout Standard
|
||||
Use `nodes/machineGroupControl/` as the template baseline for new nodes.
|
||||
|
||||
- `nodes/<nodeName>/<nodeName>.js`
|
||||
- Keep runtime entry small.
|
||||
- Create Node-RED instance and attach `this.nodeClass = new nodeClass(...)`.
|
||||
- Register admin endpoints via shared managers.
|
||||
- `nodes/<nodeName>/<nodeName>.html`
|
||||
- Register defaults in `RED.nodes.registerType(...)`.
|
||||
- Load `/<nodeName>/menu.js` and `/<nodeName>/configData.js`.
|
||||
- Use `oneditprepare` to call `window.EVOLV.nodes.<nodeName>.initEditor(this)`.
|
||||
- `nodes/<nodeName>/src/nodeClass.js`
|
||||
- Normalize `uiConfig` into runtime config.
|
||||
- Keep Node-RED concerns here: input routing, tick loop, output formatting, status.
|
||||
- `nodes/<nodeName>/src/specificClass.js`
|
||||
- Keep domain logic here with minimal/no direct Node-RED coupling.
|
||||
|
||||
## Implementation Workflow
|
||||
1. Inspect current node trio: `.html`, `.js`, `src/nodeClass.js`.
|
||||
2. Define required config properties and defaults.
|
||||
3. Update `.html` defaults and form controls.
|
||||
4. Update runtime config normalization in `src/nodeClass.js`.
|
||||
5. Confirm `msg.topic` command handling is still coherent.
|
||||
6. Add tests under `nodes/<nodeName>/test/` with focus on config defaults/overrides and topic routing.
|
||||
7. If creating a new node, add entry under root `package.json` `node-red.nodes` map.
|
||||
|
||||
## Quality Gates
|
||||
- Every UI property has corresponding runtime handling.
|
||||
- Numeric inputs are validated/coerced consistently.
|
||||
- Node status and output shape remain predictable.
|
||||
- No Node-RED runtime dependency required for domain tests.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- changed config fields and mapping table
|
||||
- changed files
|
||||
- tests added and what they prove
|
||||
- migration notes if backward compatibility changed
|
||||
|
||||
Decision interview triggers:
|
||||
- form or default changes that alter existing deployed behavior
|
||||
- endpoint contract/path changes
|
||||
- UI/runtime migration that could break saved Node-RED flows
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Frontend + Node-RED"
|
||||
short_description: "Build EVOLV Node-RED editor/runtime UX safely"
|
||||
default_prompt: "Implement EVOLV Node-RED editor/runtime changes from a file-level impact map, preserve UI/runtime parity and stable endpoint contracts, provide verification evidence, and ask decision-gate questions before compatibility-breaking edits."
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
name: evolv-instrumentation-assets
|
||||
description: Engineer measurement and instrumentation behavior for EVOLV assets. Use when defining sensor mappings, tag semantics, data quality checks, measurement container behavior, calibration assumptions, and measurement-driven node logic in `measurement` and related assets.
|
||||
---
|
||||
|
||||
# EVOLV Instrumentation Assets
|
||||
|
||||
## Mission
|
||||
Ensure measurements are trustworthy, well-modeled, and usable by control and analytics logic.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Ground changes in current measurement definitions and downstream consumers.
|
||||
- Define invariants before edits:
|
||||
- unit consistency and conversion transparency
|
||||
- explicit quality-state handling
|
||||
- no silent coercion that hides sensor faults
|
||||
- Provide evidence for data-quality transitions and fallback behavior.
|
||||
|
||||
## Scope
|
||||
- `nodes/measurement/`
|
||||
- `nodes/generalFunctions/src/helper/measurement*`
|
||||
- `nodes/generalFunctions/datasets/assetData/measurement.json`
|
||||
- Any node consuming measurement topics or quality flags
|
||||
|
||||
## Workflow
|
||||
1. Inventory required measurements by asset/function.
|
||||
2. Define tag semantics and expected units.
|
||||
3. Add validation rules for bounds, type, and missing values.
|
||||
4. Specify handling for stale/noisy/bad-quality signals.
|
||||
5. Ensure downstream nodes receive consistent payload structure.
|
||||
|
||||
## Standards
|
||||
- Prefer explicit unit naming and conversion points.
|
||||
- Separate raw sensor value from engineered value when possible.
|
||||
- Avoid hidden coercions that mask instrumentation faults.
|
||||
- Record assumptions around calibration and sensor placement.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- missing/invalid payloads
|
||||
- unit conversion correctness
|
||||
- quality/state transitions (good/suspect/bad)
|
||||
- behavior when critical measurements drop out
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- measurement dictionary (name, unit, validity range, source)
|
||||
- validation and fallback rules
|
||||
- file/test changes
|
||||
- open instrumentation risks for commissioning
|
||||
|
||||
Decision interview triggers:
|
||||
- changed units or semantics for released measurements
|
||||
- new fallback logic that may mask real field failures
|
||||
- altered quality thresholds affecting control decisions
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Instrumentation Engineer"
|
||||
short_description: "Define sensor and measurement asset behavior"
|
||||
default_prompt: "Design EVOLV measurement behavior from current assets and consumers, enforce unit/quality invariants, provide validation evidence for edge conditions, and ask decision-gate questions before semantic or threshold changes."
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
name: evolv-measurement-product-specialist
|
||||
description: Apply measurement product and device expertise for EVOLV. Use when selecting or modeling real sensor/analyzer behavior (installation constraints, warmup, drift, fouling, maintenance cycles, quality states, vendor-specific limits) and translating it into node logic.
|
||||
---
|
||||
|
||||
# EVOLV Measurement Product Specialist
|
||||
|
||||
## Mission
|
||||
Model real-world measurement device behavior so EVOLV control logic receives realistic, diagnosable signals.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from concrete device classes and current measurement payload contracts.
|
||||
- Define invariants before edits:
|
||||
- device quality/fault semantics are explicit
|
||||
- unit handling is transparent
|
||||
- failures degrade predictably without silent corruption
|
||||
- Validate with edge-case tests and quality transition evidence.
|
||||
|
||||
## Scope
|
||||
- `nodes/measurement/`
|
||||
- Measurement consumption paths in `nodes/*/src/`
|
||||
- Shared measurement utilities in `nodes/generalFunctions/src/measurements/`
|
||||
|
||||
## Workflow
|
||||
1. Define device class behavior (transmitter, analyzer, meter, switch).
|
||||
2. Capture startup/warmup/maintenance/fault states.
|
||||
3. Map quality codes and stale/noisy behavior into payload semantics.
|
||||
4. Verify conversion and plausibility bounds.
|
||||
5. Confirm downstream control impact under bad/suspect states.
|
||||
|
||||
## Standards
|
||||
- Separate raw, filtered, and engineered values where needed.
|
||||
- Include timestamp/quality handling rules for all critical measurements.
|
||||
- Avoid masking device faults with silent defaults.
|
||||
- Document maintenance and recalibration assumptions.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- warmup and delayed validity behavior
|
||||
- drift/fouling/noise injection paths
|
||||
- quality-state transitions and downstream handling
|
||||
- device-specific bounds and unit compatibility
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- device behavior model and assumptions
|
||||
- payload/quality mapping
|
||||
- changed files/tests with evidence
|
||||
- commissioning checks required in field
|
||||
|
||||
Decision interview triggers:
|
||||
- changed quality semantics used by control decisions
|
||||
- new fallback paths that could hide instrumentation failure
|
||||
- device defaults likely to alter operator behavior
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Measurement Product Specialist"
|
||||
short_description: "Sensor/analyzer product behavior expert"
|
||||
default_prompt: "Model real device behavior for the impacted EVOLV measurement paths, including warmup, drift, fouling, quality states, and bounds; preserve payload contracts and provide test-backed fallback behavior."
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
name: evolv-mechanical-rotating-equipment
|
||||
description: Provide rotating equipment engineering guidance for EVOLV machine and pumping logic. Use when implementing or reviewing `rotatingMachine`, `machineGroupControl`, pump/motor behavior, operating envelopes, efficiency/power curves, surge/choke limits, and physically plausible constraints in node domain logic.
|
||||
---
|
||||
|
||||
# EVOLV Mechanical Rotating Equipment
|
||||
|
||||
## Mission
|
||||
Keep rotating equipment behavior physically plausible, safe, and diagnosable in EVOLV JavaScript domain classes.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from equipment assumptions and current curve/sensor sources in repo.
|
||||
- Define invariants before edits:
|
||||
- physical plausibility constraints remain enforced
|
||||
- degraded/fail-safe behavior remains explicit
|
||||
- outputs remain diagnosable for operations teams
|
||||
- Validate with boundary-condition evidence and deterministic test outcomes.
|
||||
|
||||
## Scope
|
||||
- `nodes/rotatingMachine/`
|
||||
- `nodes/machineGroupControl/`
|
||||
- `nodes/pumpingStation/`
|
||||
- Related shared curve/model datasets in `nodes/generalFunctions/datasets/assetData/`
|
||||
|
||||
## Engineering Checklist
|
||||
1. Validate units and conversions before algorithm changes.
|
||||
2. Enforce operating envelope constraints:
|
||||
- min/max speed
|
||||
- flow/head boundaries
|
||||
- power/torque limits
|
||||
- efficiency range sanity
|
||||
3. Prevent impossible states (negative flow where not allowed, non-physical efficiencies, unstable mode transitions).
|
||||
4. Define clear degraded behavior for out-of-range inputs.
|
||||
5. Preserve interpretability: outputs should map to recognizable mechanical concepts.
|
||||
|
||||
## Implementation Pattern
|
||||
- Keep mechanics in `src/specificClass.js`.
|
||||
- Keep Node-RED concerns in `src/nodeClass.js`.
|
||||
- Use shared helpers from `generalFunctions` for logging/config assertions.
|
||||
|
||||
## Test Expectations
|
||||
Add/adjust tests under node-specific `test/` for:
|
||||
- boundary conditions
|
||||
- invalid sensor/input combinations
|
||||
- regression of known machine edge cases
|
||||
- deterministic output under repeated ticks
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- assumptions about equipment type and curve source
|
||||
- implemented constraints and rationale
|
||||
- test coverage for boundary cases
|
||||
- remaining mechanical uncertainties requiring field data
|
||||
|
||||
Decision interview triggers:
|
||||
- safety envelope changes (speed, power, flow/head boundaries)
|
||||
- curve-source replacement with uncertain field alignment
|
||||
- degraded-mode changes that affect availability vs protection tradeoffs
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Rotating Equipment Engineer"
|
||||
short_description: "Model rotating assets with physical realism"
|
||||
default_prompt: "Review EVOLV rotating-machine logic from current curves/sensors, enforce physical and fail-safe invariants, verify with boundary evidence, and trigger decision-gate interviews before changing safety envelopes."
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
name: evolv-orchestrator
|
||||
description: Orchestrate multi-agent execution for the EVOLV repository. Use when work spans multiple disciplines (Node-RED frontend/editor UI, rotating equipment logic, instrumentation assets, process control, InfluxDB/data architecture, OT/IT security, and quality/technical debt) and requires decomposition, sequencing, handoffs, and integration decisions.
|
||||
---
|
||||
|
||||
# EVOLV Orchestrator
|
||||
|
||||
## Mission
|
||||
Coordinate specialized EVOLV agents, split work into clear tasks, and ensure integrations are coherent across JavaScript/CommonJS Node-RED nodes, process assets, and observability/data concerns.
|
||||
|
||||
## Harness-Style Operating Rules
|
||||
- Start from the live repo state, not generic playbooks.
|
||||
- Build a file-level impact map before assigning specialist work.
|
||||
- Define invariants first, then implement changes.
|
||||
- Require evidence for each claim (tests, smoke checks, endpoint validation, or concrete diffs).
|
||||
- Convert repeated lessons into updated skill guidance to reduce future ambiguity.
|
||||
|
||||
## Execution Flow
|
||||
1. Frame the objective and constraints in one paragraph.
|
||||
2. Build an impact map before assigning work. Identify touched contracts and files:
|
||||
- `nodes/<nodeName>/<nodeName>.html` (editor UI)
|
||||
- `nodes/<nodeName>/<nodeName>.js` (runtime entry)
|
||||
- `nodes/<nodeName>/src/nodeClass.js` (Node-RED wrapper)
|
||||
- `nodes/<nodeName>/src/specificClass.js` (domain logic)
|
||||
- `nodes/generalFunctions/` (shared helpers/config)
|
||||
3. Declare invariants and acceptance criteria:
|
||||
- backward compatibility posture: controlled breaks allowed only with migration
|
||||
- safety posture: availability-first unless user overrides for a specific task
|
||||
- security trust boundary/default behavior
|
||||
- data schema/query compatibility where relevant
|
||||
4. Route tasks to specialist skills with explicit deliverables and acceptance criteria.
|
||||
5. Require each specialist to return:
|
||||
- assumptions
|
||||
- changed files
|
||||
- tests added/updated
|
||||
- unresolved risks
|
||||
6. Integrate outputs and check cross-skill consistency:
|
||||
- config fields aligned between `.html` and runtime parsing
|
||||
- admin endpoints stable (`/<nodeName>/menu.js`, `/<nodeName>/configData.js`)
|
||||
- topic contracts (`msg.topic`) unchanged unless migration is defined
|
||||
7. Ask targeted user interview questions only at decision gates (see protocol below).
|
||||
8. Produce a final integrated implementation with a risk log and decision log updates when needed.
|
||||
|
||||
## Delegation Map
|
||||
- Use `evolv-frontend-node-red` for Node-RED editor/runtime UX and HTML config input design.
|
||||
- Use `evolv-mechanical-rotating-equipment` for rotating machine behavior, limits, and performance logic.
|
||||
- Use `evolv-instrumentation-assets` for measurement tags, sensor semantics, and asset metadata.
|
||||
- Use `evolv-process-systems-control` for system-level interactions, modes, and control architecture.
|
||||
- Use `evolv-database-influx-architecture` for InfluxDB schema, retention, query shape, and Grafana coupling.
|
||||
- Use `evolv-ot-it-security` for OT/IT hardening and secure-by-default checks.
|
||||
- Use `evolv-quality-technical-debt` for regression risk, tests, maintainability, and technical debt.
|
||||
|
||||
## Interview Protocol
|
||||
Ask at most 3 focused questions at a time. Prioritize:
|
||||
1. Operational objective and KPI (what "better" means).
|
||||
2. Safety/availability constraints (what must never break).
|
||||
3. Backward compatibility expectations for flows and topics.
|
||||
|
||||
Trigger an interview before finalizing when any of these are true:
|
||||
- Breaking topic/payload/schema/API change is proposed
|
||||
- Safety envelope or fail-safe defaults are loosened/tightened
|
||||
- Security defaults or endpoint exposure changes
|
||||
- Data retention/backfill/query behavior changes
|
||||
- Rollout strategy has material operational risk
|
||||
|
||||
Default resolution rules when interviewing:
|
||||
- prefer compatibility option with migration over undocumented hard breaks
|
||||
- prefer availability-first behavior with explicit bounded safeguards
|
||||
- always create/update a decision log entry for every decision-gate outcome
|
||||
|
||||
Question format:
|
||||
- decision statement (one sentence)
|
||||
- options with tradeoff
|
||||
- recommended option and why
|
||||
|
||||
## Output Contract
|
||||
Return:
|
||||
- task breakdown by specialist
|
||||
- execution order and dependencies
|
||||
- measurable acceptance criteria
|
||||
- integration risks and mitigation
|
||||
- evidence summary (what was verified and how)
|
||||
- decision log entries created/updated (if any)
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Orchestrator"
|
||||
short_description: "Coordinate EVOLV specialist agent workflows"
|
||||
default_prompt: "Build a repo-grounded impact map, define invariants, delegate EVOLV work to specialists with measurable acceptance criteria, run decision-gate interviews for ambiguous high-impact choices, and return integrated evidence plus risks."
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
name: evolv-ot-edge-plc-integration
|
||||
description: Engineer OT edge connectivity and PLC interoperability for EVOLV. Use when implementing or reviewing OPC UA/Modbus and similar integrations, namespace/tag mapping, quality/timestamp semantics, retry/reconnect behavior, and deterministic command/feedback contracts at the edge.
|
||||
---
|
||||
|
||||
# EVOLV OT Edge PLC Integration
|
||||
|
||||
## Mission
|
||||
Deliver reliable, deterministic edge protocol integration between EVOLV Node-RED nodes and PLC/SCADA systems.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from current integration topology, topic contracts, and protocol endpoints.
|
||||
- Define invariants before edits:
|
||||
- command/feedback contracts remain deterministic
|
||||
- reconnect/retry behavior is bounded and observable
|
||||
- quality/timestamp semantics are preserved end-to-end
|
||||
- Validate with connection-loss and recovery evidence.
|
||||
|
||||
## Scope
|
||||
- Edge/connector nodes (existing and new)
|
||||
- Topic mapping code in `nodes/*/src/`
|
||||
- Admin endpoints/config for connector behavior and credentials
|
||||
|
||||
## Workflow
|
||||
1. Map PLC tags/NodeIds/registers to EVOLV message contracts.
|
||||
2. Define write acknowledgement and feedback confirmation rules.
|
||||
3. Implement reconnect/backoff/session handling.
|
||||
4. Enforce quality, timestamp, and stale-value semantics.
|
||||
5. Verify failover behavior and command idempotency.
|
||||
|
||||
## Standards
|
||||
- Never assume connection continuity; model transient faults explicitly.
|
||||
- Keep protocol mappings versioned and auditable.
|
||||
- Separate transport errors from process-state errors.
|
||||
- Ensure secure defaults align with OT/IT security skill.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- disconnect/reconnect and session re-establish paths
|
||||
- duplicate/late/out-of-order message handling
|
||||
- read/write mapping correctness and unit conversion
|
||||
- safe behavior under degraded quality or timeout
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- integration contract map (protocol <-> topic/payload)
|
||||
- retry/recovery strategy and limits
|
||||
- changed files/tests with failure-injection evidence
|
||||
- operational rollout risks and mitigations
|
||||
|
||||
Decision interview triggers:
|
||||
- command authority or handshake behavior changes
|
||||
- protocol mapping breaks requiring migration
|
||||
- timeout/retry strategy changes affecting availability/safety
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV OT Edge PLC Integration"
|
||||
short_description: "OPC UA/PLC edge interoperability specialist"
|
||||
default_prompt: "Build a protocol-to-topic contract map for the affected EVOLV integration, define deterministic read/write and reconnect semantics, validate failure and recovery behavior, and return evidence-backed implementation guidance."
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
name: evolv-ot-it-security
|
||||
description: Perform OT/IT security analysis for EVOLV Node-RED automation systems. Use when reviewing admin endpoints, node input handling, configuration exposure, dependency risk, network/data flow boundaries, and secure-by-default behavior for operational technology integrations.
|
||||
---
|
||||
|
||||
# EVOLV OT/IT Security
|
||||
|
||||
## Mission
|
||||
Identify and reduce security risk while preserving operational reliability for process automation workloads.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Model trust boundaries first (admin HTTP, message ingress, external integrations).
|
||||
- Define security invariants before edits:
|
||||
- secure defaults stay secure unless explicitly approved
|
||||
- no sensitive leakage in logs/UI/errors
|
||||
- malformed control inputs are rejected predictably
|
||||
- Support findings with reproducible evidence and concrete remediation steps.
|
||||
|
||||
## Scope
|
||||
- Node-RED admin endpoints in node entry files
|
||||
- Input validation across `msg.topic` and payload paths
|
||||
- Exposure of sensitive config/secrets in code, logs, or UI
|
||||
- Dependency and supply-chain concerns in node packages
|
||||
|
||||
## Security Workflow
|
||||
1. Enumerate attack surface:
|
||||
- HTTP admin routes
|
||||
- message ingress topics/payloads
|
||||
- external service interfaces
|
||||
2. Validate input sanitization and type checks.
|
||||
3. Check least-privilege assumptions and secret handling.
|
||||
4. Evaluate failure modes for denial-of-service or unsafe operation.
|
||||
5. Recommend pragmatic controls with minimal operational friction.
|
||||
|
||||
## Control Priorities
|
||||
- Reject malformed or unauthorized control messages.
|
||||
- Avoid leaking credentials, asset identifiers, or internal topology.
|
||||
- Keep defaults safe; require explicit opt-in for risky behavior.
|
||||
- Preserve auditability of critical control actions.
|
||||
|
||||
## Validation Expectations
|
||||
- Add negative tests for malformed inputs and unauthorized paths.
|
||||
- Confirm error paths are explicit and non-sensitive.
|
||||
- Document residual risk when controls are deferred.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- findings sorted by severity
|
||||
- concrete remediation plan by file
|
||||
- tests added for security regressions
|
||||
- residual risks and compensating controls
|
||||
|
||||
Decision interview triggers:
|
||||
- any change that relaxes authentication/authorization checks
|
||||
- exposure of new admin routes or integration interfaces
|
||||
- security control deferrals that require compensating controls
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV OT/IT Security Engineer"
|
||||
short_description: "Audit EVOLV OT/IT control security posture"
|
||||
default_prompt: "Perform EVOLV OT/IT security review from explicit trust boundaries, preserve secure defaults, provide reproducible evidence and severity-ranked fixes, and raise decision-gate questions before any risk-accepting control changes."
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
name: evolv-process-hydraulics-mass-balance
|
||||
description: Engineer process hydraulics and mass-balance consistency across EVOLV nodes. Use when validating flow/volume/level relationships, retention-time assumptions, split/merge behavior, and physically plausible cross-node transport dynamics.
|
||||
---
|
||||
|
||||
# EVOLV Process Hydraulics Mass Balance
|
||||
|
||||
## Mission
|
||||
Preserve physically coherent hydraulics and conservation behavior across interacting EVOLV process nodes.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Build a flow and accumulation map from current node contracts.
|
||||
- Define invariants before edits:
|
||||
- no unplanned conservation breaks
|
||||
- split/merge behavior remains deterministic
|
||||
- retention/transport assumptions are explicit
|
||||
- Validate with scenario-based balance checks.
|
||||
|
||||
## Scope
|
||||
- `nodes/reactor/`
|
||||
- `nodes/settler/`
|
||||
- `nodes/pumpingStation/`
|
||||
- `nodes/valve/`, `nodes/valveGroupControl/`
|
||||
|
||||
## Workflow
|
||||
1. Identify control volumes and interfaces.
|
||||
2. Map inflow/outflow/storage terms and units.
|
||||
3. Validate steady-state and transient behavior under typical scenarios.
|
||||
4. Check edge cases: zero flow, reverse flow, surge, overflow.
|
||||
5. Confirm output contracts preserve balance observability.
|
||||
|
||||
## Standards
|
||||
- Keep units and sign conventions explicit.
|
||||
- Avoid hidden source/sink terms.
|
||||
- Document retention-time and mixing assumptions.
|
||||
- Preserve existing contracts unless migration is defined.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- mass/volume conservation under nominal operation
|
||||
- split/merge and bypass edge cases
|
||||
- boundary condition behavior at zero/low/high flow
|
||||
- numeric stability under long-run ticks
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- balance model and assumptions
|
||||
- changed files/tests with scenario evidence
|
||||
- unresolved hydraulic risks and required field checks
|
||||
|
||||
Decision interview triggers:
|
||||
- changes to balance assumptions affecting KPI/compliance outputs
|
||||
- compatibility-breaking payload/topic changes for flow/volume data
|
||||
- startup behavior changes with overflow/dry-run implications
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Process Hydraulics Mass Balance"
|
||||
short_description: "Flow, volume, and conservation behavior specialist"
|
||||
default_prompt: "Build a control-volume and flow map for impacted EVOLV nodes, enforce mass/volume balance invariants, validate transient and boundary scenarios, and return test-backed findings with unresolved hydraulic risks."
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
name: evolv-process-systems-control
|
||||
description: Design and review system-level control behavior across EVOLV process nodes. Use when coordinating multi-node interactions, mode/state transitions, parent-child registration flows, control loops, and complex process sequencing spanning reactors, valves, pumps, settlers, and machine groups.
|
||||
---
|
||||
|
||||
# EVOLV Process Systems Control
|
||||
|
||||
## Mission
|
||||
Preserve stable system-wide behavior across interacting Node-RED nodes and process assets.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Build a topic and ownership map from the current repo before changing behavior.
|
||||
- Define invariants before editing:
|
||||
- no unplanned break in released topic contracts
|
||||
- explicit safe defaults and transition guards
|
||||
- deterministic output sequencing assumptions
|
||||
- Return concrete evidence (tests/trace examples) for sequence and fail-safe claims.
|
||||
|
||||
## Scope
|
||||
- Cross-node interactions via `msg.topic`
|
||||
- Parent-child registration contracts (`registerChild` and related topics)
|
||||
- Mode management and sequencing in node wrappers/domain classes
|
||||
|
||||
## Message/Port Convention Baseline
|
||||
Many EVOLV nodes use this output convention:
|
||||
- output 0: process message
|
||||
- output 1: database/influx message
|
||||
- output 2: parent/registration/control plumbing
|
||||
|
||||
Preserve topic stability once released (`registerChild`, `setMode`, `setScaling`, etc). If a topic contract changes, define a migration path.
|
||||
|
||||
## Control Workflow
|
||||
1. Map control boundaries and authority (who commands whom).
|
||||
2. List topic contracts and payload schemas.
|
||||
3. Verify state/mode transition logic for race/conflict conditions.
|
||||
4. Define safe startup, shutdown, and failover behavior.
|
||||
5. Confirm tick timing and output ordering assumptions.
|
||||
|
||||
## Design Rules
|
||||
- Keep topic names stable once released.
|
||||
- Use explicit transition guards and default-safe modes.
|
||||
- Avoid hidden cross-coupling between unrelated assets.
|
||||
- Make control intent observable in outputs/status.
|
||||
|
||||
## Test Expectations
|
||||
Add tests for:
|
||||
- normal sequence transitions
|
||||
- out-of-order messages
|
||||
- duplicate child registration and dedupe behavior
|
||||
- fail-safe behavior under missing dependencies
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- system interaction map (topics + ownership)
|
||||
- transition table and safety guards
|
||||
- changed files/tests
|
||||
- unresolved control hazards with mitigation suggestions
|
||||
|
||||
Decision interview triggers:
|
||||
- any topic rename/removal or payload schema break
|
||||
- authority changes across parent/child nodes
|
||||
- startup/shutdown sequencing changes with operational impact
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Systems Control Engineer"
|
||||
short_description: "Design robust multi-node process control"
|
||||
default_prompt: "Engineer EVOLV system control from a repo-grounded topic/ownership map, preserve transition and fail-safe invariants, validate sequencing behavior with evidence, and escalate decision-gate questions for contract-breaking control changes."
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
name: evolv-quality-technical-debt
|
||||
description: Drive code quality, regression prevention, and technical debt management for EVOLV nodes. Use when reviewing changes for bugs, maintainability, test completeness, architectural drift, and when creating prioritized remediation plans for JavaScript/CommonJS Node-RED modules.
|
||||
---
|
||||
|
||||
# EVOLV Quality Technical Debt
|
||||
|
||||
## Mission
|
||||
Raise delivery reliability by detecting defects early and systematically reducing technical debt in EVOLV nodes.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Anchor findings to concrete file/line evidence.
|
||||
- Separate correctness risk from style preferences.
|
||||
- Require regression-proof evidence for fixes (tests that fail-before/pass-after when feasible).
|
||||
- Feed recurring failure patterns back into the relevant skill guidance.
|
||||
|
||||
## Scope
|
||||
- Node implementation quality in `nodes/<nodeName>/src/`
|
||||
- Editor/runtime contract consistency in `.html` + runtime wrappers
|
||||
- Shared utility hygiene in `nodes/generalFunctions/`
|
||||
- Test depth in `nodes/<nodeName>/test/`
|
||||
|
||||
## Test Policy Baseline
|
||||
All code changes require tests under `nodes/<nodeName>/test/`.
|
||||
|
||||
Cover at minimum:
|
||||
- config default/override behavior and numeric coercion
|
||||
- each supported `msg.topic` handler with edge cases
|
||||
- child registration and dedupe side effects
|
||||
- tick/output boundaries and error paths
|
||||
- regression tests for fixed bugs
|
||||
|
||||
Execution:
|
||||
- preferred: `node --test nodes/<nodeName>/test/*.test.js`
|
||||
- fallback: `node nodes/<nodeName>/test/<file>.test.js`
|
||||
|
||||
## Review Workflow
|
||||
1. Assess correctness risks first (runtime errors, logic regressions, broken topic contracts).
|
||||
2. Assess maintainability (duplication, unclear ownership, implicit behavior).
|
||||
3. Assess test adequacy against EVOLV policy:
|
||||
- config defaults/overrides
|
||||
- topic handlers and edge cases
|
||||
- tick/output boundaries
|
||||
- regressions for fixed bugs
|
||||
4. Create a prioritized debt backlog with effort and impact.
|
||||
|
||||
## Quality Criteria
|
||||
- Domain logic remains testable without full Node-RED runtime.
|
||||
- Complex logic is explicit and minimally coupled.
|
||||
- Backward compatibility is deliberate and documented.
|
||||
- New behavior includes tests that fail before and pass after.
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- findings by severity
|
||||
- test gaps and specific cases to add
|
||||
- debt backlog (now/next/later)
|
||||
- recommended refactors with expected payoff
|
||||
|
||||
Decision interview triggers:
|
||||
- tradeoff between delivery speed and known high-severity risk
|
||||
- acceptance of temporary risk with deferred remediation
|
||||
- testing scope reductions that materially raise regression risk
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Quality + Debt Engineer"
|
||||
short_description: "Drive code quality and technical debt reduction"
|
||||
default_prompt: "Review EVOLV code with evidence-anchored findings, prioritize correctness and regression risk, require verification for fixes, and frame explicit decision-gate tradeoffs when risk is accepted or testing is reduced."
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
name: evolv-regulatory-compliance-wastewater
|
||||
description: Apply wastewater regulatory and compliance constraints to EVOLV control and telemetry design. Use when reviewing effluent-quality KPIs, reporting semantics, auditability, traceability of control actions, and compliance-impacting alarm/control decisions.
|
||||
---
|
||||
|
||||
# EVOLV Regulatory Compliance Wastewater
|
||||
|
||||
## Mission
|
||||
Ensure EVOLV changes remain auditable and aligned with wastewater compliance/reporting obligations.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Map compliance-relevant outputs and control decisions from current repo contracts.
|
||||
- Define invariants before edits:
|
||||
- compliance KPIs remain traceable
|
||||
- auditability of major control actions is preserved
|
||||
- reporting semantics are stable or explicitly migrated
|
||||
- Validate with evidence that supports audit/review workflows.
|
||||
|
||||
## Scope
|
||||
- Effluent-related outputs and quality calculations in process nodes
|
||||
- Alarm and control behaviors that affect permit-critical operation
|
||||
- Telemetry/reporting contracts consumed by dashboards/reports
|
||||
|
||||
## Workflow
|
||||
1. Identify compliance-relevant metrics and events.
|
||||
2. Trace data lineage from sensor/input to reported output.
|
||||
3. Verify timestamp/quality metadata sufficiency for audits.
|
||||
4. Review alarm/control actions that can affect permit outcomes.
|
||||
5. Define documentation and test evidence for compliance-critical paths.
|
||||
|
||||
## Standards
|
||||
- Prefer explicit semantics over inferred compliance logic.
|
||||
- Preserve historical comparability of compliance KPIs.
|
||||
- Ensure traceability of overrides, trips, and degraded operation.
|
||||
- Keep evidence artifacts reproducible and review-friendly.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- compliance KPI payload consistency
|
||||
- traceability fields presence (timestamp/source/quality where applicable)
|
||||
- alarm/control transitions relevant to permit risk
|
||||
- behavior under missing or suspect compliance measurements
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- compliance impact map and assumptions
|
||||
- changed files/tests with audit-focused evidence
|
||||
- unresolved compliance risks and mitigation recommendations
|
||||
|
||||
Decision interview triggers:
|
||||
- any change that can alter reported compliance values
|
||||
- changed retention/backfill semantics for compliance reporting
|
||||
- reduced auditability or traceability in control/telemetry paths
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Regulatory Compliance Wastewater"
|
||||
short_description: "Compliance and auditability specialist"
|
||||
default_prompt: "Assess compliance impact of the proposed EVOLV changes, trace KPI lineage and control actions relevant to permits, validate auditability fields and behaviors, and return risk-focused recommendations with evidence requirements."
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
name: evolv-telemetry-analytics-dashboards
|
||||
description: Design telemetry-to-dashboard contracts for EVOLV operations analytics. Use when defining KPI semantics, chart/topic contracts, aggregation windows, operator diagnostics, and compatibility between node outputs, Influx schema, and dashboard consumers.
|
||||
---
|
||||
|
||||
# EVOLV Telemetry Analytics Dashboards
|
||||
|
||||
## Mission
|
||||
Keep EVOLV telemetry contracts stable, queryable, and useful for operators and performance analysis.
|
||||
|
||||
## Harness Execution Contract
|
||||
- Start from current output payloads, Influx schema assumptions, and dashboard queries.
|
||||
- Define invariants before edits:
|
||||
- KPI semantics remain explicit and comparable over time
|
||||
- topic/field naming stability is preserved or migrated
|
||||
- dashboard failure modes are diagnosable
|
||||
- Validate with query-level and chart-level evidence.
|
||||
|
||||
## Scope
|
||||
- Node outputs in `nodes/*/src/nodeClass.js`
|
||||
- Influx-related contract points and dashboard config/manuals
|
||||
- FlowFuse chart usage and topic/category consistency
|
||||
|
||||
## Workflow
|
||||
1. Inventory KPI producers and consumers.
|
||||
2. Define measurement/tag/field/topic contracts.
|
||||
3. Validate aggregation/downsampling assumptions.
|
||||
4. Ensure chart wiring remains consistent (`msg.topic` category baseline).
|
||||
5. Verify operator readability and anomaly visibility.
|
||||
|
||||
## Standards
|
||||
- Keep KPI definitions versioned and unambiguous.
|
||||
- Preserve backward compatibility for released dashboards.
|
||||
- Avoid overloading fields with mixed semantics.
|
||||
- Pair every contract change with migration notes.
|
||||
|
||||
## Test Expectations
|
||||
Cover:
|
||||
- payload field presence/types for key KPIs
|
||||
- topic/category compatibility for charts
|
||||
- query compatibility for existing dashboards
|
||||
- behavior under missing/null data windows
|
||||
|
||||
## Deliverables
|
||||
Return:
|
||||
- KPI and telemetry contract map
|
||||
- changed files/tests and dashboard impact notes
|
||||
- migration/deprecation notes if compatibility changed
|
||||
|
||||
Decision interview triggers:
|
||||
- KPI definition changes affecting reporting decisions
|
||||
- dashboard contract breaks requiring migration
|
||||
- retention/aggregation changes impacting trend interpretation
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "EVOLV Telemetry Analytics Dashboards"
|
||||
short_description: "KPI and dashboard contract specialist"
|
||||
default_prompt: "Map telemetry producers/consumers for impacted EVOLV outputs, preserve KPI and chart contracts, validate query compatibility and null-data behavior, and return migration notes where needed."
|
||||
Reference in New Issue
Block a user