Gentle-Programmierung/gentle-ai

Gentle AI – Branch & PR Skill

Wann verwenden

Laden Sie diesen Skill, wenn Sie:

• Einen Branch für einen neuen Fix oder ein Feature erstellen müssen
• Einen Pull-Request auf Gentleman-Programming/gentle-ai öffnen möchten
• Änderungen zur Überprüfung vorbereiten

Kritische Regeln

1. Jeder PR MUSS mit einem genehmigten Issue verknüpft sein — Closes/Fixes/Resolves #<N> im PR-Text, und dieses Issue MUSS status:approved haben. PRs ohne dies werden von CI automatisch abgelehnt.
2. Normale type:*-Kategorisierung — CI lehnt null oder mehrere Typ-Label ab. Leiten Sie dies durch den kanonischen Issue-Erstellungs-Workflow-Vertrag: Eine aktuelle direkte menschliche Anweisung bindet das exakte Ziel/die exakte Aktion, die Ziel-Host-Fähigkeit wird verifiziert, und es wird eine begrenzte Mutation und Ziel-Host-Rücklesung verwendet; andernfalls warten Sie ohne Mutation.
3. Geschützte Policy-Label — Das Hinzufügen oder Entfernen von status:approved oder size:exception erfordert verifizierte Policy-Autorität von einem Ziel-Host-Repository-Maintainer oder einem Repository-autorisierten Genehmiger für das exakte Ziel/die exakte Aktion sowie authentifizierte Akteur-Ziel-Host-viewerPermission MAINTAIN oder ADMIN. size:exception erfordert zusätzlich dokumentierte Überbudget-Begründung.
4. 400-Zeilen-Review-Budget — Halten Sie PRs innerhalb von 400 geänderten Zeilen (additions + deletions) oder dokumentieren Sie die für ein size:exception-Label erforderliche Begründung.
5. Automatisierte Prüfungen müssen bestehen — siehe Tabelle der automatisierten Prüfungen unten.
6. Keine Co-Authored-By-Trailer — Fügen Sie niemals KI-Zuschreibungen zu Commits hinzu.
7. Kein Force-Push auf main/master — geschützter Branch.

Workflow

1. Bestätigen, dass das Issue den Status `status:approved` hat
   gh issue view <N> --repo Gentleman-Programming/gentle-ai

2. Branch von main mit der untenstehenden Namenskonvention erstellen

3. Änderungen gemäß Spezifikationen und Design implementieren

4. Lokale Prüfungen ausführen (Format + Unit + E2E)

5. Mit Conventional Commits-Format committen

6. PR mit Verweis auf das Issue öffnen
   → Genau EIN Ergebnis vom Typ `type:*` im PR-Text deklarieren
   → Den kanonischen Issue-Erstellungs-Workflow-Vertrag vor jeder PR-Label-Mutation verwenden
   → PR-Text mit der Vorlage ausfüllen

7. Alle automatisierten Prüfungen müssen vor dem Merge bestanden sein

---

Branch-Namenskonvention

Branch-Namen müssen diesem Muster entsprechen:

^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

Typ	Beispiel
feat/	feat/user-login
fix/	fix/duplicate-observation-insert
docs/	docs/api-reference-update
refactor/	refactor/extract-query-sanitizer
chore/	chore/bump-bubbletea-v0.26
style/	style/fix-linter-warnings
perf/	perf/optimize-catalog-loading
test/	test/add-pipeline-coverage
build/	build/update-goreleaser-config
ci/	ci/add-e2e-docker-job
revert/	revert/undo-model-picker-change

Regeln:

• Nur Kleinbuchstaben
• Verwenden Sie Bindestriche, Punkte oder Unterstriche als Trennzeichen (keine Leerzeichen, keine Großbuchstaben)
• Beschreibung muss kurz und aussagekräftig sein

---

PR-Text-Format

Der PR-Text muss der Vorlage unter .github/PULL_REQUEST_TEMPLATE.md folgen. Alle Abschnitte sind erforderlich, sofern nicht als optional gekennzeichnet.

## 🔗 Verknüpftes Issue

Closes #<N>

## 🏷️ PR-Typ

- [ ] `type:bug` — Bugfix (nicht-breaking Change, der ein Problem behebt)
- [ ] `type:feature` — Neues Feature (nicht-breaking Change, der Funktionalität hinzufügt)
- [ ] `type:docs` — Nur Dokumentation
- [ ] `type:refactor` — Code-Refactoring (keine funktionalen Änderungen)
- [ ] `type:chore` — Build-, CI- oder Tooling-Änderungen
- [ ] `type:breaking-change` — Breaking Change

## 📝 Zusammenfassung

<!-- Klare Beschreibung, was dieser PR tut und warum. -->

## 📂 Änderungen

| Datei / Bereich | Was geändert wurde |
|-------------|-------------|
| `path/to/file` | Kurzbeschreibung |

## 🧪 Testplan

**Unit-Tests**
```bash
go test ./...

Go-Format

go run ./internal/gofmtcheck

E2E-Tests (Docker erforderlich)

cd e2e && ./docker-test.sh

• Unit-Tests bestanden (go test ./...)
• Go-Format bestanden (go run ./internal/gofmtcheck)
• E2E-Tests bestanden (cd e2e && ./docker-test.sh)
• Lokal manuell getestet

✅ Checkliste für Beitragende

• PR ist mit einem Issue mit status:approved verknüpft
• PR bleibt innerhalb von 400 geänderten Zeilen, oder die size:exception-Begründung und verifizierte Policy-Autorität sind dokumentiert
• API-Rücklesung bestätigt genau ein passendes type:*-Label auf diesem PR
• Unit-Tests bestanden (go test ./...)
• E2E-Tests bestanden (cd e2e && ./docker-test.sh)
• Ich habe bei Bedarf die Dokumentation aktualisiert
• Meine Commits folgen dem Conventional Commits-Format
• Meine Commits enthalten keine Co-Authored-By-Trailer

---

## Automatisierte Prüfungen

Diese Prüfungen werden bei jedem PR ausgeführt und **müssen alle vor dem Merge bestanden sein**:

| Prüfung | Was wird verifiziert | Wie zu beheben |
|-------|-----------------|------------|
| **PR kognitive Last prüfen** | PR bleibt innerhalb von 400 geänderten Zeilen (`additions + deletions`) oder hat `size:exception` | PR aufteilen oder die `size:exception`-Begründung dokumentieren und Policy-Autorität vor der kanonischen Workflow-Aktion verifizieren |
| **Issue-Referenz prüfen** | PR-Text enthält `Closes/Fixes/Resolves #N` | `Closes #<N>` zum PR-Text hinzufügen |
| **Issue hat `status:approved` prüfen** | Verknüpftes Issue hat das erforderliche Label | Den kanonischen Issue-Erstellungs-Workflow-Vertrag nur verwenden, wenn eine aktuelle direkte Anweisung und Ziel-Host-Fähigkeit die genaue Aktion autorisieren; andernfalls warten |
| **PR hat `type:*`-Label prüfen** | Genau ein `type:*`-Label ist auf den PR angewendet | Den kanonischen Issue-Erstellungs-Workflow-Vertrag nur verwenden, wenn eine aktuelle direkte Anweisung und Ziel-Host-Fähigkeit die genaue Aktion autorisieren; andernfalls warten |
| **Unit-Tests** | `go test ./...` besteht | Fehlschlagende Tests vor dem Pushen beheben |
| **Go-Format** | `go run ./internal/gofmtcheck` besteht | Fehlerhafte Go-Dateien vor dem Pushen formatieren |
| **E2E-Tests** | `cd e2e && ./docker-test.sh` besteht | Fehlschlagende E2E-Szenarien vor dem Pushen beheben |

---

## Conventional Commits

Commit-Nachrichten **müssen** diesem Muster entsprechen:

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(([a-z0-9._-]+))?!?: .+

### Format

()!:

[optionaler Body]

[optionaler Footer]

### Erlaubte Typen

| Typ | Zweck | PR-Label |
|------|---------|----------|
| `feat` | Neues Feature | `type:feature` |
| `fix` | Bugfix | `type:bug` |
| `docs` | Nur Dokumentation | `type:docs` |
| `refactor` | Code-Änderung (keine Verhaltensänderung) | `type:refactor` |
| `chore` | Wartung, Abhängigkeiten, Tooling | `type:chore` |
| `style` | Formatierung, Linting (keine Logikänderung) | `type:chore` |
| `perf` | Leistungsverbesserung | `type:feature` |
| `test` | Hinzufügen oder Aktualisieren von Tests | `type:chore` |
| `build` | Build-System oder externe Abhängigkeiten | `type:chore` |
| `ci` | CI-Konfiguration | `type:chore` |
| `revert` | Macht einen vorherigen Commit rückgängig | entspricht dem rückgängig gemachten Typ |

### Breaking Changes

Fügen Sie `!` nach dem Typ/Scope hinzu:

feat(cli)!: rename --config flag to --config-file

BREAKING CHANGE: the --config flag has been renamed to --config-file.

Breaking Changes werden dem `type:breaking-change`-Label zugeordnet.

### Beispiele

feat(tui): progress bar zu installationsschritten hinzugefügt fix(agent): Claude Code-Erkennung auf macOS korrigiert docs: mitwirkungs-leitfaden aktualisiert chore(deps): bubbletea auf v0.26 aktualisiert refactor(pipeline): schritt-ausführer extrahiert style: linter-warnungen im katalog-paket behoben perf(system): OS-erkennungsergebnis zwischengespeichert test(installer): abdeckung für katalog-schritt-ausführung hinzugefügt build: goreleaser-konfiguration für arm64 aktualisiert ci: unit- und e2e-test-jobs getrennt revert: model-picker-neugestaltung rückgängig gemacht feat(cli)!: standard-konfigurationspfad geändert

---

## Befehle

### Einrichtung

```bash
# Vor dem Start bestätigen, dass Issue genehmigt ist
gh issue view <N> --repo Gentleman-Programming/gentle-ai

# Branch erstellen
git checkout main && git pull
git checkout -b fix/<kurzbeschreibung>

Lokales Testen

# Unit-Tests
go test ./...

# Go-Format
go run ./internal/gofmtcheck

# Unit-Tests — spezifisches Paket
go test ./internal/tui/...

# Unit-Tests — ausführlich
go test -v ./...

# E2E-Tests (Docker muss laufen)
cd e2e && ./docker-test.sh

PR öffnen

gh pr create \
  --repo Gentleman-Programming/gentle-ai \
  --title "fix(agent): Claude Code-Erkennung auf Linux korrigiert" \
  --body "$(cat <<'EOF'
## 🔗 Verknüpftes Issue

Closes #42

## 🏷️ PR-Typ

- [x] \`type:bug\` — Bugfix (nicht-breaking Change, der ein Problem behebt)

## 📝 Zusammenfassung

Behebt die fehlgeschlagene Erkennung des Claude Code-Binärs auf Linux, wenn HOME nicht gesetzt ist.

## 📂 Änderungen

| Datei / Bereich | Was geändert wurde |
|-------------|-------------|
| \`internal/agents/claude.go\` | HOME-Umgebungsvariable-Fallback hinzugefügt |

## 🧪 Testplan

- [x] Unit-Tests bestanden (\`go test ./...\`)
- [x] E2E-Tests bestanden (\`cd e2e && ./docker-test.sh\`)
- [x] Lokal manuell getestet

## ✅ Checkliste für Beitragende

- [x] PR ist mit einem Issue mit \`status:approved\` verknüpft
- [x] PR bleibt innerhalb von 400 geänderten Zeilen, oder die \`size:exception\`-Begründung und verifizierte Policy-Autorität sind dokumentiert
- [x] API-Rücklesung bestätigt genau ein passendes \`type:*\`-Label auf diesem PR
- [x] Unit-Tests bestanden (\`go test ./...\`)
- [x] E2E-Tests bestanden (\`cd e2e && ./docker-test.sh\`)
- [x] Ich habe bei Bedarf die Dokumentation aktualisiert
- [x] Meine Commits folgen dem Conventional Commits-Format
- [x] Meine Commits enthalten keine \`Co-Authored-By\`-Trailer
EOF
)"

PR-Status prüfen

gh pr checks --repo Gentleman-Programming/gentle-ai <PR-number>
gh pr view --repo Gentleman-Programming/gentle-ai <PR-number>