---
name: nexus-sdd-workflow
description: Arbeitsablauf für SDD-Karten im Repo l.kirchner/nexus-hub (Family Knowledge Hub). Verwenden bei JEDER Arbeit an einer nexus-Karte - vom Aufnehmen einer Karte aus todo/ bis zum Merge. Deckt ab - Worktree-Disziplin, Karten-Lebenszyklus, Codex-Cross-Review via MCP, CI-Pflicht, Wiki-Pflege, Memory-Hub-Spiegelung.
---

# nexus SDD-Workflow

## Kontext laden (immer zuerst, in dieser Reihenfolge)

1. `docs/00_README.md` — Lesepfad-Manifest des Repos
2. Die nummerierten Docs in Reihenfolge (mind. Brief, PRD, Architektur), soweit fürs Karten-Scope relevant
3. `docs/agent-rules.md` — gemeinsame Regeln (verbindlich)
4. Die Karte selbst unter `.specs/tasks/todo/`
5. Memory Hub (MCP `memory`): Entity `Family Knowledge Hub` für aktuelle Entscheidungen/Lessons

Präzedenz bei Widersprüchen: Repo-Docs > ADRs > Memory Hub > Pipeline-Repo.

## Karten-Lebenszyklus

1. **Aufnehmen:** Karte von `todo/` nach `in-progress/` verschieben (eigener Commit). Pro Karte genau EIN führender Agent (ADR-0001) — steht in der Karte.
2. **Worktree:** Niemals auf dem Haupt-Checkout arbeiten. `git worktree add ../nexus-hub-<karte> -b karte/<nr>-<slug>`.
3. **Implementieren:** Akzeptanzkriterien der Karte sind das Ziel. Jede Karte erweitert die CI passend zu ihrem Scope (`.gitea/workflows/ci.yml`). Commits referenzieren die Karte (`K-1xx: ...`).
4. **Cross-Review:** Vor dem Merge die Änderungen vom jeweils anderen Agenten reviewen lassen — als Claude Code: Codex via MCP-Tool `codex` (read-only Sandbox, Diff + Karte als Kontext übergeben). Findings triagieren: fixen oder begründet ablehnen (in der Karte dokumentieren).
5. **Merge:** Nur bei grüner CI inkl. SICHT-4-Suite. Karte nach `done/` verschieben, offene Folgepunkte als neue Draft-Karten anlegen.
6. **Nacharbeiten (Pflicht, nicht optional):**
   - Wiki `Status` + `Phase-Tracking` aktualisieren (Gitea-MCP `wiki_write`)
   - Entscheidungen → Wiki `Decisions-Log` + ADR + Memory-Hub-Spiegelung (`Decision`-Entity, Relation `PART_OF_PROJECT` → `Family Knowledge Hub`)
   - Neue Projekt-Kommandos in `docs/agent-rules.md` dokumentieren

## Rote Linien

- Keine Funktionalität nur im Frontend (API-first)
- Keine LLM-Calls am Router vorbei
- Keine Karte ohne Tests für ihre Akzeptanzkriterien
- Veraltetes Wiki gilt als Bug