rd13_copilot_setup/docs/MAINTAINER.md

Maintainer-Handbuch – rd13_copilot_setup

Dieses Dokument beschreibt Architektur, Designentscheidungen und wie das Projekt erweitert wird.

---

Architektur: 3-Schichten-Modell

┌─────────────────────────────────────────────────────────┐
│  Layer 1: Immer aktiv (User settings.json)               │
│  • Senior-Dev-Grundregeln in codeGeneration.instructions │
│  • Commit-Format, Review-Standard, Test-Standard         │
│  • Copilot Feature-Flags                                 │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Auf Abruf (Prompt Files ~/.vscode-server/…)    │
│  • /requirements  /architecture  /new-feature            │
│  • /code-review   /debug         /refactor               │
│  • /write-tests   /done-check    /docker                 │
├─────────────────────────────────────────────────────────┤
│  Layer 3: Repo-spezifisch (.github/copilot-instructions) │
│  • Stack, Konventionen, ADR-Entscheidungen               │
│  • Definition of Done für dieses Projekt                 │
│  • NFRs (Performance, Availability, Security)            │
└─────────────────────────────────────────────────────────┘

---

Dateistruktur

rd13_copilot_setup/
├── docs/
│   ├── USER.md                     ← Endnutzer-Dokumentation
│   ├── ADMIN.md                    ← Administrator-Dokumentation (Deploy, Hooks, PATH)
│   └── MAINTAINER.md               ← Dieses Dokument
├── git-templates/                  ← Template-Quellen für neue Repos
│   ├── .github/
│   │   └── copilot-instructions.md ← Wird pro Repo individualisiert (TODO-Felder)
│   ├── .vscode/
│   │   ├── settings.json           ← Repo-spezifische VS Code Einstellungen
│   │   └── extensions.json         ← Empfohlene Extensions für neue Repos
│   ├── hooks/
│   │   └── pre-commit              ← Agent Quality Gate (Tests + Doku-Check)
│   ├── docs/
│   │   ├── USER.md                 ← Template Endnutzer-Doku
│   │   ├── ADMIN.md                ← Template Admin-Doku
│   │   └── MAINTAINER.md           ← Template Maintainer-Doku
│   └── history/
│       └── summary/
│           └── PROJECT_CONTEXT.md  ← Template Agent-Kontext-Summary
├── prompts/                        ← Wiederverwendbare Copilot-Workflows
│   └── *.prompt.md
├── scripts/
│   ├── deploy.sh                   ← Bash-Deploy (macOS + Linux)
│   ├── deploy.fish                 ← Fish-Deploy (Linux)
│   ├── copilot-bootstrap.sh        ← POSIX-sh Bootstrap für einzelne Repos (Haupt-Script)
│   └── copilot-bootstrap.fish      ← Fish-Variante (legacy, optional)
└── user-settings/
    └── settings.json               ← VS Code User-Level Settings (Layer 1)

---

Wie git init automatisiert wird

Git hat keinen post-init Hook – .github/ und .vscode/ befinden sich im Working Tree, nicht in .git/, weshalb init.templateDir allein nicht ausreicht.

Lösung: Git-Alias mit Rekursionsschutz

In ~/.gitconfig (wird von deploy.sh/.fish gesetzt):

[alias]
    init = !f() { dir=.; for a in "$@"; do case "$a" in -*) ;; *) dir="$a" ;; esac; done; "$(git --exec-path)/git-init" "$@" && "$HOME/.local/bin/copilot-bootstrap.sh" "$dir"; }; f

• ! → externer Shell-Befehl (via /bin/sh), kein Git-Subcommand
• $(git --exec-path)/git-init → ruft das echte git-init-Binary direkt auf, umgeht den Alias → kein Rekursions-Loop
• Letzte Nicht-Flag-Argument wird als Zielverzeichnis erkannt (dir=. als Default)
• Nach erfolgreichem git init wird copilot-bootstrap.sh ausgeführt

---

Neuen Prompt hinzufügen

1. Datei prompts/mein-workflow.prompt.md anlegen
2. Format:

   ---
   mode: agent
   description: Kurzbeschreibung für den Chat-Slash-Command
   ---
   # Mein Workflow
   …
   

3. deploy.sh erneut ausführen → deployed die neue Datei in ~/.vscode-server/…/prompts/
4. In README.md und docs/USER.md in der Prompt-Tabelle eintragen
5. Committen

Template-Dateien ändern

Dateien unter git-templates/ bearbeiten → deploy.sh ausführen → neue Repos bekommen die neue Version. Bestehende Repos werden nicht automatisch aktualisiert (Bootstrap überschreibt nicht).

Wichtig beim Ändern von git-templates/hooks/pre-commit: Die Datei muss nach dem Deployen ausführbar sein (chmod +x). deploy.sh erledigt das automatisch.

Deploy-Skripte ändern

deploy.sh (bash) ist die Referenzimplementierung. deploy.fish sollte immer dieselben Schritte in Fish-Syntax abbilden. Nach Änderungen beide synchron halten.

---

Designentscheidungen

Entscheidung	Begründung
POSIX sh für Bootstrap-Script	Läuft auf jedem System ohne extra Dependencies (kein fish nötig)
Git-Alias statt Fish-Wrapper	Portabel: funktioniert in bash, sh, CI, GUI-Clients – nicht nur in fish
git --exec-path statt command git	command umgeht Aliases in fish/zsh, aber nicht in POSIX sh; --exec-path ist universell
Templates nicht auto-updaten	Idempotenz: Bootstrap überschreibt nie – Nutzer können Templates nach Init anpassen
3 Zielgruppen-Docs (USER/ADMIN/MAINTAINER)	Klare Trennung: Nutzer ≠ Ops ≠ Dev; jede Gruppe findet ihren Kontext direkt
data/ gitignored, Ordner-Struktur tracked	Persistente Daten gehören nie ins Git; Struktur als Konvention dokumentiert
history/prompts/ committed	Vollständige Agent-History bleibt im Repo erhalten; ermöglicht lückenlose Nachvollziehbarkeit
pre-commit Hook als Quality Gate	Automatisches Netz verhindert dass Tests/Doku vergessen werden; --no-verify bleibt als bewusstes Escape-Valve