From df8518d629a967796d0646761cd0b6f82f220378 Mon Sep 17 00:00:00 2001 From: Conrad Schulz Date: Wed, 3 Jun 2026 10:04:43 +0000 Subject: [PATCH] chore: copilot-instructions auf aktuelle version aktualisiert MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Agent Session Protocol (MANDATORY) ergänzt - Verbotene Aktionen dokumentiert - DoD und Workflow-Sektionen aus copilot-setup template übernommen --- .github/copilot-instructions.md | 190 +++++++++++++++++++++++--------- 1 file changed, 137 insertions(+), 53 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ee53e29..763645b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,75 +1,159 @@ # GitHub Copilot – Project Instructions +## ⚡ Agent Session Protocol (MANDATORY) + +> Diese Sektion hat höchste Priorität und darf nicht ignoriert werden. + +**Session START** – Bevor du irgendetwas tust: +1. Lies `history/summary/PROJECT_CONTEXT.md` (falls vorhanden) +2. Verstehe den aktuellen Projektzustand bevor du anfängst + +**Session END** – Der Agent führt dies **automatisch** am Ende jeder Aufgabe aus, bevor er `git commit` ausführt: +1. Lies die bestehende `history/prompts/YYYY-MM-DD_*_session.md` (falls vorhanden) und ergänze nur den neuen Teil + **Dateiformat zwingend:** Suffix `_session.md`, Dateiname beginnt mit heutigem Datum (`YYYY-MM-DD`) +2. **Für jeden Benutzer-Prompt seit dem letzten Commit** einen Block ergänzen: + ``` + ### Prompt N + «wörtlicher Benutzertext – exakt, kein Paraphrasieren» + + ### Antwort N + «Was getan wurde + alle ausgeführten Kommandos im Code-Block + relevante Terminal-Outputs» + ``` + ⚠ Kein „Nachtrag"-Block statt echter Prompt-Einträge. Die Benutzer-Nachricht **wörtlich** zitieren. + ⚠ Keine reinen Stichpunkt-Zusammenfassungen. Ausgeführte Kommandos und Outputs gehören **wörtlich** in die Antwort. + ⚠ Keine Platzhalter wie `PENDING` committen. Ist der Commit-Hash noch unbekannt: Hash weglassen oder Datei direkt nach dem Commit mit dem echten Hash aktualisieren und sofort (`git add history/ && git commit`) nachziehen. +3. Aktualisiere `history/summary/PROJECT_CONTEXT.md` mit dem neuen Projektstand +4. **Stage beide Dateien VOR `git commit`:** `git add history/` + Der pre-commit Hook (Check 6) blockiert wenn: + - keine `*_session.md` gestaged ist + - der Dateiname nicht mit dem heutigen Datum beginnt + - die Datei keinen einzigen `### Prompt`-Eintrag enthält + +> Kein Bypass. Kein Vergessen. Kein "mache ich beim nächsten Mal". +> Die History ist das Gedächtnis des Projekts. +> **Der Agent wartet nicht auf expliziten `/history`-Aufruf – er führt es automatisch vor jedem Commit aus.** + +## ⛔ Verbotene Aktionen (NIEMALS ausführen) + +- **`git commit --no-verify`** – Der pre-commit Quality Gate darf NIEMALS umgangen werden. + Wenn der Hook fehlschlägt: Problem beheben (Tests schreiben, Doku aktualisieren, Context aktualisieren). + Einzige Ausnahme: Der User fordert es explizit und begründet es. +- **`git push --force`** – Nie force-pushen ohne explizite Anweisung des Users. +- **Secrets in Code** – Keine Passwörter, API-Keys, Tokens in Dateien. + +--- + ## Project -Selbst gehosteter Tile-Server (rd13) – stellt Karten-Tiles (OSM Vektor + Satelliten-Raster) -für interne Dienste bereit: MediaWiki (Kartographer), Nextcloud Maps, Home Assistant und weitere Web-Apps. + ## Stack -- Language: Shell (Bash/Fish), YAML, JSON -- Infrastructure: Docker Compose, Martin (Rust), Nginx Proxy Manager (System-Proxy) -- Data: MBTiles / PMTiles (OpenMapTiles-Schema), Planetiler (Java) -- Map styles: MapLibre GL JSON (client-seitiges Rendering) -- Reverse Proxy: Nginx Proxy Manager (extern, SSL, Routing) – kein eigener nginx-Container + +- Language: +- Framework: +- Database: +- Infrastructure: ## Architecture -- Pattern: Single-purpose service (tile serving only) -- `martin` Container: Rust-basierter Tile-Server, serviert Vektor- und Raster-Tiles aus MBTiles/PMTiles -- Kein nginx-Sidecar – CORS via Martin built-in, Proxy/SSL via NPM -- Kartendaten liegen in `data/` (nicht im Git, da mehrere GB) -- Styles in `data/styles/`, Fonts in `data/fonts/`, Sprites in `data/sprites/` + +- Pattern (MVC / Hexagonal / Event-driven / ...): - Key constraints: - - MBTiles/PMTiles nie ins Git committen (.gitignore) - - Secrets immer via `.env` (`.env` selbst auch ignoriert) - - CORS via Martin-Config (alle Origins erlaubt für LAN) +- ADR location: `docs/adr/` + +## Project Structure Conventions + +### Persistent Data (`/data/`) +- **Alle persistenten Service-Daten** gehören in `/data//` (Repo-Root) +- **Nie** Daten-Dateien committen – `/data/` ist vollständig gitignored +- Einen Unterordner pro Service (z.B. `data/postgres/`, `data/redis/`, `data/uploads/`) +- Erforderliche Unterordner in `docs/ADMIN.md` dokumentieren + +### Requirements (`/docs/requirements/`) +- **Alle verstandenen Anforderungen** → `docs/requirements/REQUIREMENTS.md` (**committed, immer aktuell halten!**) +- **Beim Start einer neuen Aufgabe:** `docs/requirements/REQUIREMENTS.md` zuerst lesen (falls vorhanden) +- **Nach Anforderungs-Klärung:** Requirements-Datei aktualisieren und stagen +- Copilot Chat: `/requirements` → Requirements-Workshop starten oder bestehende Requirements aktualisieren +- Copilot Chat: `/check-consistency` → Konsistenz zwischen Code, Docs und Requirements prüfen + +### Agent History (`/history/`) +- **Vollständige Konversationen** → `history/prompts/YYYY-MM-DD_beschreibung_session.md` (**Suffix `_session.md` zwingend** – Check 6 im pre-commit Hook erkennt daran das Agent-Log) +- **Komprimierter Kontext** → `history/summary/PROJECT_CONTEXT.md` (**committed, immer aktuell halten!**) +- **Beim Start einer neuen Session:** `history/summary/PROJECT_CONTEXT.md` zuerst lesen +- **Am Ende jeder Session:** beide Dateien committen +- Copilot Chat: `/history` → History loggen + Summary aktualisieren + +### Documentation (3 Zielgruppen – alle 3 müssen existieren) +| Datei | Zielgruppe | Inhalt | +|---|---|---| +| `docs/USER.md` | Endnutzer | Features, How-To, FAQ – keine technischen Details | +| `docs/ADMIN.md` | Administratoren | Deployment, Konfiguration, Monitoring, Backup | +| `docs/MAINTAINER.md` | Entwickler | Architektur, ADRs, Konventionen, Erweiterung | + +**Regel:** Jede bedeutende Änderung muss mindestens eine dieser Dateien aktualisieren. +Der pre-commit Hook prüft dies automatisch. ## Conventions -- Branch naming: `feat/`, `fix/` -- Commit format: Conventional Commits (`feat|fix|chore|docs|refactor|ci`) + +- Branch naming: `feat/-description`, `fix/-description` +- Commit format: Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`) - File structure: - ``` - config/ Martin-Konfiguration (martin.yaml) - data/ MBTiles, Fonts, Sprites, Styles (nicht im Git) - docs/ Integrations-Anleitungen (MediaWiki, Nextcloud, Home Assistant, API) - prompts/ GitHub Copilot Prompt-Templates - scripts/ Daten-Download, Deploy-Hilfen - ``` -- Naming: snake_case für Dateien, kebab-case für Docker-Service-Namen +- Naming: ## Engineering Process ### Before starting any task -1. `docker compose config` – Syntax validieren -2. `docker compose logs martin` – laufende Fehler prüfen -3. Impact analysis – betrifft die Änderung CORS, Caching oder Endpunkt-URLs? -4. Test strategy – mit curl / Browser gegen lokalen Server testen +1. Lies `docs/requirements/REQUIREMENTS.md` (falls vorhanden) – verstehe die Anforderungen +2. Clarify requirements – user story + acceptance criteria vorhanden? +3. Impact analysis – welche bestehenden Komponenten sind betroffen? +4. Architecture check – passt die geplante Lösung zur bestehenden Architektur? +5. Test strategy – wie wird das Feature getestet? + +### Definition of Ready (DoR) +A task can only be started when: +- [ ] Acceptance criteria are clear and unambiguous +- [ ] Non-functional requirements defined (performance, security, scalability) +- [ ] Architectural approach agreed upon +- [ ] No unresolved external blockers ### Definition of Done (DoD) -- [ ] `docker compose config` fehlerfrei -- [ ] Server startet ohne Fehler in den Logs -- [ ] Tile-Endpunkt antwortet (`curl http://localhost:3000/health`) -- [ ] CORS-Header korrekt gesetzt (prüfen mit `curl -I -H "Origin: ..."`) -- [ ] Keine Secrets in docker-compose.yml oder Configs -- [ ] .gitignore schützt MBTiles und .env -- [ ] Commit message folgt Conventional Commits +A task is only done when ALL of the following are true: +- [ ] Code implements the acceptance criteria +- [ ] Requirements-Konsistenz geprüft: keine Widersprüche zwischen Code und `docs/requirements/REQUIREMENTS.md` +- [ ] `docs/requirements/REQUIREMENTS.md` aktualisiert falls Anforderungen sich geändert haben +- [ ] Unit tests written and passing +- [ ] Integration tests (where applicable) passing +- [ ] No linter / type errors +- [ ] No secrets or credentials in code +- [ ] OWASP Top 10 reviewed +- [ ] Relevant documentation updated: `docs/USER.md` and/or `docs/ADMIN.md` and/or `docs/MAINTAINER.md` +- [ ] Alle 3 Zielgruppen-Dokumente vorhanden (`docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md`) +- [ ] Persistente Daten liegen ausschließlich in `/data//` (nie woanders) +- [ ] `history/summary/PROJECT_CONTEXT.md` aktualisiert +- [ ] Commit message follows Conventional Commits +- [ ] No dead code, no TODOs left behind (or tracked as issues) +- [ ] pre-commit Quality Gate bestanden -## Tile-Server spezifische Hinweise -- Martin serviert Tiles direkt aus MBTiles/PMTiles – kein server-seitiges Rendering -- Clients (MediaWiki, Nextcloud, HA) rendern OSM-Vektorkacheln via MapLibre GL im Browser -- Satellit-Raster-Tiles (PNG) werden direkt aus raster MBTiles durchgereicht -- Hot-Reload: neue `.mbtiles`-Datei in `data/` ablegen → sofort unter `/catalog` sichtbar -- Zoom-Level 0–14 reichen für die meisten Anwendungsfälle (Dateigröße vs. Detail) -- Planetiler benötigt min. 4 GB RAM für Deutschland, 8 GB für Europa -- Satellitenkacheln: kostenfrei nur bis Zoom 10 (NASA GIBS oder maptiler.com) -- TileJSON-Endpoints: `/{source_id}` z.B. `/osm`, `/satellite` -- Katalog aller geladenen Sources: `/catalog` +## Testing Strategy + +- Framework: +- Coverage target: ≥ 80% (critical paths: 100%) +- Test pyramid: unit > integration > e2e +- Test location: `tests/` mirroring source structure ## Security -- Keine Secrets in martin.yaml oder docker-compose.yml -- NPM Rate-Limiting aktiv halten -- Port 3000 nur intern exponieren wenn NPM im selben Docker-Netz läuft -- CORS auf `*` ist für internes LAN akzeptabel – für public deployment einschränken +- No secrets in code or config files – use environment variables +- Validate all inputs at system boundaries +- Principle of least privilege for all permissions +- Dependency vulnerabilities: check before adding new deps + +## Documentation Standards +- Code comments: explain WHY, not WHAT +- Public APIs: always documented +- Architecture decisions: write ADR in `docs/adr/` (template: `docs/adr/000-template.md`) +- CHANGELOG.md: update with every release +- **3-Zielgruppen-Regel:** USER.md (Endnutzer) + ADMIN.md (Ops) + MAINTAINER.md (Dev) – immer alle 3 pflegen ## Non-Functional Requirements -- Tile-Response: < 200ms für gecachte Tiles -- Availability: best-effort (kein HA erforderlich) -- Daten-Update-Zyklus: OSM monatlich (Planetiler-Re-Run), Satellit nach Bedarf + +- Response time: +- Availability: +- Data retention: