rd13_copilot_setup/docs/ADMIN.md

Administrator-Handbuch – rd13_copilot_setup

Zielgruppe: Administratoren & DevOps – Menschen, die das Setup deployen und auf Systemen verwalten.

---

Systemvoraussetzungen

Komponente	Anforderung
Git	≥ 2.28
Shell	POSIX sh (bash, dash) oder fish ≥ 3.x
VS Code / VS Code Server	beliebige aktuelle Version
OS	Linux oder macOS

---

Deployment auf einem neuen System

Für Repos mit einem Namen beginnend mit rd13_ gilt als Standard-Topologie:

• Der Runner muss in Docker laufen.
• Alle Services werden über Caddy als Reverse Proxy ausgeliefert.
• Die Proxy-Schicht wird zentral im Repo rd13_system_proxy gepflegt.

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

bash scripts/deploy.sh        # bash (macOS + Linux)
# oder
fish scripts/deploy.fish      # fish (Linux)

Was das Deploy-Skript tut

Schritt	Was	Ziel
1	VS Code User-dir ermitteln	Server / Insiders / VSCodium / Cursor / Flatpak / macOS / Windows-WSL
2	settings.json deployen	~/.vscode-server/data/User/ (oder Äquivalent)
3	Prompt Files deployen	~/.vscode-server/data/User/prompts/
4	Git-Templates deployen	~/.git-templates/ inkl. Hooks, Docs, History-Template
5	Bootstrap- + Update-Skripte installieren	~/.local/bin/
6	Git-Aliase setzen	~/.gitconfig → git init-copilot (opt-in) + git copilot-update

Nicht-invasiv: deploy.sh setzt kein globales init.templateDir und überschreibt nicht den Standard-git init. Fremde git init/git clone bleiben unberührt. Auto-Bootstrap nur über den expliziten Alias git init-copilot <pfad>. Optional installiert bash scripts/deploy.sh --with-self-update-hook den post-merge Auto-Deploy für das Setup-Repo selbst.

---

Git-Templates verwalten

Die Templates unter git-templates/ werden beim Deployen nach ~/.git-templates/ kopiert. Von dort nutzen sie copilot-bootstrap.sh und git copilot-update. Sie werden nicht automatisch bei jedem git init kopiert (kein globales init.templateDir mehr) – das geschieht nur per Opt-in: git init-copilot <pfad> oder copilot-bootstrap.sh <pfad>.

Struktur nach Deploy:

~/.git-templates/
├── .github/copilot-instructions.md
├── .vscode/settings.json
├── .vscode/extensions.json
├── hooks/
│   └── pre-commit          ← Agent Quality Gate (ausführbar)
├── docs/
│   ├── USER.md
│   ├── ADMIN.md
│   └── MAINTAINER.md
└── history/
    └── summary/
        └── PROJECT_CONTEXT.md

---

pre-commit Hook verwalten

Der Hook liegt in git-templates/hooks/pre-commit und wird automatisch deployed.

Hook aktivieren in bestehenden Repos (manuell):

cp ~/.git-templates/hooks/pre-commit /path/to/repo/.git/hooks/pre-commit
chmod +x /path/to/repo/.git/hooks/pre-commit

Hook dauerhaft deaktivieren (pro Repo):

chmod -x .git/hooks/pre-commit

Quality Gate – Übersicht der Checks

Check	Was wird geprüft	Opt-out Datei
1	Tests gestaged bei Code-Änderungen	.copilot-no-tests
2	Mindestens eine Zielgruppen-Doku aktualisiert	.copilot-no-docs
3	Alle 3 Zielgruppen-Docs vorhanden (USER/ADMIN/MAINTAINER)	–
4	docs/history/summary/PROJECT_CONTEXT.md aktualisiert	–
5	docs/requirements/REQUIREMENTS.md keine unstaged Änderungen	.copilot-no-requirements
6	Eine *_session.md ist in diesem Commit gestaged	– (kein Opt-out)

Opt-out Dateien – einfach im Repo-Root anlegen um einen Check zu deaktivieren:

touch .copilot-no-tests        # Repo hat kein Test-Framework
touch .copilot-no-docs         # Repo hat keine Doku-Pflicht (reine Scripts/Config)
touch .copilot-no-requirements # Repo verwendet keine REQUIREMENTS.md

Opt-out Dateien committen damit sie für alle gelten:

git add .copilot-no-tests && git commit -m "chore: disable test check (no test framework)"

---

Templates in bestehenden Repos aktualisieren (git copilot-update)

Nach Änderungen am Setup-Repo können alle Repos mit dem neuesten Stand versorgt werden:

cd /path/to/any-repo
git copilot-update

Was git copilot-update tut:

Schritt	Was	Besonderheit
0	Setup-Quelle holen (~/.copilot-setup/ oder COPILOT_SETUP_DIR)	Remote o. lokaler Klon; offline = graceful skip
1b	Script selbst aktualisieren (~/.local/bin/copilot-update.sh)	startet neue Version via exec
2	~/.git-templates/ aktualisieren	Hooks, Docs, History-Template
3	VS Code Prompt-Dateien aktualisieren	~/.vscode-server/.../prompts/
4a	.git/hooks/pre-commit aktualisieren	nur wenn Repo vorhanden
4b	.github/copilot-instructions.md Framework-Sektion aktualisieren	Projekt-Teil (ab ---) bleibt unberührt
4c	Fehlende docs/USER.md, docs/ADMIN.md, docs/MAINTAINER.md anlegen	nur wenn docs/ vorhanden + Datei fehlt; überschreibt nie

Wichtig: Die .github/copilot-instructions.md besteht aus zwei Teilen:

• Framework-Sektion (vor ---): Session-Protokoll, Verbotene Aktionen → wird bei jedem Update überschrieben
• Projekt-Sektion (ab ---): Stack, Architecture, Conventions → bleibt immer erhalten

---

Setup-Quelle konfigurieren (Remote / Offline)

git copilot-update braucht eine Quelle. Reihenfolge: Umgebungsvariable > Config-Datei. Ist nichts erreichbar, endet der Befehl ohne Fehler (graceful skip) – dann gibt es schlicht nichts zu aktualisieren.

Variable	Zweck
COPILOT_SETUP_REMOTE_SSH	SSH-URL des Setup-Repos
COPILOT_SETUP_REMOTE_HTTP	HTTP-URL (Fallback)
COPILOT_SETUP_DIR	Lokaler Klon/Arbeitskopie – Offline-Betrieb ohne Netz
COPILOT_SETUP_CONFIG	Alternativer Pfad zur Config-Datei

Config-Datei (sh-Syntax) unter ~/.config/copilot-setup/config (bzw. $XDG_CONFIG_HOME/copilot-setup/config):

COPILOT_SETUP_REMOTE_SSH="ssh://git@dein-host:22/you/rd13_copilot_setup.git"
COPILOT_SETUP_REMOTE_HTTP="https://dein-host/you/rd13_copilot_setup.git"
# Alternativ rein lokal/offline:
# COPILOT_SETUP_DIR="$HOME/dotfiles/copilot-setup"

Die fish-Variante sourcet die Datei nicht, sondern parst KEY="value" selbst – dieselbe Datei funktioniert für beide Shells.

---

Bestehende Repos ausstatten

cd /path/to/existing-repo
copilot-bootstrap.sh
# oder von überall:
sh ~/.local/bin/copilot-bootstrap.sh /path/to/repo

Das Bootstrap-Skript legt idempotent an:

• .github/copilot-instructions.md
• .vscode/settings.json + .vscode/extensions.json
• data/ (gitignored)
• docs/history/prompts/ (committed) + docs/history/summary/PROJECT_CONTEXT.md
• docs/USER.md, docs/ADMIN.md, docs/MAINTAINER.md
• .git/hooks/pre-commit
• .gitignore-Einträge für data/**/*

---

Migration: history/ → docs/history/

Frühere Versionen legten die Agent-History unter history/ im Repo-Root ab. Neuer Standard ist docs/history/. Bestehende Repos werden automatisch migriert, sobald dort git copilot-update läuft:

cd /path/to/repo
git copilot-update      # erkennt history/ und verschiebt es per git mv nach docs/history/
git commit -m "chore: migrate history to docs/history"

• Verschiebung erfolgt mit git mv (Historie bleibt erhalten); Fallback mv für ungetrackte Dateien.
• Sind beide Verzeichnisse vorhanden, bricht das Tool nicht ab, sondern bittet um manuelles Zusammenführen (git mv history/prompts/* docs/history/prompts/ && git rm -r history).
• Der pre-commit Hook erwartet nach der Migration ausschließlich docs/history/ (Check 4 + Check 6). Un-migrierte Repos müssen einmalig git copilot-update ausführen.

---

~/.local/bin/ im PATH?

Das Bootstrap-Skript wird in ~/.local/bin/ installiert. Sicherstellen dass dieser Pfad im $PATH ist:

bash/zsh (~/.bashrc / ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

fish (~/.config/fish/config.fish):

fish_add_path ~/.local/bin

---

Troubleshooting

Problem	Ursache	Lösung
copilot-bootstrap.sh: command not found	~/.local/bin nicht im PATH	Siehe "PATH" oben
git init-copilot nicht gefunden	Git-Alias nicht gesetzt	deploy.sh erneut ausführen
git copilot-update: „Keine Setup-Quelle"	Remote nicht konfiguriert/erreichbar	COPILOT_SETUP_REMOTE_* oder COPILOT_SETUP_DIR setzen (s. Abschnitt oben)
Hook schlägt fehl: Tests fehlen	Code geändert ohne Tests	/write-tests in Copilot Chat, oder .copilot-no-tests anlegen
Hook schlägt fehl: Doku fehlt	Code geändert ohne Doku-Update	Docs aktualisieren, oder .copilot-no-docs anlegen
Hook schlägt fehl: Session fehlt	*_session.md nicht gestaged	Copilot Chat → /history, dann git add history/
Hook schlägt fehl: REQUIREMENTS.md unstaged	Requirements geändert aber nicht gestaged	git add docs/requirements/REQUIREMENTS.md
Hook nicht aktiv nach git clone	Hooks werden bei clone nicht kopiert	copilot-bootstrap.sh im geklonten Repo ausführen