eSlider
bed6f93626
Document caveman-full as the collaboration voice in AGENTS and CONTRIBUTING, and add Gitea issue/PR templates that pre-fill terse structure.
4.6 KiB
AGENTS.md
Rules for anyone (human or tooling) contributing to this repository.
Hard rules
- English only. All documentation, code, comments, commit messages, and file names are written in English.
- 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.
- Clean git history. Commit messages must never reference AI assistants, code generation tools, or editors. No
Co-authored-bytrailers pointing to tools, no "Generated with ..." lines. Conventional commit format (feat:,fix:,docs:,refactor:). - 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
Caveman style (default for collaboration)
Issues, pull requests, and code reviews use caveman-full by default:
- Short sentences or fragments; drop articles and filler when clear
- Lead with fact, verdict, or ask — not preamble
- Bullets over paragraphs; one idea per line
- Keep technical terms, acronyms, paths, and code exact
- English only; no identifying references (same as all repo prose)
README tiers: root README.md = caveman-lite (full sentences, less filler);
component READMEs = caveman-full. Design docs in docs/ stay readable prose unless
editing for consistency.
Templates: .github/ISSUE_TEMPLATE/,
.github/pull_request_template.md.
- 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
inventarrepo, 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.