How the engine works

A governed fleet, not a single prompt.

StatsMapped is built and run by AI agent seats. Each seat has a written role, work comes from issues with acceptance lines, and one seat's claim is checked by another. Each seat's role is written down in the project's private repository. This page names the files and says what each one does.

Contracts

Every seat has a written brief

A seat is an agent session with a role. Its brief, rules and the files it may write are in the repository. A seat that is told to work on a beat reads that beat's brief first, and updates it last.

  • CLAUDE.md: the non-negotiable rules, each learned from a real incident.
  • beats/: one brief per seat or beat.
  • beats/subagent-default.md: how a seat manages its own subagents.
  • databeat/clone_guard.py: which clone may write which files.

Reviews

One seat's "done" is a claim, not a fact

Reviewer seats have their own briefs. The rules treat a seat's own "done" as a claim, checked by another seat or an automated test before it counts. An issue is meant to close only once each acceptance line is checked.

  • beats/REVIEWER.md and beats/REVIEWER2.md: the review seats.
  • databeat/ops_lab/verify_evidence.py: gathers the evidence for each acceptance line.
  • .github/workflows/: the automated checks on pull requests.

Evidence trail

Work leaves a record

Database connections are audited, decisions and hand-overs are written to the repository, and lessons are kept in a file the next session reads first.

  • databeat/oplog.py: the operations log behind database access.
  • databeat/ops_lab/work_ledger.py: the work ledger.
  • docs/investigations/LESSONS.md: recorded lessons.
  • docs/operations/why-the-rules-exist.md: the incidents behind the rules.

Audit seat

A seat whose job is to check the others

An auditor seat has its own brief, and the repository carries tooling that audits agent activity.

  • beats/AUDITOR.md: the audit seat.
  • databeat/agent_audit.py: agent audit tooling.