add-spec

name	add-spec
description	Neue Spezifikation analysieren, in Phasen aufteilen und in den Master-Implementierungsplan aufnehmen. Erkennt automatisch neue Spec-Dateien.
disable-model-invocation	true
argument-hint	[docs/specs/MeineSpec.md]

Neue Spec analysieren und in den Plan aufnehmen

Dieser Befehl nimmt eine Spezifikations-Datei entgegen, analysiert sie, teilt sie in Phasen auf und integriert sie in den Master-Implementierungsplan.

Eingabe

Der User gibt optional den Pfad zu einer (oder mehreren) Markdown-Spezifikation(en) an, z.B.:

/add-spec docs/specs/MeineNeueSpec.md
/add-spec docs/specs/Spec_A.md docs/specs/Spec_B.md

Falls kein Pfad angegeben wird → automatische Erkennung (siehe Schritt 0).

Anweisungen

0. Automatische Spec-Erkennung (falls kein Pfad angegeben)

Wenn der User keinen Pfad angibt, suche automatisch nach neuen Markdown-Dateien im Repo:

git status --porcelain -- "docs/specs/*.md" "docs/specs/**/*.md"

Das findet Dateien mit Status ?? (untracked), A (staged/added) oder M (modified).

Fall A: Keine neuen Specs gefunden

• Informiere den User: "Keine neuen Spec-Dateien gefunden."
• Frage nach dem Pfad zur Spec-Datei.

Fall B: Genau eine neue Spec gefunden

• Zeige dem User die gefundene Datei und fahre mit Schritt 1 fort.

Fall C: Mehrere neue Specs gefunden

• Liste alle gefundenen Specs auf, z.B.:

  Neue Spec-Dateien gefunden:
    1. docs/specs/WeatherSystem_Spec.md
    2. docs/specs/WeatherSystem_Effects.md
    3. docs/specs/CraftingSystem_Spec.md
  

• Frage den User, welche Spec(s) verarbeitet werden sollen:
  • Einzelne Spec → Normaler Ablauf (Schritt 1)
  • Mehrere Specs für ein Epic → Konsolidierung (Schritt 0b)
  • Alle einzeln → Nacheinander als separate Epics verarbeiten

0b. Mehrere Specs konsolidieren

Wenn der User mehrere Specs auswählt, die zu einem Epic gehören:

1. Alle gewählten Specs vollständig lesen
2. Überschneidungen und Widersprüche identifizieren
   • Gleiche Konzepte mit unterschiedlichen Details → zusammenführen
   • Widersprüchliche Definitionen → dem User zur Klärung vorlegen
3. Konsolidierte Zusammenfassung erstellen
   • Alle Kernkomponenten aus allen Specs zusammentragen
   • Einheitliches Datenmodell ableiten
   • Gemeinsame Abhängigkeiten identifizieren
4. Konsolidierte Spec-Datei erstellen unter docs/specs/:
   • Dateiname: beschreibend, z.B. WeatherSystem_Specification.md
   • Inhalt: Eigenständige, vollständige Spezifikation (keine Verweise auf die Originale nötig)
   • Die konsolidierte Spec muss ohne die Originale verständlich sein
   • WICHTIG: Alle Punkte aus allen Quell-Specs müssen im gleichen Detaillierungsgrad enthalten sein. Nichts darf zusammengefasst, gekürzt oder abstrahiert werden. Die konsolidierte Spec ist eine Zusammenführung, keine Zusammenfassung.
5. User fragen ob Original-Specs gelöscht werden sollen
   • Zeige die Quell-Dateien auf und frage: "Sollen die Original-Specs gelöscht werden?"
   • Ja → Dateien löschen (die konsolidierte Spec enthält alles)
   • Nein → Original-Specs bleiben erhalten
6. Weiter mit Schritt 1 unter Verwendung der konsolidierten Spec

1. Spec-Datei(en) lesen und analysieren

Lies die angegebene(n) Spec-Datei(en) vollständig und identifiziere:

• Titel/Name des Features/Systems
• Scope: Was wird gebaut? Welche Packages/Ordner sind betroffen?
• Kernkomponenten: Welche Klassen, Systeme, Services werden benötigt?
• Abhängigkeiten: Braucht dieses Feature andere Epics/Phasen?
• Komplexität: Wie viele Phasen sind sinnvoll?
• Implementierungs-Reihenfolge: Was muss zuerst gebaut werden?

2. Master-Plan lesen

Lies docs/implementation/README.md und identifiziere:

• Welche Epics existieren bereits (beschreibende Titel, keine Buchstaben-Prefixe)
• Welche Phasen-Nummern sind bereits vergeben
• Die nächste freie Phasen-Nummer

3. Phasen-Aufteilung vorschlagen

Teile die Spec in sinnvolle Phasen auf. Dabei gelten folgende Regeln:

Granularität:

• Eine Phase = ein zusammenhängendes, abgeschlossenes Teilsystem
• Jede Phase soll 3–7 Schritte haben
• Jede Phase soll für sich kompilierbar und testbar sein
• Datenmodell/Core immer als erste Phase
• UI/Integration immer als letzte Phase(n)

Reihenfolge:

1. Package-Struktur + Datenmodell
2. Core-Logik / Services
3. Subsysteme (einzeln, nach Abhängigkeit sortiert)
4. UI / Scene
5. Persistenz / Integration / Polish

Für jede Phase definieren:

• Phasen-Nummer (fortlaufend nach letzter vergebener Nummer)
• Name (kurz, beschreibend)
• Integration-Branch-Name (Format: integration/phase-X-beschreibung)
• Ziel (1-2 Sätze)
• Vorläufige Schritte (als Checkbox-Liste)
• Referenz auf relevante Spec-Kapitel
• Spec-Zuordnung pro Schritt (vorläufig): Für jeden vorläufigen Schritt notieren, welche Spec-Kapitel/Sektionen besonders relevant sind. Diese Zuordnung wird von /plan-phase in Schritt 5d verfeinert und als ## Relevante Spezifikationen in die Schritt-Dateien eingetragen.

4. Vorschlag dem User präsentieren

Zeige dem User:

• Den vorgeschlagenen Epic-Namen (beschreibend, kein Buchstaben-Prefix)
• Die Anzahl der Phasen
• Für jede Phase: Nummer, Name, Integration-Branch, Ziel, vorläufige Schritte
• Abhängigkeiten zu bestehenden Epics/Phasen
• Frage ob Anpassungen gewünscht sind

WICHTIG: Nicht direkt in den Plan schreiben! Erst dem User zeigen und auf Bestätigung warten.

5. Nach Bestätigung: Plan aktualisieren

Aktualisiere docs/implementation/README.md:

Epic-Übersicht Tabelle:

• Neue Zeile mit Epic-Name (beschreibend), Phasen-Range, Status

Phasen-Übersicht Tabelle:

• Neue Zeilen für jede Phase mit allen Spalten:

  | Phase | Epic | Name | Features | Ausgearbeitet | Status |
  | X     | Epic | Name | —        | ❌            | Offen  |
  

• Alle neuen Phasen: Features = —, Ausgearbeitet = ❌, Status = Offen

Abhängigkeiten-Diagramm:

• Neues Epic mit internen Abhängigkeiten ergänzen
• Kreuz-Abhängigkeiten zu bestehenden Epics/Phasen eintragen

Neuer Epic-Abschnitt:

• Epic-Überschrift (H1) mit beschreibendem Titel und kurzer Beschreibung
• Verweis auf Haupt-Spezifikation
• Package-Liste (falls relevant)
• Für jede Phase ein Abschnitt (H3) mit:
  • **Branch:** \integration/phase-X-beschreibung``
  • **Ausgearbeitet:** ❌ Nein
  • Ziel-Beschreibung
  • **Schritte (vorläufig):** als Checkbox-Liste
  • Spec-Referenz

6. Zusammenfassung

Zeige dem User:

• Was hinzugefügt wurde
• Nächster empfohlener Schritt (/plan-phase für Detail-Ausarbeitung)
• Welche Phase als erstes dran wäre

7. KEINEN Commit erstellen

Die Änderungen werden NICHT automatisch committed. Der User entscheidet selbst, wann und wie committed wird.

Beispiel-Ausgaben

Beispiel 1: Einzelne Spec (mit Pfad)

/add-spec docs/specs/CraftingSystem_Spec.md

Spec analysiert: "Crafting System Specification"

Vorschlag für neues Epic:

Crafting & Berufe (3 Phasen)
├── Phase 17: Crafting Core Data Model
│   Branch: integration/phase-17-crafting-data-model
│   Ziel: Rezepte, Materialien, Stationen als Datenmodell
│   Schritte: Package-Struktur, RecipeDefinition, MaterialType, CraftingStation, Tests
│
├── Phase 18: Crafting Pipeline & Logic
│   ...
└── ...

Soll ich das so in den Plan aufnehmen? (Anpassungen möglich)

Beispiel 2: Automatische Erkennung (ohne Pfad)

/add-spec

Neue Spec-Dateien gefunden:
  1. docs/specs/WeatherSystem_Spec.md          (untracked)
  2. docs/specs/WeatherSystem_Effects.md        (untracked)
  3. docs/specs/CraftingSystem_Spec.md          (untracked)

Welche Specs sollen verarbeitet werden?
  → Einzelne Spec auswählen (1, 2 oder 3)
  → Mehrere für ein Epic konsolidieren (z.B. 1+2)
  → Alle einzeln nacheinander

Beispiel 3: Konsolidierung mehrerer Specs

User wählt: 1+2 (konsolidieren)

Lese 2 Specs...
  ✓ WeatherSystem_Spec.md (Grundsystem, Wetterzyklus, Biome)
  ✓ WeatherSystem_Effects.md (VFX, Audio, Gameplay-Effekte)

Überschneidungen:
  - Beide definieren WeatherType Enum → zusammengeführt (Spec hat 6, Effects hat 8 → 8 übernommen)
  - Keine Widersprüche gefunden

Konsolidierte Spec erstellt: docs/specs/WeatherSystem_Specification.md

Original-Specs löschen?
  - docs/specs/WeatherSystem_Spec.md
  - docs/specs/WeatherSystem_Effects.md
User: Ja → gelöscht

Vorschlag für neues Epic:

Dynamisches Wetter & Umgebungseffekte (4 Phasen)
├── Phase 17: Weather Core Data Model
│   Branch: integration/phase-17-weather-data-model
│   Quellen: WeatherSystem_Spec.md Kap. 2-4, WeatherSystem_Effects.md Kap. 1
│   ...
└── ...

Soll ich das so in den Plan aufnehmen? (Anpassungen möglich)

Hinweise

• Spec-Dateien liegen typischerweise unter docs/specs/
• Falls die Spec bereits im Plan referenziert wird, darauf hinweisen
• Falls die Spec zu klein ist für mehrere Phasen (< 3 Klassen), als einzelne Phase aufnehmen
• Falls die Spec zu vage ist, offene Fragen sammeln und dem User stellen
• Epics haben keine Buchstaben-Prefixe (A, B, C) — nur beschreibende Titel
• Die Reihenfolge zwischen Epics ist nicht festgelegt und ergibt sich aus Abhängigkeiten
• Bei Konsolidierung: Die konsolidierte Spec ist eigenständig (keine Verweise auf Originale), daher können Originale nach Rückfrage gelöscht werden
• git status --porcelain erkennt sowohl untracked (??) als auch staged (A) Dateien