swarm-house/AGENTS.md

AGENTS.md

Rules for anyone (human or tooling) contributing to this repository.

Hard rules

1. English only. All documentation, code, comments, commit messages, and file names are written in English.
2. No identifying references. Never mention names of people, companies, organizations, or locations anywhere in this repository — not in docs, code, comments, or git history. This is a generic, self-contained design proposal for an on-prem data platform for autonomous drone swarms.
3. Clean git history. Commit messages must never reference AI assistants, code generation tools, or editors. No Co-authored-by trailers pointing to tools, no "Generated with ..." lines. Conventional commit format (feat:, fix:, docs:, refactor:).
4. Push target. The only remote is origin → git.produktor.io. Never mirror this repository anywhere else.

Project layout

docs/           Design documentation (Markdown + Mermaid)
simulator/      Virtual drone fleet — Python data generator (Parquet/DuckDB pipeline)
prototype/      2D swarm visualization — React + TypeScript (Vite)
infra/          Ansible host prep, Terraform workloads, Flux GitOps overlays
var/t1/         Shared T1 live lake (gitignored runtime data)
var/t3/         Shared T3 warehouse (gitignored runtime data)

See CONTRIBUTING.md for the development workflow and TDD requirements.

Conventions

• Markdown: ATX headings, fenced code blocks with language tags, pipe tables.
• Python: PEP 8, type hints, pure functions where possible, no unnecessary classes.
• TypeScript: strict mode, functional components and hooks, no extra UI libraries.
• YAML: 2-space indent.
• Diagrams: Mermaid inside Markdown.

Decision records

Significant architectural decisions are recorded chronologically as ADRs in docs/adr/ — one immutable file per decision, in the Status / Context / Options / Decision / Consequences format. Start from docs/adr/README.md.

• ADR = a point-in-time decision for this repo → docs/adr/.
• ASR = a standing, ecosystem-wide standard (Go-first, secrets, layout) → lives in the inventar repo, not here.

When a change alters a boundary, contract, or trade-off, add an ADR (copy docs/adr/TEMPLATE.md, take the next number, update the index) and cross-link it from the affected design doc. A later reversal gets a new ADR that supersedes the old one — never edit an Accepted record.

Runtime & operations (sim environment)

The k3d ground miniature is swarm-sim. Services are exposed as NodePorts:

Service	URL
Explorer (T1 live lake)	http://localhost:30088
Warehouse explorer (T3)	http://localhost:30089
Grafana (dashboards swarm-fleet, swarm-platform)	http://localhost:30300
Prometheus	http://localhost:30990
MinIO console	http://localhost:30901
Prototype dev server (npm run dev)	http://localhost:5173

Rebuild the simulator image and roll it out:

cd simulator && docker build -t swarm-house/simulator:dev .
k3d image import swarm-house/simulator:dev -c swarm-sim
kubectl rollout restart -n swarm statefulset/drone deployment/explorer deployment/exporter
cd infra/terraform/sim-env && terraform apply

CPU budget knobs (see ADR-0009): METRIC_FLIGHT_WINDOW (scan only recent flights), SCAN_INTERVAL_S, VIEW_REFRESH_S, TREE_CACHE_S, KEEP_ALIVE=1 (drones idle after seal instead of restarting), IMU_HZ. Never scan the full lake on a hot path — it grows with pod churn. Long-horizon analysis is a T3 warehouse query, not an exporter job.

Runtime data lives under var/t1 / var/t3, owned by uid 10001 (ADR-0007, ADR-0008); both are gitignored. Terraform state is local and never committed.