Orchestrator/bahn/O2C-Harness/planning.md

# Planung mit Responsible Vibe + GitLab Issues

## Entwicklungsprozess

Nutze den `workflows` MCP Server (Responsible Vibe) für strukturierte Entwicklung:

1. **`start_development()`** – Workflow starten (greenfield für neue Projekte)
2. **`whats_next()`** – Nach JEDER Aktion aufrufen für nächsten Schritt
3. **`proceed_to_phase()`** – Phase wechseln wenn Kriterien erfüllt

## GitLab Issues: PFLICHT vor Implementierung

**BEVOR du eine einzige Zeile Code schreibst**, MUSST du Issues anlegen:

```bash
# Labels erstellen (einmalig)
glab label create "enhancement" --color "#428BCA"
glab label create "bug" --color "#d9534f"
glab label create "documentation" --color "#5cb85c"
glab label create "test" --color "#f0ad4e"
glab label create "ci/cd" --color "#777777"
glab label create "refactoring" --color "#9b59b6"

# Issues anlegen – JEDE Aufgabe wird ein Issue
glab issue create --title "feat: REST Controller implementieren" --description "Endpoints: GET/POST/PUT/DELETE /api/..." --label "enhancement"
glab issue create --title "feat: Service-Layer mit Business-Logik" --description "Validierung, Error-Handling, ..." --label "enhancement"
glab issue create --title "test: Unit- und Integrationstests" --description "Controller-Tests, Service-Tests, Testcontainers" --label "test"
glab issue create --title "docs: Arc42 + README" --description "Context-Diagramm, ADRs, API-Doku" --label "documentation"
glab issue create --title "ci: Pipeline konfigurieren" --description ".gitlab-ci.yml, Helm Values, Deployment" --label "ci/cd"
```

**Reihenfolge:**
1. Aufgabe analysieren
2. In 3-7 Issues zerlegen
3. Issues in GitLab anlegen
4. Erst DANN implementieren

## Ablauf (strikt einhalten)

1. `start_development()` → Workflow initialisieren
2. `whats_next()` → Plan erstellen
3. **Issues in GitLab anlegen** (PFLICHT, nicht optional!)
4. Issues der Reihe nach abarbeiten:
   - Implementieren
   - Testen
   - Committen mit Issue-Referenz: `feat(users): implement GET endpoint (#1)`
   - Issue schließen: `glab issue close 1`
5. `whats_next()` → Nächste Phase
6. Wiederholen bis alle Issues geschlossen

## Commit-Messages: Conventional Commits (Pflicht)

```
feat(controller): implement GET /users endpoint (#1)
feat(service): add validation and error handling (#2)
test(controller): add WebMvcTest for UserController (#3)
docs(arc42): add context diagram and ADR-1 (#4)
ci(pipeline): add .gitlab-ci.yml from pipelinetemplates (#5)
```

Format: `type(scope): beschreibung (#issue-nummer)`

## Fragen selbst beantworten

Responsible Vibe stellt in den Phasen Fragen (z.B. "Wer nutzt das System?", "Welche Constraints gibt es?").

**WICHTIG:** Diese Fragen NICHT an den Benutzer weiterleiten. Beantworte sie selbst basierend auf:
1. Der Ticket-Beschreibung / Aufgabe ($TICKET_DESCRIPTION)
2. Dem Projekt-Kontext (vorhandener Code, README, etc.)
3. Best Practices und Conventions aus dem Steering
4. Sinnvollen Defaults wenn keine Info vorhanden

Der Agent arbeitet autonom – er ist Entwickler UND Product Owner in einem.

## Issue-Labels nach Workflow-Typ

| Workflow | Label | Beschreibung |
|----------|-------|-------------|
| greenfield | `enhancement` | Neues Projekt/Feature |
| epcc | `enhancement` | Feature zu bestehendem Projekt |
| bugfix | `bug` | Fehlerbehebung |
| tdd | `test` | Test-getriebene Entwicklung |
| minor | `chore` | Kleine Änderung/Refactoring |

## GitLab Issues: Qualität

Issues MÜSSEN ausführlich in Markdown geschrieben werden:

### Format

```bash
glab issue create \
  --title "feat: Address REST API (CRUD)" \
  --label "enhancement" \
  --description "## Beschreibung

REST Controller mit vollständigen CRUD Endpoints für die Adressverwaltung.

## Anforderungen

- GET /api/addresses – Alle Adressen auflisten
- GET /api/addresses/{id} – Einzelne Adresse
- POST /api/addresses – Neue Adresse anlegen
- PUT /api/addresses/{id} – Adresse aktualisieren
- DELETE /api/addresses/{id} – Adresse löschen

## Akzeptanzkriterien

- [ ] Alle Endpoints implementiert und getestet
- [ ] Validierung der Eingaben (Name, PLZ nicht leer)
- [ ] Korrekte HTTP Status Codes (201, 404, 400)
- [ ] JSON Request/Response Format dokumentiert

## Technische Details

- Spring @RestController
- @Valid für Bean Validation
- ResponseEntity für Status Codes"
```

### Regeln

- **Mehrzeilige Descriptions**: Heredoc oder mehrzeilige Strings nutzen, KEINE `\n` Escapes
- **Markdown-Struktur**: Überschriften (##), Listen (-), Checkboxen (- [ ])
- **Inhalt**: Beschreibung, Anforderungen, Akzeptanzkriterien, technische Details
- **Ausführlich**: Jedes Issue muss für sich allein verständlich sein

## Arc42 Dokumentation: PFLICHT-Issue

Bei JEDEM Projekt muss ein Issue für Arc42-Doku angelegt und abgearbeitet werden:

```bash
glab issue create \
  --title "docs: Arc42 Dokumentation erstellen" \
  --label "documentation" \
  --description "## Beschreibung

Arc42-Dokumentation unter docs/arc42/ anlegen.

## Pflicht-Inhalte

- docs/arc42/01-introduction.md (Aufgabenstellung, Qualitätsziele)
- docs/arc42/03-context.md (C4 Context-Diagramm als Mermaid)
- docs/arc42/05-building-blocks.md (Komponenten-Übersicht)
- docs/arc42/06-runtime-view.md (Sequenzdiagramm Hauptflow)
- docs/arc42/09-architecture-decisions.md (mind. 1 ADR im Nygard-Format)

## Akzeptanzkriterien

- [ ] Mindestens 5 Arc42-Dateien unter docs/arc42/
- [ ] C4 Context-Diagramm als Mermaid
- [ ] Mindestens 1 ADR (z.B. Stack-Wahl, Datenbank-Wahl)
- [ ] Sequenzdiagramm für den Hauptflow"
```

Arc42-Doku ist kontextabhängig:
- Services/APIs mit Deployment → Arc42 anlegen
- Libraries, CLI-Tools, Doku-Repos → KEINE Arc42 nötig
- Bestehende Projekte mit vorhandener Doku → nur ergänzen wenn sinnvoll