---
name: gh-tickets
description: "Konventionen für Forgejo-Issues in diesem Workspace: Aufgabentyp-Labels, Sortierung über status:todo-Labels und CLI-Abfragen. Verwende diesen Skill immer dann, wenn Issues angelegt, abgefragt, sortiert oder vom nextstep-Router verarbeitet werden. Trigger-Phrasen: 'nächstes Ticket', 'Issue anlegen', 'Reihenfolge', 'Priorität', 'nextstep', 'Status', 'Board'."
---

# Skill: Forgejo Tickets (gh-tickets)

Dieses Dokument definiert die verbindlichen Konventionen für Issues im Forgejo-Repository `bollwerkadmin/bollwerk` (`https://git.bollwerk.online`).

---

## 1. Aufgabentyp (Pflicht-Label)

Jedes Issue MUSS genau **eines** dieser Type-Labels tragen:

| Label            | Kürzel | Beschreibung                                                                   |
| ---------------- | ------ | ------------------------------------------------------------------------------ |
| `block-planning` | [B]    | Grobplanung – zerlegt Projekt in Blocks, erstellt [T]- und [P]-Tickets         |
| `feature`        | [F]    | Feature-Entwicklung – Neuentwicklung ohne Referenz-Altcode                     |
| `refactoring`    | [F]    | Architektur-Refactoring – wird wie Feature behandelt (workflow-implementation) |
| `tech-decision`  | [T]    | Technologie-Entscheidung (User trifft die Wahl)                                |
| `infrastructure` | [I]    | Infrastruktur, Prozess, Tooling, Dokumentation                                 |
| `planning`       | [P]    | Planungsaufgabe – zerlegt grobes Ticket in Arbeitspakete                       |
| `test`           | [X]    | Generaltest oder Coverage-Check eines abgeschlossenen Bereichs                 |

### Validierung

Bevor ein Workflow gestartet wird, prüfe ob das Issue ein Type-Label hat. Falls nicht:

```
⚠️  Issue #<N> hat kein Type-Label (block-planning/feature/migration/refactoring/tech-decision/infrastructure/planning/test).
    Bitte eines der Labels zuweisen, bevor der Workflow starten kann.
```

Stoppe und fordere den User zur Zuordnung auf. Starte den Workflow **nicht** ohne Type-Label.

### Mapping zum Workflow

| Label            | Workflow-Prompt                                     |
| ---------------- | --------------------------------------------------- |
| `block-planning` | `.github/prompts/nextstep-block-planning.prompt.md` |
| `feature`        | `.github/prompts/nextstep-implementation.prompt.md` |
| `migration`      | `.github/prompts/nextstep-implementation.prompt.md` |
| `refactoring`    | `.github/prompts/nextstep-implementation.prompt.md` |
| `tech-decision`  | `.github/prompts/nextstep-tech-decision.prompt.md`  |
| `infrastructure` | `.github/prompts/nextstep-infrastructure.prompt.md` |
| `planning`       | `.github/prompts/nextstep-planning.prompt.md`       |
| `test`           | `.github/prompts/nextstep-test.prompt.md`           |

---

## 2. Sortierung über Status-Labels

Die Abarbeitungsreihenfolge wird über **Status-Labels** in Forgejo gesteuert.

### Status-Labels

| Label               | Bedeutung                                         |
| ------------------- | ------------------------------------------------- |
| `status:todo`       | Nächste offene Aufgabe (wird von next-ticket.ps1 gefunden) |
| `status:in-progress`| Aktuell in Bearbeitung                            |
| `status:done`       | Abgeschlossen                                     |
| `status:backlog`    | Im Backlog – wird erst nach todo-Items bearbeitet |

### Repository

| Eigenschaft  | Wert                                              |
| ------------ | ------------------------------------------------- |
| URL          | https://git.bollwerk.online/bollwerkadmin/bollwerk |
| API-Base     | https://git.bollwerk.online/api/v1                |
| Token        | `.github/skills/gh-tickets/forgejo-token.txt` (lokal, nicht committed) |

### Nächstes offenes Issue ermitteln

**Skript:** `.github/skills/gh-tickets/next-ticket.ps1`

```powershell
# Nächstes Ticket (priority:high zuerst, dann Issue-Nummer aufsteigend):
& ".github/skills/gh-tickets/next-ticket.ps1"

# Bestimmtes Issue abfragen (Typ-Label prüfen):
& ".github/skills/gh-tickets/next-ticket.ps1" -IssueNumber 128
```

Ausgabe: `#128 [I] infra(forgejo): Projektlinks, Skills und Referenzen umstellen (Order: 128)`

### Status aktualisieren

**Skript:** `.github/skills/gh-tickets/set-board-status.ps1`

```powershell
# Status auf "In Progress" setzen
& ".github/skills/gh-tickets/set-board-status.ps1" -IssueNumber 128 -Status InProgress

# Status auf "Done" setzen
& ".github/skills/gh-tickets/set-board-status.ps1" -IssueNumber 128 -Status Done

# Status auf "Todo" zurücksetzen
& ".github/skills/gh-tickets/set-board-status.ps1" -IssueNumber 128 -Status Todo
```

Gültige Status-Werte: `Todo`, `InProgress`, `Done`, `Backlog`

---

## 3. Issue anlegen (Checkliste)

Beim Anlegen eines neuen Issues **MÜSSEN alle 3 Schritte** durchgeführt werden:

1. **Titel**: Beschreibend, ggf. mit Modulpräfix (z.B. `feat(core):`, `infra(forgejo):`)
2. **Type-Label**: Genau eines von `migration`, `tech-decision`, `infrastructure`, `block-planning`, `feature`, `refactoring`, `planning`, `test`
3. **Status-Label**: `status:todo` (sofort bearbeiten) oder `status:backlog` (später)

> **Kein Issue ohne Status-Label!** Ein Issue ohne `status:todo` oder `status:backlog` wird bei „nächste Aufgabe" nicht gefunden.

### Dringend vorgezogenes Issue anlegen ("als nächstes")

**Skript:** `.github/skills/gh-tickets/create-next-ticket.ps1`

Wenn während einer laufenden Aufgabe ein neues Issue entdeckt wird, das **direkt danach** bearbeitet werden soll:

```powershell
# Issue anlegen mit status:todo (wird als nächstes gefunden, niedrigste Nummer)
& ".github/skills/gh-tickets/create-next-ticket.ps1" -Title "fix(server): Bug in Auth" -Labels "infrastructure" -Body "Beschreibung..."

# Issue ins Backlog legen
& ".github/skills/gh-tickets/create-next-ticket.ps1" -Title "feat: Neues Feature" -Labels "feature" -Status Backlog
```

Das Skript erledigt automatisch: Issue anlegen + Status-Label setzen.
**Trigger-Phrasen:** „als nächstes anlegen", „nächstes Ticket erstellen", „direkt danach bearbeiten"

---

## 4. Sortierung: Priorität + Issue-Nummer (zweistufig)

Die Abarbeitungsreihenfolge wird **zweistufig** bestimmt:

1. **Primär: Label `priority:high`** → Issues mit diesem Label kommen **immer zuerst**
2. **Sekundär: Label `priority:low`** → Issues mit diesem Label kommen **immer zuletzt**
3. **Tertiär: Issue-Nummer aufsteigend** → Niedrigere Nummer = früher erstellt = höhere Priorität

Beispiel: Ein Issue #50 mit `priority:high` kommt **vor** Issue #10 ohne Priorität.