rd13_copilot_setup/git-templates/.github/copilot-instructions.md

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 docs/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 docs/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 docs/history/ && git commit) nachziehen.
3. Aktualisiere docs/history/summary/PROJECT_CONTEXT.md mit dem neuen Projektstand
4. Stage beide Dateien VOR git commit: git add docs/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.

🖥 Terminal-Syntax (MANDATORY – Shell-Fehler vermeiden)

Vor jedem Terminal-Kommando: lies das Feld Default-Shell (Abschnitt „Entwicklungsumgebung", unten nach ---) und nutze die Syntax genau dieser Shell. Die Terminal-Tool-Beschreibung nennt die aktive Shell zusätzlich.

Bei fish (häufiger Fall):

• Variablen: set VAR (cmd) — niemals VAR=$(cmd) (fish bricht ab mit „Unsupported use of '='").
• Blöcke enden mit end, nicht done/fi.

Harte Regel gegen wiederholte Syntaxfehler:

• Nur ein einzelnes, triviales Kommando direkt im Prompt tippen.
• Alles mit Zuweisung, Schleife, Bedingung oder mehreren Statements → in eine .sh-Datei mit #!/usr/bin/env bash schreiben und mit bash datei.sh ausführen. Dann ist die interaktive Shell-Syntax irrelevant und der Fehler kann nicht auftreten.

⚠ Bekannte Fallstricke (nicht vergessen!)

• Scripts mit Self-Update (copilot-update.sh/.fish) immer erst committen+pushen, DANN manuell deployen. Reihenfolge zwingend:

  1. Änderung im Repo vornehmen
  2. git add … && git commit && git push
  3. cp scripts/copilot-update.sh ~/.local/bin/copilot-update.sh
  4. Testen Falsche Reihenfolge (erst deployen, dann committen) → Self-Update überschreibt den manuell deployten Fix mit der alten Version aus dem Remote-Cache. Der Fix geht verloren.

• fi ─── oder end ─── in POSIX-sh/fish: Box-Drawing-Zeichen nie direkt ans fi/end anhängen. Kommentar-Trennlinie immer auf eigener Zeile: # ── Abschnitt ──

• printf '%s\n%s\n' frisst trailing newlines aus $(awk ...) Substitution. Wenn eine Leerzeile zwischen zwei Blöcken erhalten bleiben soll: printf '%s\n\n%s\n' verwenden.

---

🖥 Entwicklungsumgebung

• Default-Shell: fish

Der Agent nutzt diese Shell für alle Terminal-Kommandos und passt die Syntax an (fish ≠ POSIX sh/bash – z.B. set -x VAR wert statt export VAR=wert, (cmd) statt $(cmd), kein &&/||-Verketten in fish-Skripten). Bei anderem System / neuem Repo diesen Wert anpassen.

Project

Stack

• Language:
• Framework:
• Database:
• Infrastructure:

Architecture

• Pattern (MVC / Hexagonal / Event-driven / ...):
• Key constraints:
• ADR location: docs/adr/

rd13_-Konventionen

• In Repos, deren Name mit rd13_ beginnt, muss der Runner in Docker laufen.
• Alle Services laufen hinter einem Caddy als Reverse Proxy.
• Das zentrale Proxy-Repo heißt rd13_system_proxy.

Project Structure Conventions

Persistent Data (/data/)

• Alle persistenten Service-Daten gehören in /data/<service-name>/ (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 (/docs/history/)

• Vollständige Konversationen → docs/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 → docs/history/summary/PROJECT_CONTEXT.md (committed, immer aktuell halten!)
• Beim Start einer neuen Session: docs/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/<ticket>-description, fix/<ticket>-description
• Commit format: Conventional Commits (feat|fix|chore|docs|refactor|test|ci)
• File structure:
• Naming:

Engineering Process

Before starting any task

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)

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/<service>/ (nie woanders)
• docs/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

Testing Strategy

• Framework:
• Coverage target: ≥ 80% (critical paths: 100%)
• Test pyramid: unit > integration > e2e
• Test location: tests/ mirroring source structure

Security

• 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

• Response time:
• Availability:
• Data retention: