AGENTS.md

This file provides high-level guidance for all agents working in the SCADA for Small Water Systems project.

Project Mission

Build a modern, affordable, low-egress SCADA monitoring and alerting platform for small municipal and private water systems. The system must combine edge computing (Raspberry Pi), hybrid AI models, and a clean multi-tenant interface to deliver reliable monitoring with minimal ongoing data costs.

Key Principles

Follow the execution guidelines defined in core-planning/docs/EXECUTION.md
Use the SCRUM stand-up format when reporting progress
Coordinate primarily through the project Kanban board
Maintain clear, actionable comments on tasks
Prioritize low data egress and practical reliability over theoretical perfection

Architecture & Constraints

Target hardware: Raspberry Pi 5 + cellular HAT (eSIM preferred)
Strong emphasis on low-egress design — heavy local summarization, rich context only on alerts
Hybrid AI architecture (small edge models + larger reasoning models)
Multi-tenancy support for both individual system owners and professional operators managing multiple systems
Tamper-evident sealed enclosures for field devices
Must support both non-technical board members and licensed water system operators

Coding Standards

All project documentation must live under the /docs folder
Use clear, professional technical writing
Architecture Decision Records (ADRs) go in docs/decisions/

Kanban Workflow

All work is tracked in the project Kanban board
Use clear task prefixes: [Feature], [Bug], [Research], [Architecture], [Spec], etc.
Follow the escalation rules defined in core-planning/docs/KANBAN-WORKFLOW.md
Only escalate to the human when the defined escalation criteria are met

Important Context

All documentation lives under docs/ in this repo
Refer to core-planning/docs/ for team-wide standards
When in doubt, ask for clarification in the task comments

Agent Roles in This Project

See the agents/ folder for role-specific instructions.

This file should be updated as the project evolves.

2.1 KiB Raw Permalink Blame History