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,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,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,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,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,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,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,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,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,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,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,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,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,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,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,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."
|
||||
@@ -41,8 +41,8 @@ You are a biological process engineer specializing in wastewater treatment model
|
||||
- `.agents/function-anchors/monster/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-biological-process-engineering/SKILL.md`
|
||||
- `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
- `.claude/skills/evolv-biological-process-engineering/SKILL.md`
|
||||
- `.claude/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Kinetic rates have correct temperature compensation
|
||||
@@ -53,4 +53,4 @@ You are a biological process engineer specializing in wastewater treatment model
|
||||
- [ ] Retention times consistent with reactor geometry and flow
|
||||
|
||||
## Reasoning Difficulty: Very High
|
||||
This agent handles ASM kinetics, mass balance calculations, temperature compensation, and sludge settling models — some of the most complex scientific reasoning in the platform. Incorrect stoichiometric coefficients, missed temperature corrections, or flawed mass balance closures can propagate silently through reactor simulations. When uncertain, consult `third_party/docs/asm-models.md`, `third_party/docs/settling-models.md`, and `.agents/skills/evolv-biological-process-engineering/SKILL.md` before making claims about biological process behavior.
|
||||
This agent handles ASM kinetics, mass balance calculations, temperature compensation, and sludge settling models — some of the most complex scientific reasoning in the platform. Incorrect stoichiometric coefficients, missed temperature corrections, or flawed mass balance closures can propagate silently through reactor simulations. When uncertain, consult `third_party/docs/asm-models.md`, `third_party/docs/settling-models.md`, and `.claude/skills/evolv-biological-process-engineering/SKILL.md` before making claims about biological process behavior.
|
||||
|
||||
@@ -43,9 +43,9 @@ You are a commissioning and compliance specialist for the EVOLV wastewater treat
|
||||
- Mode changes (auto→manual, simulation→physical) are compliance-relevant events
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-commissioning-validation/SKILL.md`
|
||||
- `.agents/skills/evolv-regulatory-compliance-wastewater/SKILL.md`
|
||||
- `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
- `.claude/skills/evolv-commissioning-validation/SKILL.md`
|
||||
- `.claude/skills/evolv-regulatory-compliance-wastewater/SKILL.md`
|
||||
- `.claude/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Compliance-relevant output fields unchanged (or migration documented)
|
||||
@@ -56,4 +56,4 @@ You are a commissioning and compliance specialist for the EVOLV wastewater treat
|
||||
- [ ] Control-action traceability maintained through the change
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles regulatory compliance context, audit trail requirements, and simulation-to-field validation gaps. Dutch wastewater regulations (Waterschapswet, EU UWWTD) have specific monitoring and reporting obligations that code changes can inadvertently violate. When uncertain, consult `third_party/docs/wastewater-compliance-nl.md` and `.agents/skills/evolv-commissioning-validation/SKILL.md` before making claims about compliance requirements.
|
||||
This agent handles regulatory compliance context, audit trail requirements, and simulation-to-field validation gaps. Dutch wastewater regulations (Waterschapswet, EU UWWTD) have specific monitoring and reporting obligations that code changes can inadvertently violate. When uncertain, consult `third_party/docs/wastewater-compliance-nl.md` and `.claude/skills/evolv-commissioning-validation/SKILL.md` before making claims about compliance requirements.
|
||||
|
||||
@@ -29,7 +29,7 @@ You are the EVOLV orchestrator agent. You decompose complex tasks, route to spec
|
||||
- Canonical internal units: Pa, m³/s, W, K
|
||||
|
||||
## Workflow
|
||||
1. Read `.agents/skills/evolv-orchestrator/SKILL.md` for full orchestration protocol
|
||||
1. Read `.claude/skills/evolv-orchestrator/SKILL.md` for full orchestration protocol
|
||||
2. Build an impact map: which nodes, contracts, and shared modules are affected?
|
||||
3. Identify the minimum set of specialist agents needed
|
||||
4. Decompose into sequenced subtasks with clear acceptance criteria
|
||||
@@ -44,7 +44,7 @@ You are the EVOLV orchestrator agent. You decompose complex tasks, route to spec
|
||||
- `CONTRACTS.md` (EVOLV root) — front-door map: where every contract, rule, and standard lives
|
||||
- `.claude/refactor/CONTRACTS.md` — platform API shapes (BaseDomain, BaseNodeAdapter, commands registry, …)
|
||||
- `.claude/refactor/OPEN_QUESTIONS.md` — live decisions log
|
||||
- `.agents/skills/evolv-orchestrator/SKILL.md` — Full orchestration protocol
|
||||
- `.claude/skills/evolv-orchestrator/SKILL.md` — Full orchestration protocol
|
||||
- `.agents/AGENTS.md` — Agent invocation policy and routing table
|
||||
- `.agents/improvements/IMPROVEMENTS_BACKLOG.md` — Deferred improvements
|
||||
|
||||
@@ -55,4 +55,4 @@ You are the EVOLV orchestrator agent. You decompose complex tasks, route to spec
|
||||
- Owner-approved defaults: compatibility=controlled, safety=availability-first
|
||||
|
||||
## Reasoning Difficulty: Medium-High
|
||||
This agent handles multi-domain task decomposition, cross-cutting impact analysis, and decision governance enforcement. The primary challenge is correctly mapping changes across node boundaries — a single modification can cascade through parent-child relationships, shared contracts, and InfluxDB semantics. When uncertain about cross-domain impact, consult `.agents/skills/evolv-orchestrator/SKILL.md` and `.agents/AGENTS.md` before routing to specialist agents.
|
||||
This agent handles multi-domain task decomposition, cross-cutting impact analysis, and decision governance enforcement. The primary challenge is correctly mapping changes across node boundaries — a single modification can cascade through parent-child relationships, shared contracts, and InfluxDB semantics. When uncertain about cross-domain impact, consult `.claude/skills/evolv-orchestrator/SKILL.md` and `.agents/AGENTS.md` before routing to specialist agents.
|
||||
|
||||
@@ -45,7 +45,7 @@ dashboardAPI, diffuser, machineGroupControl, measurement, monster, pumpingStatio
|
||||
- `nodes/generalFunctions/src/*/` — Individual module directories
|
||||
|
||||
## Reference Skills
|
||||
- All `.agents/skills/` depending on which module is being changed:
|
||||
- All `.claude/skills/` depending on which module is being changed:
|
||||
- predict/interpolation/loadCurve → `evolv-mechanical-rotating-equipment`
|
||||
- MeasurementContainer/nrmse/convert → `evolv-instrumentation-assets`
|
||||
- outputUtils → `evolv-database-influx-architecture`
|
||||
@@ -59,4 +59,4 @@ dashboardAPI, diffuser, machineGroupControl, measurement, monster, pumpingStatio
|
||||
- Prefer additive changes (new exports) over breaking changes (renamed/removed exports)
|
||||
|
||||
## Reasoning Difficulty: Medium-High
|
||||
This agent manages a shared library consumed by all 13 nodes. Individual module changes are often straightforward, but the cross-node impact analysis is challenging — a subtle behavior change in interpolation or predict can cascade through rotatingMachine, pumpingStation, and machineGroupControl simultaneously. When uncertain about impact scope, grep for imports across `nodes/*/src/` and consult the relevant `.agents/skills/` for the module being changed.
|
||||
This agent manages a shared library consumed by all 13 nodes. Individual module changes are often straightforward, but the cross-node impact analysis is challenging — a subtle behavior change in interpolation or predict can cascade through rotatingMachine, pumpingStation, and machineGroupControl simultaneously. When uncertain about impact scope, grep for imports across `nodes/*/src/` and consult the relevant `.claude/skills/` for the module being changed.
|
||||
|
||||
@@ -43,8 +43,8 @@ You are an instrumentation engineer specializing in sensor measurement, signal c
|
||||
- `.agents/function-anchors/measurement/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-instrumentation-assets/SKILL.md`
|
||||
- `.agents/skills/evolv-measurement-product-specialist/SKILL.md`
|
||||
- `.claude/skills/evolv-instrumentation-assets/SKILL.md`
|
||||
- `.claude/skills/evolv-measurement-product-specialist/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Unit conversions chain correctly (no double-conversion)
|
||||
@@ -55,4 +55,4 @@ You are an instrumentation engineer specializing in sensor measurement, signal c
|
||||
- [ ] MeasurementContainer fields populated consistently
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles signal processing, NRMSE-based drift detection, sensor behavior modeling, and data quality propagation. Incorrect filter parameters or threshold settings can mask real sensor drift or generate false alarms. When uncertain, consult `third_party/docs/signal-processing-sensors.md` and `.agents/skills/evolv-instrumentation-assets/SKILL.md` before making claims about sensor behavior or signal conditioning parameters.
|
||||
This agent handles signal processing, NRMSE-based drift detection, sensor behavior modeling, and data quality propagation. Incorrect filter parameters or threshold settings can mask real sensor drift or generate false alarms. When uncertain, consult `third_party/docs/signal-processing-sensors.md` and `.claude/skills/evolv-instrumentation-assets/SKILL.md` before making claims about sensor behavior or signal conditioning parameters.
|
||||
|
||||
@@ -50,9 +50,9 @@ You are a mechanical and process engineer specializing in rotating equipment, hy
|
||||
- `.agents/function-anchors/valve/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-mechanical-rotating-equipment/SKILL.md`
|
||||
- `.agents/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
- `.agents/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
- `.claude/skills/evolv-mechanical-rotating-equipment/SKILL.md`
|
||||
- `.claude/skills/evolv-process-hydraulics-mass-balance/SKILL.md`
|
||||
- `.claude/skills/evolv-alarms-interlocks-permissives/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Unit conversions use canonical system (Pa, m³/s, W, K internally)
|
||||
@@ -63,4 +63,4 @@ You are a mechanical and process engineer specializing in rotating equipment, hy
|
||||
- [ ] System curve intersection validated for duty point calculations
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles physics validation involving affinity laws, pump curve theory, system curve intersections, and unit system rigor. Errors in hydraulic calculations or VFD scaling can produce physically impossible results that look numerically plausible. When uncertain, consult `third_party/docs/pump-affinity-laws.md`, `third_party/docs/pid-control-theory.md`, and `.agents/skills/evolv-mechanical-rotating-equipment/SKILL.md` before making claims about mechanical behavior.
|
||||
This agent handles physics validation involving affinity laws, pump curve theory, system curve intersections, and unit system rigor. Errors in hydraulic calculations or VFD scaling can produce physically impossible results that look numerically plausible. When uncertain, consult `third_party/docs/pump-affinity-laws.md`, `third_party/docs/pid-control-theory.md`, and `.claude/skills/evolv-mechanical-rotating-equipment/SKILL.md` before making claims about mechanical behavior.
|
||||
|
||||
@@ -38,8 +38,8 @@ You are a Node-RED runtime and editor specialist for the EVOLV platform. You und
|
||||
- `nodes/generalFunctions/` — Shared utilities (MenuManager, configManager, logger, etc.)
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-frontend-node-red/SKILL.md` — Detailed Node-RED frontend patterns
|
||||
- `.agents/skills/evolv-process-systems-control/SKILL.md` — Control architecture and topic contracts
|
||||
- `.claude/skills/evolv-frontend-node-red/SKILL.md` — Detailed Node-RED frontend patterns
|
||||
- `.claude/skills/evolv-process-systems-control/SKILL.md` — Control architecture and topic contracts
|
||||
|
||||
## Rules
|
||||
- Never put `RED.*` calls in specificClass — that's nodeClass territory
|
||||
@@ -48,4 +48,4 @@ You are a Node-RED runtime and editor specialist for the EVOLV platform. You und
|
||||
- Always check `generalFunctions` MenuManager/configManager when modifying config flows
|
||||
|
||||
## Reasoning Difficulty: Medium
|
||||
Node-RED patterns are well-documented with clear conventions. The main risk is editor/runtime synchronization — changes to admin endpoints, HTML forms, or registration patterns can silently break the editor without runtime errors. When uncertain, consult `.agents/skills/evolv-frontend-node-red/SKILL.md` and the Node-RED documentation before making structural changes.
|
||||
Node-RED patterns are well-documented with clear conventions. The main risk is editor/runtime synchronization — changes to admin endpoints, HTML forms, or registration patterns can silently break the editor without runtime errors. When uncertain, consult `.claude/skills/evolv-frontend-node-red/SKILL.md` and the Node-RED documentation before making structural changes.
|
||||
|
||||
@@ -35,8 +35,8 @@ You are an OT/IT security and edge integration specialist for the EVOLV industri
|
||||
- Watchdog timers for connection health monitoring
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-ot-it-security/SKILL.md`
|
||||
- `.agents/skills/evolv-ot-edge-plc-integration/SKILL.md`
|
||||
- `.claude/skills/evolv-ot-it-security/SKILL.md`
|
||||
- `.claude/skills/evolv-ot-edge-plc-integration/SKILL.md`
|
||||
|
||||
## Scope
|
||||
- Admin endpoints (`GET /<nodeName>/menu.js`, `GET /<nodeName>/configData.js`)
|
||||
@@ -55,4 +55,4 @@ You are an OT/IT security and edge integration specialist for the EVOLV industri
|
||||
- [ ] Control messages validated before actuator commands are issued
|
||||
|
||||
## Reasoning Difficulty: High
|
||||
This agent handles industrial threat modeling, OT protocol security, and fail-safe analysis. Security in industrial systems has physical safety implications — a missed input validation on a control message could lead to unsafe actuator commands. When uncertain, consult `third_party/docs/ot-security-iec62443.md` and `.agents/skills/evolv-ot-it-security/SKILL.md` before making claims about security boundaries or protocol safety.
|
||||
This agent handles industrial threat modeling, OT protocol security, and fail-safe analysis. Security in industrial systems has physical safety implications — a missed input validation on a control message could lead to unsafe actuator commands. When uncertain, consult `third_party/docs/ot-security-iec62443.md` and `.claude/skills/evolv-ot-it-security/SKILL.md` before making claims about security boundaries or protocol safety.
|
||||
|
||||
@@ -49,8 +49,8 @@ node --test nodes/<nodeName>/test/edge/*.test.js
|
||||
- `nodes/*/examples/` — Example flows
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-quality-technical-debt/SKILL.md`
|
||||
- `.agents/skills/evolv-commissioning-validation/SKILL.md`
|
||||
- `.claude/skills/evolv-quality-technical-debt/SKILL.md`
|
||||
- `.claude/skills/evolv-commissioning-validation/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] All 3 test tiers present (basic/integration/edge)
|
||||
@@ -62,4 +62,4 @@ node --test nodes/<nodeName>/test/edge/*.test.js
|
||||
- [ ] Code complexity reasonable (no god functions, clear naming)
|
||||
|
||||
## Reasoning Difficulty: Medium
|
||||
Test patterns are straightforward and the 3-tier structure provides clear guidance. The harder challenge is cross-node regression detection — a change in generalFunctions can silently break downstream nodes whose tests still pass in isolation. When uncertain, consult `.agents/skills/evolv-quality-technical-debt/SKILL.md` and `.agents/function-anchors/` for behavioral contracts before writing or modifying tests.
|
||||
Test patterns are straightforward and the 3-tier structure provides clear guidance. The harder challenge is cross-node regression detection — a change in generalFunctions can silently break downstream nodes whose tests still pass in isolation. When uncertain, consult `.claude/skills/evolv-quality-technical-debt/SKILL.md` and `.agents/function-anchors/` for behavioral contracts before writing or modifying tests.
|
||||
|
||||
@@ -45,8 +45,8 @@ You are a telemetry and database specialist for the EVOLV platform, focusing on
|
||||
- `.agents/function-anchors/dashboardAPI/`
|
||||
|
||||
## Reference Skills
|
||||
- `.agents/skills/evolv-database-influx-architecture/SKILL.md`
|
||||
- `.agents/skills/evolv-telemetry-analytics-dashboards/SKILL.md`
|
||||
- `.claude/skills/evolv-database-influx-architecture/SKILL.md`
|
||||
- `.claude/skills/evolv-telemetry-analytics-dashboards/SKILL.md`
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] Tags are low-cardinality only (no timestamps, UUIDs, free-text)
|
||||
@@ -57,4 +57,4 @@ You are a telemetry and database specialist for the EVOLV platform, focusing on
|
||||
- [ ] Retention policy matches data criticality and storage constraints
|
||||
|
||||
## Reasoning Difficulty: Medium
|
||||
InfluxDB schema design is well-understood, and the Port 1 telemetry contract is consistent across nodes. The main risk area is cardinality management — adding a high-cardinality tag can silently degrade query performance until it becomes critical. When uncertain, consult `third_party/docs/influxdb-schema-design.md` and `.agents/skills/evolv-database-influx-architecture/SKILL.md` before making schema changes.
|
||||
InfluxDB schema design is well-understood, and the Port 1 telemetry contract is consistent across nodes. The main risk area is cardinality management — adding a high-cardinality tag can silently degrade query performance until it becomes critical. When uncertain, consult `third_party/docs/influxdb-schema-design.md` and `.claude/skills/evolv-database-influx-architecture/SKILL.md` before making schema changes.
|
||||
|
||||
@@ -211,7 +211,7 @@ post-refactor shape, not the in-flight transition).
|
||||
|
||||
| # | Task | Notes |
|
||||
|---|---|---|
|
||||
| 9.1 | Author the canonical wiki template at `.claude/refactor/WIKI_TEMPLATE.md` (or the repo-mem rule path) | Source of truth. |
|
||||
| 9.1 | Author the canonical wiki template at `.claude/refactor/WIKI_TEMPLATE.md` | Source of truth. |
|
||||
| 9.2 | Build the auto-generator: `commands/index.js` → "Topic contract" markdown section | Run via a small `npm run wiki:contract` script per node. |
|
||||
| 9.3 | Pilot on `pumpingStation` wiki: replace existing pages with the new template | Visual-first, prune prose. |
|
||||
| 9.4 | Apply to other 3 core nodes (`measurement`, `MGC`, `rotatingMachine`) | |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
---
|
||||
paths:
|
||||
- "nodes/*/*.js"
|
||||
- "nodes/*/*.html"
|
||||
- "nodes/*/src/**"
|
||||
---
|
||||
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
paths:
|
||||
- "nodes/*/examples/**"
|
||||
- "examples/**"
|
||||
---
|
||||
|
||||
# Node-RED Flow Layout Rules
|
||||
|
||||
How to lay out a multi-tab Node-RED demo or production flow so it is readable, debuggable, and trivially extendable. These rules apply to anything you build with `examples/` flows, dashboards, or production deployments.
|
||||
|
||||
@@ -1,80 +0,0 @@
|
||||
# repo-mem MCP Tools
|
||||
|
||||
This repo has a per-repo memory MCP server (`repo-mem`) wired via `.mcp.json`. It exposes 5 tools backed by a Hopfield substrate trained on EVOLV's source plus a BM25 index over file chunks. **Use them. They are faster and better-targeted than `grep` for concept queries, and they accumulate institutional memory of repairs.**
|
||||
|
||||
If `/mcp` does not list `repo-mem` as Connected, the rest of this file does not apply for this session — fall back to `grep` / `Read`.
|
||||
|
||||
## When to call which tool
|
||||
|
||||
### `repo_search(query, k=8)` — primary lookup tool
|
||||
Use **before** `grep` / `find` / `Explore` agent for any natural-language "where is X handled / find all places that do Y / what code implements Z" question.
|
||||
|
||||
- ✅ "where is the predicted volume integrator?" → `repo_search`
|
||||
- ✅ "find places that emit InfluxDB line protocol" → `repo_search`
|
||||
- ❌ "find every occurrence of `_updatePredictedVolume`" → `grep` (exact symbol — BM25 doesn't beat grep at exact-string lookup)
|
||||
- ❌ "list all `.test.js` files" → `find` / `ls` (no concept query)
|
||||
|
||||
Returns top-K files with `file:line` ranges and snippets. Read the snippet first; only open the file if the snippet doesn't answer the question.
|
||||
|
||||
### `repo_similar_fixes(query, failure?, files?, tags?, k=5)` — start-of-task context
|
||||
Call at the **start** of any non-trivial bug fix or behavioral change. Cheap (BM25 + file overlap + atom cosine), zero downside if it returns nothing useful.
|
||||
|
||||
- Pass the user's task description as `query`.
|
||||
- If there's a failing test or stack trace, pass it as `failure`.
|
||||
- If you already know which files are involved, pass them as `files`.
|
||||
- Skim the returned traces; surface any near-match to the user before starting.
|
||||
|
||||
### `repo_record_fix({task, failure, files, diff_summary, patch, tests, outcome, tags})` — end-of-task persist
|
||||
Call at the **end** of a landed fix or behavioral change, **before** reporting completion to the user. Skip for trivial typo/comment commits. Required fields: `task` and `outcome`. Recommended:
|
||||
- `failure`: the symptom that prompted the work (test output, user description, stack trace).
|
||||
- `files`: the files actually changed.
|
||||
- `diff_summary`: 1–3 sentences on *what* changed and *why*.
|
||||
- `patch`: the unified diff (truncate to the load-bearing hunks if huge).
|
||||
- `tests`: the verification command(s) you ran.
|
||||
- `outcome`: `passed` / `failed` / `partial` / `reverted`.
|
||||
- `tags`: short labels (`overflow-clamp`, `tokenizer`, `migration`, etc.) for retrieval bias.
|
||||
|
||||
Rule of thumb: if the change took more than one read+edit pair, record it.
|
||||
|
||||
### `substrate_score(text, worst_k=5)` — OOD-token check
|
||||
Use **sparingly**. After generating a non-trivial code block (≥ ~30 lines of new logic, not test scaffolding), pass it through `substrate_score` and inspect the worst-confidence positions for typos, wrong identifiers, or out-of-house style. Noisy on small additions — don't use it for one-line tweaks.
|
||||
|
||||
### `substrate_top_next(context, k=10)` — rarely
|
||||
Predicts next BPE-subword tokens in the local style. Mostly useful for autonomous solver loops; in interactive review it's diagnostic only. If you find yourself wanting it, you probably want `repo_search` instead.
|
||||
|
||||
## Workflow shape
|
||||
|
||||
```
|
||||
new task arrives
|
||||
↓
|
||||
repo_similar_fixes(query=user_task) ← cheap, always do this for non-trivial tasks
|
||||
↓
|
||||
repo_search(query=concept) ← when scoping
|
||||
↓
|
||||
[normal Read / Edit / Bash work]
|
||||
↓
|
||||
[after generating non-trivial new code]
|
||||
substrate_score(text=new_block) ← optional, only if block is big
|
||||
↓
|
||||
[verify: tests / build / smoke]
|
||||
↓
|
||||
repo_record_fix({...}) ← before final user-facing summary
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- ❌ Calling `repo_search` when you already know the file path. Just `Read` it.
|
||||
- ❌ Calling `repo_record_fix` after every micro-edit. Only at meaningful task boundaries.
|
||||
- ❌ Treating `substrate_top_next` results as authoritative — they reflect repo style, not correctness.
|
||||
- ❌ Passing the full conversation to `substrate_score` — it's per-snippet, not per-session.
|
||||
|
||||
## Refresh model
|
||||
|
||||
The post-commit hook auto-runs `--quick --lock` (re-ingest + BM25 + chunk re-embed; substrate retrain skipped) so retrieval stays current within ~2 s of any commit. The substrate itself is only retrained when you (or a maintainer) run `--full` manually:
|
||||
|
||||
```bash
|
||||
node ~/anchor-net-master/tools/repo-mem/refresh.mjs \
|
||||
--repo . --in .repo-mem --full
|
||||
```
|
||||
|
||||
Re-train when the repo gains substantially new vocabulary (new node, new domain, new dependency surface). Otherwise BM25 + existing atoms keep up.
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
paths:
|
||||
- "nodes/*/src/nodeClass.js"
|
||||
- "nodes/*/src/specificClass.js"
|
||||
- "nodes/*/src/output/**"
|
||||
- "nodes/generalFunctions/src/outputUtils/**"
|
||||
---
|
||||
|
||||
# Telemetry Rules
|
||||
|
||||
2
.gitignore
vendored
2
.gitignore
vendored
@@ -8,8 +8,6 @@ npm-debug.log*
|
||||
|
||||
# Build artifacts
|
||||
*.tgz
|
||||
# repo-mem regenerable indexes
|
||||
.repo-mem/
|
||||
|
||||
# Per-session runtime locks (scheduled_tasks, etc.)
|
||||
.claude/*.lock
|
||||
|
||||
21
CLAUDE.md
21
CLAUDE.md
@@ -1,8 +1,7 @@
|
||||
# EVOLV - Claude Code Project Guide
|
||||
|
||||
> **READ FIRST, BEFORE ANY OTHER WORK:**
|
||||
> 1. [`CONTRACTS.md`](./CONTRACTS.md) — front-door map: where every contract, rule, and standard lives, and how to find them.
|
||||
> 2. [`.claude/rules/repo-mem.md`](./.claude/rules/repo-mem.md) — this repo has an MCP server (`repo-mem`) exposing a substrate-trained `repo_search` and a persistent fix-trace store. Use those instead of `grep` for concept queries, and record completed fixes via `repo_record_fix`.
|
||||
> [`CONTRACTS.md`](./CONTRACTS.md) — front-door map: where every contract, rule, and standard lives, and how to find them.
|
||||
|
||||
## What This Is
|
||||
Node-RED custom nodes package for wastewater treatment plant automation. Developed by Waterschap Brabantse Delta R&D team. Follows ISA-88 (S88) batch control standard.
|
||||
@@ -51,11 +50,27 @@ mismatches in the meantime):
|
||||
- Nodes register under category `'EVOLV'` in Node-RED
|
||||
- S88 color scheme: Area=#0f52a5, ProcessCell=#0c99d9, Unit=#50a8d9, Equipment=#86bbdd, ControlModule=#a9daee
|
||||
- Config JSON files in `generalFunctions/src/configs/` define defaults, types, enums per node
|
||||
- Tick loop runs at 1000ms intervals for time-based updates
|
||||
- Tick loop is **opt-in per node** — default cadence 1000 ms, but each node sets `static tickInterval` (or skips it). See `.claude/refactor/OPEN_QUESTIONS.md` (2026-05-10 entry) for the design decision
|
||||
- Output ports + 3-tier architecture + file-naming + `src/editor/` layout: see `.claude/rules/node-architecture.md`
|
||||
- **Multi-tab demo flows**: see `.claude/rules/node-red-flow-layout.md` for the tab/link-channel/spacing rule set used by `examples/`
|
||||
- **Output coverage** (every output, every state, every layer): see `.claude/rules/output-coverage.md` — manifest + populated/degraded tests are mandatory for any change that touches Port 0/1/2 keys, function-node fan-outs, telemetry fields, or dashboard widget sources
|
||||
|
||||
## Agents and Skills (use them — don't reinvent)
|
||||
- **Skills** at `.claude/skills/evolv-*/SKILL.md` (15 domain skills) — auto-discovered, invoke via the `Skill` tool. Load them when you need domain reasoning (rotating equipment, biology, telemetry, security, instrumentation, hydraulics, alarms, OT integration, regulatory, quality, commissioning, frontend, …).
|
||||
- **Subagents** at `.claude/agents/*.md` (10 Claude Code subagents) — spawnable via `Agent(subagent_type: '<name>')`. Use for independent work: `evolv-orchestrator` (multi-domain decomposition + `team` workflows), `mechanical-process-engineer`, `biological-process-engineer`, `instrumentation-measurement`, `node-red-runtime`, `telemetry-database`, `quality-test-engineer`, `commissioning-compliance`, `ot-security-integration`, `general-functions-library`.
|
||||
- **Routing table**: [`.agents/AGENTS.md`](./.agents/AGENTS.md) maps task patterns → which skill/subagent to invoke.
|
||||
- **`team` keyword**: when the user says "team", spawn `evolv-orchestrator` (subagent) — it picks specialists, runs an alignment pass, returns one integrated answer.
|
||||
|
||||
## Tooling (Docker-first, local now, central later)
|
||||
Custom EVOLV tooling lives in `tools/` and is intended to run inside the local Docker compose stack (`tools/docker-compose.yml`). **Always prefer these tools over ad-hoc grep/curl/manual checks** — they encode the rules in `.claude/rules/` and catch regressions the human review would miss:
|
||||
- `tools/flow-lint/` — validates `examples/*.flow.json` against `.claude/rules/node-red-flow-layout.md`. Run before committing any flow change.
|
||||
- `tools/output-manifest-verify/` — diffs declared Port 0/1/2 keys vs. runtime emissions. Run on any output-shape change.
|
||||
- `tools/contract-verify/` — diffs `nodes/<n>/CONTRACT.md` vs. `src/commands/index.js`. Run after touching a command registry.
|
||||
- `tools/wiki-gen/` — regenerates topic-contract + data-model sections of `nodes/<n>/wiki/`. Run after a CONTRACT change.
|
||||
- `tools/physics-sanity/` — cross-node mass/hydraulic/energy balance assertions. Run as part of `node --test` for cross-node changes.
|
||||
- **MCP services** (Node-RED admin, InfluxDB, headless browser) live under `tools/mcp/` as Docker services. **Migration note**: these will move to a central MCP server later; the local stack is interim. The Dockerfile + compose entry stays in this repo as the canonical definition.
|
||||
- **Why use them**: every tool encodes a rule that we've previously discovered through a bug (η-null crash, ui-chart blank renders, output-key drift). Skipping them re-opens those bugs.
|
||||
|
||||
## Sources of truth (the canonical files)
|
||||
- **Front-door map**: [`CONTRACTS.md`](./CONTRACTS.md) — read first; lists every standard and where it lives
|
||||
- **Platform API shapes** (BaseDomain, BaseNodeAdapter, commands registry, UnitPolicy, …): `.claude/refactor/CONTRACTS.md`
|
||||
|
||||
12
CONTRACTS.md
12
CONTRACTS.md
@@ -26,9 +26,10 @@ branch across 12 submodules; promotion to `main` is gated by Docker E2E.
|
||||
| **Wiki page templates** | [`.claude/refactor/WIKI_TEMPLATE.md`](./.claude/refactor/WIKI_TEMPLATE.md) + [`WIKI_HOME_TEMPLATE.md`](./.claude/refactor/WIKI_HOME_TEMPLATE.md) | When editing a per-node wiki page |
|
||||
| **Live decisions log** | [`.claude/refactor/OPEN_QUESTIONS.md`](./.claude/refactor/OPEN_QUESTIONS.md) | When you spot an ambiguity — append, don't invent |
|
||||
| **Top-level wiki** | [`wiki/`](./wiki/) (Home, Architecture, Getting-Started, Telemetry, Topology-Patterns, Topic-Conventions, Glossary, Functional-Overview) | When you need a process-level or architecture-level view |
|
||||
| **Agent skills / routing** | [`.agents/AGENTS.md`](./.agents/AGENTS.md) + [`.agents/skills/`](./.agents/skills/) | When deciding which specialist to invoke |
|
||||
| **Agent skills** | [`.claude/skills/`](./.claude/skills/) (15 domain skills, auto-discovered, invokable via `Skill` tool) | When you need domain reasoning |
|
||||
| **Spawnable subagents** | [`.claude/agents/`](./.claude/agents/) (10 Claude Code subagents) | When you want to delegate independent work |
|
||||
| **Routing table** | [`.agents/AGENTS.md`](./.agents/AGENTS.md) | When deciding which specialist to invoke |
|
||||
| **Improvements backlog** | [`.agents/improvements/IMPROVEMENTS_BACKLOG.md`](./.agents/improvements/IMPROVEMENTS_BACKLOG.md) | When deferring functional work |
|
||||
| **Repo-memory MCP rule** | [`.claude/rules/repo-mem.md`](./.claude/rules/repo-mem.md) | Before any concept-search — use `repo_search` instead of `grep` |
|
||||
|
||||
### Per-node (`nodes/<nodeName>/`)
|
||||
|
||||
@@ -63,11 +64,11 @@ branch across 12 submodules; promotion to `main` is gated by Docker E2E.
|
||||
|
||||
## 2. Discovery chain — how a fresh agent finds the rules
|
||||
|
||||
1. `CLAUDE.md` auto-loads → points at this file and `.claude/rules/repo-mem.md`.
|
||||
1. `CLAUDE.md` auto-loads → points at this file.
|
||||
2. `.claude/rules/*.md` auto-load by `paths:` frontmatter when editing matching files.
|
||||
3. `nodes/<n>/CLAUDE.md` auto-loads when working under that submodule.
|
||||
4. This file (`CONTRACTS.md`) is the human-facing map of everything in step 1-3.
|
||||
5. **Concept lookup**: use the `repo-mem` MCP server (`repo_search`, `repo_similar_fixes`) — it's faster and more targeted than `grep`. See `.claude/rules/repo-mem.md`.
|
||||
5. **Concept lookup**: use `grep` / `find` or the `Explore` subagent — anchor on the canonical sources listed in §1 (commands registry, CONTRACT.md, base classes in `generalFunctions/`).
|
||||
|
||||
---
|
||||
|
||||
@@ -111,6 +112,7 @@ See [`.claude/rules/output-coverage.md`](./.claude/rules/output-coverage.md).
|
||||
4. If the change touched a platform shape (a base class or shared utility), update [`.claude/refactor/CONTRACTS.md`](./.claude/refactor/CONTRACTS.md) and `nodes/generalFunctions/CONTRACT.md`.
|
||||
5. If the change introduced a deprecation, add an alias to `commands/index.js` and a one-line note to the per-node `CONTRACT.md`.
|
||||
6. Append unresolved questions to [`.claude/refactor/OPEN_QUESTIONS.md`](./.claude/refactor/OPEN_QUESTIONS.md). Don't invent answers.
|
||||
7. If topic usage in an example flow changed, regenerate or review the per-node `wiki/Reference-Examples.md` and the `examples/*.flow.json` set.
|
||||
|
||||
---
|
||||
|
||||
@@ -137,5 +139,5 @@ submodule first, then the superproject bumps the pin.
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18. If something in this map is wrong, fix this file
|
||||
*Last reviewed: 2026-05-19. If something in this map is wrong, fix this file
|
||||
in the same PR as the change that made it wrong.*
|
||||
|
||||
Submodule nodes/generalFunctions updated: ab481357d2...48fa54363d
Reference in New Issue
Block a user