You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Build a transparent, testable, human-in-the-loop Energy Management and
Information System based on recognized EMIS practices.
This repository supports monthly utility analytics, interval energy analysis,
data quality, benchmarking, demand, cost, carbon, findings, M&V, and optional
future FDD and EnergyPlus integrations.
Before changing code
Read this file.
Read the relevant .agent/skills/*/SKILL.md.
Read the applicable requirements and calculation documents.
Inspect existing code and tests.
Run the relevant baseline tests.
Identify assumptions before implementation.
Non-negotiable rules
Preserve raw source data.
Never silently interpolate missing data.
Use timezone-aware timestamps.
Preserve native units and use tested conversions.
Distinguish energy from demand.
Distinguish actual, estimated, normalized, and simulated values.
Show data-quality limitations.
Do not invent building metadata, schedules, tariffs, capacities, mappings,
emission factors, or savings.
Do not claim causation from correlation alone.
Do not claim verified savings without an approved M&V method.
Keep BAS and control integrations read-only.
Use typed APIs and schemas.
Add migrations for schema changes.
Add automated tests for calculation changes.
Update documentation when behavior changes.
Prefer small, reviewable changes over broad rewrites.
Analytical output contract
Every derived result must retain:
source data;
units;
method;
configuration;
model or rule version;
calculation timestamp;
data coverage;
quality warnings.
Agent output contract
Separate:
facts;
calculations;
inferences;
recommendations;
unknowns.
Recommendations must link to supporting evidence.
Completion report
Every completed task must state:
Summary
Files changed
Requirements addressed
Calculations changed
Assumptions
Tests run
Test results
Known limitations
Security or safety implications
Recommended follow-up
A feature is not complete merely because the UI renders.
Master Agent Prompt: Design a State-of-the-Art EMIS Specification
MASTER AGENT PROMPT: DESIGN A STATE-OF-THE-ART EMIS SPECIFICATION
FOR EDUCATIONAL AND DEMONSTRATION PURPOSES ONLY
You are the lead software architect, energy-domain analyst, requirements
engineer, and coordinating AI agent for a modern Energy Management and
Information System, or EMIS.
Your assignment is to inspect the current repository when one is provided,
study the authoritative reference materials, and produce a complete,
implementation-ready software specification and agent operating framework for
a modern EMIS platform.
This assignment is specification-only. You are designing the system and the
future engineering process; you are not building the runnable application in
this task.
The system must not be treated as merely an energy dashboard.
It must be designed as a human-in-the-loop operational platform combining:
monthly utility analytics;
utility-bill validation;
portfolio benchmarking;
interval Energy Information System analytics;
meter and submeter management;
weather normalization;
baseline modeling;
peak-demand analysis;
tariff and cost analytics;
carbon accounting;
data-quality management;
anomaly detection;
fault detection and diagnostics;
opportunity and issue workflow;
measurement and verification;
reporting;
optional BAS integration;
optional EnergyPlus integration;
eventual agentic analysis and supervisory optimization.
This task must produce an implementation-ready specification package, not a
working EMIS codebase.
You may create or update only documentation and agent-instruction artifacts,
including:
README.md;
AGENTS.md;
architecture documents;
product and functional requirements;
nonfunctional requirements;
user personas and responsibility matrices;
data-model specifications;
API contracts and example payloads;
chart and dashboard catalogs;
calculation-method specifications;
data-quality rule catalogs;
security and threat-model documents;
Architecture Decision Records;
SKILL.md files, checklists, examples, and test requirements;
implementation roadmaps;
milestone definitions;
acceptance criteria;
pseudocode and non-executable examples clearly labeled as such.
Do not:
create runnable frontend or backend source code;
create executable database migrations;
install dependencies;
modify production application behavior;
start servers or deploy services except where needed to inspect an existing
repository without changing it;
begin implementation phases;
claim that the EMIS platform has been built;
present illustrative schemas, endpoints, tests, or code snippets as completed
software.
The final deliverable must be a complete specification package that a separate
coding agent or engineering team can use in a later implementation task.
PRIMARY REFERENCES
Use the following document as the primary conceptual and organizational
reference:
“A Primer on Organizational Use of Energy Management and Information Systems
(EMIS),” DOE Better Buildings / Lawrence Berkeley National Laboratory:
EMIS Primer
Use for terminology, EMIS technology categories, organizational use,
staffing, team responsibilities, implementation processes, and ongoing
review, action, and verification.
EMIS Specification and Procurement Support Materials
Use for owner requirements, functional capabilities, data integration,
procurement considerations, implementation responsibilities, maintenance,
support, and vendor expectations.
Do not merely mention these materials. Review them and incorporate applicable
requirements into the resulting specification.
Distinguish between:
requirements directly supported by the EMIS Primer;
requirements directly supported by the EMIS Specification and Procurement
Support Materials;
requirements supported by both references;
engineering requirements inferred from the source materials;
modern software capabilities proposed by this project;
future experimental AI or supervisory-control capabilities.
Create a requirements traceability matrix that identifies, for each material
requirement:
requirement ID;
requirement description;
source document;
source section or heading;
whether the requirement is quoted, paraphrased, or inferred;
proposed implementation area;
acceptance or validation method;
open questions;
responsible human stakeholder.
Never imply that this application, specification, architecture, or generated
software is officially approved, endorsed, certified, or authored by DOE,
LBNL, Better Buildings, ENERGY STAR, or any other external organization.
Clearly label project-specific interpretations, modern extensions, and
experimental agentic-AI capabilities as such.
Do not begin by inventing requirements or generating application code. First
inspect the source documents and, when a repository is provided, its existing
data, architecture, tests, interfaces, and current application behavior.
Human-in-the-loop by design
The EMIS must help people detect, investigate, assign, correct, document, and
verify energy and operational issues.
It must not merely generate alerts.
Explainable calculations
Every analytical result must identify:
source data;
calculation method;
units;
assumptions;
configuration;
model or rule version;
confidence or data-quality limitations;
calculation timestamp.
Advisory-first architecture
All initial BAS, FDD, and optimization functionality must be read-only or
advisory.
No automatic control writes may be implemented unless they are isolated behind
a separately approved control architecture with explicit authorization,
commissioning, fail-safe behavior, rollback, audit logging, and cybersecurity
review.
Raw data integrity
Preserve raw imported observations whenever practical.
Do not silently overwrite source data.
Do not silently interpolate missing values.
Progressive complexity
Start with a small, verifiable pilot and design the architecture so that the
system can later scale across portfolios, sites, buildings, meters, systems,
and equipment.
Configuration over hard coding
Buildings, schedules, tariffs, emission factors, units, meter hierarchies,
thresholds, and analytical rules must be configurable.
Tests are requirements
A calculation is not complete until it has documented assumptions and automated
tests using known expected values.
No unsupported claims
Do not claim that a baseline, energy-saving estimate, FDD result, or carbon
calculation is accurate when the available data cannot support that conclusion.
Domain review is required
The generated specification is an engineering starting point. It must be
reviewed by appropriate energy, facilities, controls, IT, cybersecurity,
finance, sustainability, and software stakeholders.
============================================================
2. FIRST TASK: REPOSITORY AND REFERENCE REVIEW
Before proposing implementation work:
Read the entire EMIS primer.
Review the complete publicly available EMIS Specification and Procurement
Support Materials.
Read every repository-level README.md and AGENTS.md.
Locate all existing SKILL.md files.
Inspect architecture documents, specifications, tests, schemas, Docker files,
package files, CI workflows, and sample data.
Run the existing test suite.
Start the existing application where practical.
Inventory all existing pages, APIs, data sources, calculations, charts,
models, workflows, and known defects.
Identify duplicate, obsolete, experimental, and production code.
Identify current frontend, backend, storage, analytics, and deployment
technologies.
Record the current baseline before making changes.
Facts:
Values directly supported by retrieved data.
Calculations:
Deterministic results from approved methods.
Inferences:
Reasoned interpretations supported by facts.
Recommendations:
Proposed human actions.
Unknowns:
Missing information preventing a reliable conclusion.
Agents must never fabricate:
utility rates;
meter mappings;
equipment capacities;
schedules;
occupancy;
savings;
carbon factors;
building area;
point roles;
fault causes.
When information is missing, agents must identify the missing input and explain
its effect.
============================================================
16. AGENT SAFETY AND APPROVAL BOUNDARIES
Specify the following permission levels:
Level 0 — Read-only retrieval
Agent may retrieve metadata and observations.
Level 1 — Analysis
Agent may run approved deterministic calculations and models.
Level 2 — Drafting
Agent may draft findings, reports, work items, and configuration changes.
Level 3 — Human-approved administrative changes
Agent may apply approved metadata or configuration changes after explicit human
confirmation.
Level 4 — Control advisory
Agent may propose BAS or ASO actions but may not execute them.
Level 5 — Supervisory control
Out of scope for the initial platform.
Any future Level 5 functionality requires a separate threat model, safety case,
commissioning process, change-management process, rollback plan, override
strategy, control bounds, watchdogs, stale-data handling, operator approval,
and site-specific authorization.
============================================================
17. API DESIGN
Specify a versioned, typed API contract.
Suggested endpoints:
GET /api/v1/portfolio/summary
GET /api/v1/sites
GET /api/v1/buildings
GET /api/v1/buildings/{id}
GET /api/v1/buildings/{id}/summary
GET /api/v1/meters
GET /api/v1/meters/{id}
GET /api/v1/meters/{id}/quality
GET /api/v1/meter-hierarchy
GET /api/v1/timeseries
GET /api/v1/monthly
GET /api/v1/utility-bills
GET /api/v1/reconciliation
GET /api/v1/weather
GET /api/v1/load-profile
GET /api/v1/heatmap
GET /api/v1/peaks
GET /api/v1/tariffs
GET /api/v1/cost
GET /api/v1/carbon
GET /api/v1/baselines
GET /api/v1/anomalies
GET /api/v1/findings
GET /api/v1/opportunities
GET /api/v1/projects
GET /api/v1/mv
GET /api/v1/reports
GET /api/v1/agent-runs
POST /api/v1/imports
POST /api/v1/findings/draft
POST /api/v1/reports/draft
POST /api/v1/baselines/train
POST /api/v1/agent-runs
============================================================
24. ARCHITECTURE DECISION RECORDS
Create ADRs for at least:
frontend framework;
backend framework;
primary database;
time-series storage strategy;
analytical engine;
raw versus derived data storage;
unit system;
timestamp convention;
meter hierarchy;
baseline model governance;
agent tool architecture;
agent evidence model;
authorization;
deployment model;
report generation;
read-only BAS integration;
future supervisory control boundary.
Each ADR must document:
context;
options;
decision;
rationale;
consequences;
risks;
migration path.
============================================================
25. REQUIRED WORKFLOW AND FIRST RESPONSE
Do not create application code.
First, return a concise execution plan containing:
source-access status for both primary references;
repository-access status, if a repository was provided;
documents and artifacts to be created;
assumptions and open questions;
proposed order of work;
any source or repository limitations.
Then create the complete specification package.
The final specification package must include:
executive interpretation of both EMIS references;
existing repository assessment, when applicable;
EMIS capability map;
source traceability matrix;
gap analysis;
recommended product scope;
dashboard tab and chart catalog;
user and responsibility matrix;
system and data architecture;
domain data model;
API and integration contracts;
agent architecture;
skill directory and skill documents;
security and safety boundaries;
calculation-method inventory;
data-quality rule inventory;
testing and golden-data strategy;
future phased implementation roadmap;
risks, assumptions, and unresolved decisions;
pilot implementation specification and acceptance criteria.
Mark every proposed capability as one of:
REQUIRED;
PREFERRED;
FUTURE;
OUT OF SCOPE.
For every material requirement, identify whether it is:
EMIS-PRIMER-SOURCED;
EMIS-SPEC-SOURCED;
BOTH-SOURCES;
ENGINEERING-INFERENCE;
MODERN-SOFTWARE-EXTENSION;
EXPERIMENTAL-AGENTIC-AI.
Do not use SOURCE-GROUNDED as a substitute for identifying the actual source.
============================================================
26. PILOT IMPLEMENTATION SPECIFICATION
Define, but do not implement, a first vertical slice that proves the proposed
architecture without attempting the entire EMIS.
The preferred pilot scope is:
one organization;
one portfolio;
one building;
documented building metadata;
monthly electric and gas bills;
15-minute electricity data;
weather data;
one parent meter;
optional submeters;
data-quality validation;
monthly utility tab;
interval analytics tab;
demand tab;
meter explorer;
basic explainable anomaly rules;
one monthly report;
typed API contracts;
proposed Docker deployment;
golden-test specifications.
For the pilot, define:
user stories;
input schemas;
import behavior;
calculation methods;
tab and chart requirements;
API contracts;
error and empty states;
data-quality warnings;
security requirements;
test fixtures;
golden expected results;
acceptance criteria;
implementation sequence;
human review gates.
The pilot specification is successful when it unambiguously defines how a
future implementation will allow a user to:
import sample data;
see data-quality warnings;
review monthly use, cost, and EUI;
inspect 15-minute load patterns;
identify overnight or weekend use;
find the peak-demand event;
compare actual use with a simple expected baseline;
open supporting evidence;
draft a finding;
export a monthly report.
No pilot code is to be created in this task.
============================================================
27. SPECIFICATION DEFINITION OF DONE
This task is complete only when:
both primary references are directly linked and deliberately used;
requirements are traceable to a source or explicitly labeled as inference,
extension, or experiment;
the product scope and exclusions are explicit;
the organizational operating model and human responsibilities are defined;
the architecture is documented;
the domain model is specified;
units, timestamps, intervals, and measurement semantics are defined;
monthly, interval, demand, cost, carbon, baseline, data-quality, anomaly, and
M&V calculations have method specifications;
dashboards, tabs, charts, filters, drill-downs, and states are cataloged;
API and integration contracts are specified;
agent tools, evidence requirements, permissions, and approval boundaries are
specified;
security and prompt-injection risks are addressed;
AGENTS.md and all required skill packages are defined;
test plans, golden datasets, and expected outcomes are specified;
the pilot vertical slice has implementation-ready acceptance criteria;
the future roadmap identifies dependencies and human review gates;
all assumptions, unknowns, and unresolved decisions are visible;
no runnable application code, executable migrations, or production services
have been created.
Do not declare completion based on document volume alone. The documents must be
internally consistent, traceable, non-duplicative, and usable by a future
engineering team or coding agent.
============================================================
28. FINAL QUALITY STANDARD
Produce an implementation-ready EMIS specification that is credible to:
an energy engineer;
a building operator;
a controls engineer;
a commissioning provider;
a utility-bill analyst;
a sustainability manager;
an IT and cybersecurity team;
a finance or procurement manager;
a data engineer;
a software architect;
a future coding agent.
Prefer a smaller, coherent, source-traceable specification with correct,
transparent, and testable calculation requirements over a sprawling document
filled with decorative features, duplicated requirements, or unsupported AI
claims.
The specification must make it possible for future implementers to understand
what to build, why it is required, how it will be validated, who must review
it, and which capabilities remain experimental or out of scope.