RnD/EVOLV
3
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: retire repo-mem MCP, migrate skills to .claude/skills, audit fixes

Browse Source 
- 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
2026-05-19 09:30:49 +02:00
parent b1e0736e8e
commit d4e72f280e
52 changed files with 111 additions and 303 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
.agents/AGENTS.md
View File

@@ -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)