| 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
0b. Mehrere Specs konsolidieren
Wenn der User mehrere Specs auswählt, die zu einem Epic gehören:
- Alle gewählten Specs vollständig lesen
- Überschneidungen und Widersprüche identifizieren
- Gleiche Konzepte mit unterschiedlichen Details → zusammenführen
- Widersprüchliche Definitionen → dem User zur Klärung vorlegen
- Konsolidierte Zusammenfassung erstellen
- Alle Kernkomponenten aus allen Specs zusammentragen
- Einheitliches Datenmodell ableiten
- Gemeinsame Abhängigkeiten identifizieren
- 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.
- 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
- 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:
- Package-Struktur + Datenmodell
- Core-Logik / Services
- Subsysteme (einzeln, nach Abhängigkeit sortiert)
- UI / Scene
- 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:
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
