# 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
<!-- TODO: Beschreibe das Projekt in 1-2 Sätzen -->

## Stack
<!-- TODO: Sprachen, Frameworks, wichtige Tools -->
- Language:
- Framework:
- Database:
- Infrastructure:

## Architecture
<!-- TODO: Relevante Architekturentscheidungen -->
- Pattern (MVC / Hexagonal / Event-driven / ...):
- Key constraints:
- ADR location: `docs/adr/`

## 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 (`/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
<!-- TODO: Projekt-spezifische Konventionen -->
- 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)
- [ ] `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
<!-- TODO: Anpassen auf das Projekt -->
- 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
<!-- TODO: Anpassen -->
- Response time:
- Availability:
- Data retention: