Prometheus is a local-first personal assistant that shows the four pillars behind every serious agent: Harness, Loop, Memory, and Eval/LLM-Ops. It began as a repo you could read in an afternoon and is growing into a full open-source assistant. Every change must keep it clear, honest code a newcomer can follow: the project will get bigger, and it must never get muddier.
This file is for everyone who changes the repo, human or coding agent. A test caps it at 100 lines, so the detail lives in the files it points to.
| Before you | Read |
|---|---|
| run Prometheus for the first time | docs/getting-started.md |
| start anything non-trivial | docs/status.md: what works and what is known-broken |
| decide how much process a change needs | conventions §2 |
| add capability (tool, gateway, provider, store) | conventions §3, the footprint ladder |
| add a skill | skills/TEMPLATE.md: no Python needed |
| connect Prometheus Memory, or carry skills to another agent | docs/integrations.md |
| add a tool | thenew-tool skill in .claude/skills/new-tool/ |
| run prometheus for other people on a server | hosted/README.md |
| touch the loop, memory, graph engine or a tool contract | docs/architecture.md, then conventions §2: it may need a proposal |
| change how the dashboard looks | docs/context/design-system.md |
| change dashboard JavaScript or CSS | prometheus/ops/static/README.md |
| write a doc, UI copy, a commit message or a SKILL.md | docs/context/writing-rules.md |
add a lesson toexamples/ or a topic to lab/ |
lab/README.md, then conventions §6 |
| hit something surprising | docs/context/gotchas.md, and add it if it is missing |
- Never wipe runtime data without asking. Anything that clears
.prometheus/(memory, calendar, chat log, traces, theusage.jsonlspend ledger),scripts/demo_seed.pyincluded, needs the user's explicit yes right before each run. A yes never carries over to the next run. - Never touch secrets in
prometheus/, the code that runs on a person's own machine: no hidden network calls, nothing reads or sends.envor keys, and nothing runs at install time.hosted/is the platform's own deployment and reads the platform's own configuration by design; it ships to nobody. - No new default dependency. The core is stdlib plus the Anthropic and
OpenAI clients. Anything else goes behind an extra (
[voice],[telegram]). - Every behaviour change gets a deterministic eval in
evals/deterministic/(0/1, offline). A bug fix adds the case that would have caught it. - Nothing under
prometheus/orevals/imports fromexamples/orlab/, andlab/never ships to PyPI. - No emojis in the dashboard, CLI output or docs prose.
- Two things here are not MIT.
hosted/is Elastic License 2.0 (hosted/LICENSE): runnable by anyone, including commercially, but not offerable to third parties as a service. The brand — the design system, the Prometheus mark and the names — is covered separately from the code, so never copy one intoexamples/, and do not move code betweenhosted/andprometheus/without saying which license it lands under. - Don't edit the copied design files in
prometheus/ops/static/design/. They are synced from the private master; ask for a new token in an issue. - Fix the doc your change makes false, in the same PR.
The validate workflow runs on every PR, and hosted-docker runs beside it.
Each of these fails one of them:
| Blocked | Checked by |
|---|---|
auv.lock change without a pyproject.toml change |
a step in.github/workflows/validate-skills.yml |
a lint error inprometheus/, evals/, scripts/ or hosted/ |
ruff check |
an import betweenprometheus/ and hosted/, in either direction |
evals/deterministic/test_hosted_boundary.py |
| a dashboard route with no hosted policy entry | evals/deterministic/hosted/test_route_contract.py |
| a hosted change that breaks a tenant container or a tenant's disk limit (advisory: not yet a required check) | .github/workflows/hosted-docker.yml |
| a skill that fails validation | scripts/validate_skills.py |
| a skill that loads on everyday or another skill's messages | evals/deterministic/test_skill_triggers.py |
.env.example out of step with the integrations registry |
scripts/generate_env_example.py |
| an edited design copy, a colour literal, an old token name | evals/deterministic/test_design_system.py |
| a second version number | evals/deterministic/test_version.py |
this file over 100 lines, a broken rulebook link, an unindexed doc, an import fromexamples/ or lab/, a lab topic without its playbook, a retired Prometheus Memory address, an emoji in the rulebook or README, a module-level name defined twice |
evals/deterministic/test_rulebook.py |
| any other failing deterministic eval | pytest evals/deterministic |
Everything else in the rulebook is checked in review. The judge evals in
evals/judge/ need an API key, so make gate runs them locally and CI does not.
hosted-docker needs a Docker daemon and an XFS filesystem, so it is a job of
its own, and its row above says "advisory" because it is: a red run there does
not block a merge until hosted-docker is added to main's required checks.
It now checks the two bridges networks.sh creates, but nothing yet about the
rules that make them safe: firewall.sh is still spec 001's group C.
make run · make dashboard (localhost:7777) · make voice · make trace (Phoenix, 6006)
make eval · make gate (deterministic + judge) · make lint · tests live in evals/, not tests/