Conrad Schulz
045e2e7202
- New repo convention: /data/<service>/ for all persistent service data (gitignored) - New repo convention: /history/prompts/ (gitignored) + /history/summary/PROJECT_CONTEXT.md for agent session logging and compressed project context - git-templates/hooks/pre-commit: quality gate checking tests + docs on every commit - git-templates/docs/: USER.md, ADMIN.md, MAINTAINER.md templates (3 target groups) - git-templates/history/summary/PROJECT_CONTEXT.md: agent context template - prompts/history.prompt.md: /history prompt for logging sessions + updating summary - copilot-bootstrap.sh: creates all new folders, .gitignore entries, installs hook - deploy.sh + deploy.fish: deploy hooks, doc templates, history template - docs/ADMIN.md: new admin handbook for this project - docs/USER.md + docs/MAINTAINER.md: updated with new conventions - git-templates/.github/copilot-instructions.md: extended DoD + new conventions - README.md: updated structure overview + prompt table
131 lines
3.6 KiB
Markdown
131 lines
3.6 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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):**
|
||
```bash
|
||
cp ~/.git-templates/hooks/pre-commit /path/to/repo/.git/hooks/pre-commit
|
||
chmod +x /path/to/repo/.git/hooks/pre-commit
|
||
```
|
||
|
||
**Hook deaktivieren (pro Commit):**
|
||
```bash
|
||
git commit --no-verify -m "..."
|
||
```
|
||
|
||
**Hook dauerhaft deaktivieren (pro Repo):**
|
||
```bash
|
||
chmod -x .git/hooks/pre-commit
|
||
```
|
||
|
||
---
|
||
|
||
## Bestehende Repos ausstatten
|
||
|
||
```bash
|
||
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/` (gitignored) + `history/summary/PROJECT_CONTEXT.md`
|
||
- `docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md`
|
||
- `.git/hooks/pre-commit`
|
||
- `.gitignore`-Einträge für `data/**/*` und `history/prompts/*`
|
||
|
||
---
|
||
|
||
## `~/.local/bin/` im PATH?
|
||
|
||
Das Bootstrap-Skript wird in `~/.local/bin/` installiert. Sicherstellen dass dieser Pfad im `$PATH` ist:
|
||
|
||
**bash/zsh** (`~/.bashrc` / `~/.zshrc`):
|
||
```bash
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
```
|
||
|
||
**fish** (`~/.config/fish/config.fish`):
|
||
```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 obwohl alles ok | Falsch-positiver Match | `git commit --no-verify` |
|
||
| Hook nicht aktiv nach `git clone` | Hooks werden bei `clone` nicht kopiert | `copilot-bootstrap.sh` im geklonten Repo ausführen |
|