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:

# 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

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:

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