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

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	plattformspezifisch (Server / lokal / macOS)
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-Skript installieren	~/.local/bin/copilot-bootstrap.sh
6	Git-Alias setzen	~/.gitconfig → git init ruft Bootstrap automatisch auf

---

Git-Templates verwalten

Die Templates unter git-templates/ werden beim Deployen nach ~/.git-templates/ kopiert. Sie werden bei jedem git init automatisch in neue Repos kopiert (via init.templateDir).

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	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-Repo Cache aktualisieren (~/.copilot-setup/)	SSH, HTTP-Fallback
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

---

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)
• history/prompts/ (committed) + history/summary/PROJECT_CONTEXT.md
• docs/USER.md, docs/ADMIN.md, docs/MAINTAINER.md
• .git/hooks/pre-commit
• .gitignore-Einträge für data/**/*

---

~/.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 ruft Bootstrap nicht auf	Git-Alias nicht gesetzt	deploy.sh erneut ausführen
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