rd13_copilot_setup/docs/USER.md

# Benutzerhandbuch – rd13_copilot_setup

Dieses Dokument erklärt wie du das Copilot-Setup auf einem neuen System einrichtest und täglich nutzt.

---

## Ersteinrichtung auf einem neuen System

### Schritt 1: Repo klonen

```bash
git clone <repo-url> ~/dotfiles/copilot-setup
cd ~/dotfiles/copilot-setup
```

### Schritt 2: Deploy-Skript ausführen

```bash
bash scripts/deploy.sh        # macOS oder Linux (bash)
fish scripts/deploy.fish      # Linux mit fish-Shell
```

Das Skript erledigt **einmalig** alles automatisch:

| Was | Wo |
|---|---|
| VS Code User-Settings | `~/.vscode-server/data/User/settings.json` (Remote) / `~/.config/Code/User/` (lokal) |
| Prompt Files | `~/.vscode-server/data/User/prompts/` |
| Git-Templates | `~/.git-templates/` |
| Bootstrap-Skript | `~/.local/bin/copilot-bootstrap.sh` |
| Git-Alias `init-copilot` (opt-in) | `~/.gitconfig` |

### Schritt 3: VS Code Settings Sync aktivieren (optional)

`Ctrl+Shift+P` → **Settings Sync: Turn On** → Mit GitHub-Account einloggen → Alle Elemente auswählen

---

## Tägliche Nutzung

### Neues Repo anlegen

```bash
git init-copilot mein-projekt
cd mein-projekt
```

Der Opt-in-Alias `git init-copilot` macht `git init` **und** Bootstrap in einem Schritt –
er legt `.github/copilot-instructions.md`, `.vscode/`, `docs/`, `history/` und den
pre-commit Hook an. (Der normale `git init` bleibt unverändert.) Danach:

1. Die `TODO`-Felder in `.github/copilot-instructions.md` ausfüllen
2. Committen:
   ```bash
   git add .github .vscode
   git commit -m "chore: add copilot workspace config"
   ```

### Bestehendes oder geklontes Repo ausstatten

```bash
cd /pfad/zum/repo
copilot-bootstrap.sh
# oder: sh ~/.local/bin/copilot-bootstrap.sh
```

### Prompt Files im Chat nutzen

In GitHub Copilot Chat einfach `/` tippen:

| Prompt | Wofür |
|---|---|
| `/requirements` | Requirements Engineering Workshop |
| `/architecture` | Architektur-Review + ADR erstellen |
| `/new-feature` | Vollständiger Feature-Workflow |
| `/code-review` | Security + Qualitäts-Review |
| `/debug` | Root-Cause-Analyse + Fix |
| `/refactor` | Refactoring ohne Behavior-Change |
| `/write-tests` | Test-Generierung |
| `/done-check` | Definition of Done Checkliste |
| `/docker` | Docker/Compose-Aufgaben |
| `/history` | Agent-History loggen + Kontext-Summary aktualisieren |
| `/check-consistency` | Konsistenzprüfung: Code vs. Requirements vs. Docs |

---

## Was jedes neue Repo bekommt

Nach `git init-copilot` oder `copilot-bootstrap.sh` erhält jedes Repo automatisch:

| Was | Wo | Zweck |
|---|---|---|
| Copilot-Anweisungen | `.github/copilot-instructions.md` | Agent-Verhalten für dieses Repo |
| VS Code-Einstellungen | `.vscode/settings.json` | Repo-spezifische Editor-Konfiguration |
| Empfohlene Extensions | `.vscode/extensions.json` | Extension-Vorschläge für das Team |
| Persistente Daten | `data/` | Service-Daten getrennt nach Service-Namen |
| Agent-Logs | `docs/history/prompts/` | Vollständige Konversationen (committed) |
| Agent-Kontext | `docs/history/summary/PROJECT_CONTEXT.md` | Komprimierter Projektzustand für Agenten |
| Nutzer-Doku | `docs/USER.md` | Dokumentation für Endnutzer |
| Admin-Doku | `docs/ADMIN.md` | Dokumentation für Administratoren |
| Entwickler-Doku | `docs/MAINTAINER.md` | Dokumentation für Entwickler |
| Quality-Gate-Hook | `.git/hooks/pre-commit` | Prüft Tests + Doku bei jedem Commit |

---

## Häufige Fragen

**`copilot-bootstrap.sh: command not found`**  
`~/.local/bin` ist nicht im PATH. Entweder direkt aufrufen: `sh ~/.local/bin/copilot-bootstrap.sh`  
Oder in `~/.bashrc` / `~/.config/fish/config.fish` hinzufügen:
```bash
export PATH="$HOME/.local/bin:$PATH"   # bash/zsh
```
```fish
fish_add_path ~/.local/bin             # fish
```

**`git init-copilot: command not found` oder keine Copilot-Dateien**  
Entweder wurde das deploy-Skript noch nicht ausgeführt (Schritt 1+2 wiederholen), oder
du hast den normalen `git init` benutzt – nutze `git init-copilot` für Auto-Bootstrap,
oder rufe in einem bestehenden Repo `copilot-bootstrap.sh` auf.

**Der pre-commit Hook blockiert meinen Commit**  
Der Hook hat Tests, Dokumentation, Session-Datei oder Requirements vermisst. Optionen:
- Tests schreiben: Copilot Chat → `/write-tests`
- Dokumentation aktualisieren: `docs/USER.md`, `docs/ADMIN.md` oder `docs/MAINTAINER.md`
- Session-Datei stagen: Copilot Chat → `/history`, dann `git add history/`
- Für Repos ohne Test-Framework: `.copilot-no-tests` im Repo-Root anlegen
- Für Repos ohne Doku-Pflicht: `.copilot-no-docs` im Repo-Root anlegen

**Ich will die Templates aktualisieren**  
Im `rd13_copilot_setup`-Repo die Dateien in `git-templates/` ändern, committen, dann `deploy.sh` erneut ausführen.