Zions-store/project-ledger

Copyright (C) 2026 ZionXiaoxiSuOGLocGo SPDX-Lizenzkennung: GPL-3.0-or-later

project-docs

Erstellt und pflegt ein dreiteiliges Projektwissenssystem. Unterstützt alle von project-onboard erkannten Projekttypen – wählt automatisch die richtige Vorlage basierend auf dem Projekttyp aus.

Dreiteiliges Dokumentsystem

Datei	Zweck	Aktualisierungshäufigkeit
AGENTS.md	Projektübersicht: Identität, Verzeichnisstruktur, Klassenarchitektur, Einstiegspunkte, Abhängigkeiten, Notizen	Pro Meilenstein (~3-5 neue Dateien/Klassen)
PROJECT_STATE.md	Lebendes Dokument: vollständiges Klassen-/Quellspektrum (mit Parametern), Konfiguration, Modulzuordnung, Systemabläufe, Erledigt-/Aufgabenliste	Bei jedem Sitzungsende
DEVLOG.md	Entwicklungsprotokoll: Zeitleisten-Einträge – was wurde gemacht, warum, was wurde gelernt	Pro Tag oder pro Funktionsmeilenstein

Siehe maintenance-spec.md für detaillierte Regeln zu Aktualisierungsauslösern, Inhaltsgrenzen und Konsistenzprüfungen.

Vorlagenauswahl

Die Vorlagen folgen demselben Auto-Discovery-Muster wie die project-onboard-Regelsätze. Der Skill versucht, templates/<type>/PROJECT_STATE.md.tmpl zu laden, wobei <type> der kleingeschriebene Wert des Typs aus den Basisinformationen von AGENTS.md ist. Wenn keine typspezifische Vorlage existiert, wird auf templates/PROJECT_STATE.md.tmpl zurückgegriffen.

templates/<type>/PROJECT_STATE.md.tmpl existiert? → verwenden
                                             nein → templates/PROJECT_STATE.md.tmpl (generischer Fallback)

Hinzufügen von Unterstützung für eine neue Engine oder ein neues Framework: Erstellen Sie templates/<type>/PROJECT_STATE.md.tmpl. Keine Codeänderungen erforderlich – der Skill entdeckt sie automatisch.

Alle Typen teilen sich templates/DEVLOG.md.tmpl (projekttyp-unabhängig).

AGENTS.md → PROJECT_STATE.md Feldzuordnung

Beim Vorausfüllen von PROJECT_STATE.md aus Daten von AGENTS.md verwenden Sie diese Zuordnung:

AGENTS.md-Abschnitt	AGENTS.md-Feld	STATE-Vorlagenabschnitt	STATE-Platzhalter
Basisinformationen	Typ, Sprache, Framework/Engine, Wichtige Abhängigkeiten	§1 Projektidentität	{{PROJECT_TYPE}}, {{LANGUAGE}}, {{FRAMEWORK}}, {{KEY_DEPENDENCIES}}
Basisinformationen	Engine (für Spielprojekte)	§1 Projektidentität	{{ENGINE_VERSION}}
Verzeichnisstruktur	Verzeichnisse und Beschreibungen	§2 Verzeichnisstruktur	{{DIRECTORY_TREE}} (generisch) oder Source/{{MODULE_NAME}}/... (UE)
Kernarchitektur	Wichtige Dateien/Klassen und Rollen	§3 Quell-/Skriptspektrum	{{CLASS_NAME}}, {{RESPONSIBILITY}}, {{FILE_NAME}}
Abhängigkeiten	Paketzusammenfassung	§4 Konfiguration / §7 Abhängigkeiten	{{CONFIG_KEY}}, {{DEP_NAME}} (kontextabhängig)
Erstellen & Ausführen	Build-/Testkommandos	§9 Erstellen & Ausführen	{{BUILD_CMD}}, {{RUN_CMD}}, {{TEST_CMD}}
Einstiegspunkte	Startdatei/-szene und Rolle	§1 Projektidentität (Modul)	{{MODULE_NAME}}

Bei nicht-englischer Ausgabe: Übersetzen Sie Abschnittsüberschriften, Bezeichnungen und Platzhalterbeschreibungen, aber lassen Sie die {{PLATZHALTER}}-Markierungen intakt.

Wann dieser Skill verwendet werden sollte

• Benutzer sagt „Projektdokumente initialisieren“ / „建立文档体系“ / „project-docs“
• Ein neues Projekt benötigt PROJECT_STATE.md und DEVLOG.md
• Ein bestehendes Projekt hat AGENTS.md, aber die anderen beiden fehlen
• Benutzer bittet darum, den Projektstatus nach einer Sitzung zu aktualisieren

Arbeitsablauf

1. Initialisieren (neues Projekt / fehlende Dokumente)

0. Fragen Sie den Benutzer, in welcher Sprache die Dokumente generiert werden sollen. Standardmäßig Englisch, wenn der Benutzer überspringt oder „ist mir egal“ sagt. Jede Sprache, die das LLM ausgeben kann, wird unterstützt – der Agent übernimmt die Übersetzung zum Zeitpunkt der Generierung:

   „In welcher Sprache sollen die Projektdokumente verfasst werden? Standard: Englisch. Jede Sprache, die das LLM ausgeben kann, wird unterstützt.“

1. Überprüfen, ob AGENTS.md existiert.

   • Wenn nicht: Bieten Sie an, zuerst den Skill project-onboard auszuführen, um AGENTS.md zu generieren. Hier anhalten.
   • Wenn ja: Lesen Sie AGENTS.md und extrahieren Sie:
     • Projektname
     • Typ (aus den Basisinformationen – z. B. „unreal“, „unity“, „nodejs“, „python“)
     • Kernarchitektur (Klassen, Dateien, Rollen)

2. Vorlage erkennen: Basierend auf dem extrahierten Typ (kleingeschrieben) versuchen, eine typspezifische Vorlage zu laden. Wenn keine Übereinstimmung gefunden wird, auf die generische Vorlage zurückfallen:

   • Zuerst versuchen templates/<type>/PROJECT_STATE.md.tmpl
   • Wenn diese Datei nicht existiert, templates/PROJECT_STATE.md.tmpl (generisch) verwenden

3. PROJECT_STATE.md aus der ausgewählten Vorlage generieren:

   • Die Abschnitte §1-§3 aus den Daten von AGENTS.md mithilfe der obigen Feldzuordnungstabelle vorausfüllen.
   • Die restlichen Abschnitte mit ihrer Platzhalterstruktur für zukünftige Aktualisierungen belassen.

4. DEVLOG.md aus templates/DEVLOG.md.tmpl generieren:

   • Projektnamen eintragen.
   • Die Eintragsvorlage für den ersten Entwicklungsprotokolleintrag bereit lassen.

5. Folgenden Block oben in AGENTS.md einfügen, direkt nach der Überschriftszeile # Projektname (aber vor dem restlichen Inhalt):

   ## Dies zuerst lesen
   
   1. Lesen Sie `PROJECT_STATE.md` – aktueller Aufgabenstatus und zu erledigende Punkte (§10)
   2. Lesen Sie `DEVLOG.md` – letzter Entwicklungsverlauf
   
   ---
   

6. Berichten, was erstellt wurde, welche Vorlage verwendet wurde und in welcher Sprache.

2. Aktualisieren (bestehende Dokumente)

1. Lesen Sie PROJECT_STATE.md → identifizieren Sie die Aufgabenliste in §10
2. Fragen Sie den Benutzer, was abgeschlossen wurde / was sich geändert hat
3. Aktualisieren Sie die betroffenen Abschnitte:
   • §1-§2: wenn sich die Projektidentität oder Verzeichnisstruktur geändert hat
   • §3: neue Klassen, Dateien oder wichtige Mitglieder
   • §4: Konfigurationsänderungen (Blueprint-Eigenschaften, Prefab-Einstellungen oder generische Konfiguration)
   • §5: Eingabebindungen, Aktionszuordnungen oder Modul-/Paketänderungen
   • §6: Systemlogik, Architekturfluss oder Änderungen an Spielsystemen
   • §7: Szenen-/Levelkonfiguration oder Änderungen an externen Diensten
   • §8: Änderungen an numerischen Parametern
   • §9: Build-Probleme, neue Kompilierungsfehler oder Befehlsänderungen
   • §10: immer aktualisieren – Erledigt-Liste, Aufgabenliste, bekannte Probleme
4. Eintrag an DEVLOG.md anhängen (gemäß maintenance-spec.md-Format)
5. Wenn sich die Architektur geändert hat (neue Klassen, Plugins, Verzeichnisse) → AGENTS.md aktualisieren

3. Konsistenzprüfung

Nach jeder Aktualisierung überprüfen:

• Keine überlappenden Daten zwischen AGENTS.md und PROJECT_STATE.md (Architekturüberblick vs. Parameterdetails)
• Alle Einträge der Verzeichnisstruktur in AGENTS.md haben Gegenstücke in PROJECT_STATE.md
• Parameterwerte in PROJECT_STATE.md §8 stimmen mit den tatsächlichen Quellstandards überein (z. B. .h-Standards, Konfigurationsdateiwerte, BP CDO-Überschreibungen)
• Die Aufgabenliste in PROJECT_STATE.md §10 widerspricht nicht dem letzten Eintrag in DEVLOG.md (wenn DEVLOG „erledigt“ sagt, sollte STATE dies widerspiegeln)
• Keine doppelten Informationen in den drei Dokumenten (eine Tatsache = ein Ort)

Vorlagen

Vorlagen werden automatisch nach Projekttyp erkannt – keine festcodierte Zuordnungstabelle. Das Verzeichnis spiegelt die Referenzstruktur von project-onboard wider:

templates/
├── DEVLOG.md.tmpl              ← Alle Typen (generisch)
├── PROJECT_STATE.md.tmpl       ← Fallback (generisch)
├── unreal/PROJECT_STATE.md.tmpl     ← Unreal Engine
└── unity/PROJECT_STATE.md.tmpl      ← Unity

templates/<type>/PROJECT_STATE.md.tmpl-Dateien sind optional. Der Skill versucht, eine zu laden, die dem AGENTS.md-Typ entspricht; wenn keine vorhanden ist, wird die generische Vorlage im Stammverzeichnis verwendet.

Hinzufügen eines neuen Typs: Erstellen Sie templates/<type>/PROJECT_STATE.md.tmpl mit typspezifischen Abschnitten. Der Skill entdeckt sie beim nächsten Lauf – null Codeänderungen.

Regeln

• Vorhandene Dateien niemals überschreiben. Wenn ein Dokument existiert, aktualisieren Sie es direkt.
• Inhaltsgrenzen respektieren: AGENTS.md = Architekturüberblick. PROJECT_STATE.md = Parameterdetails + Status. DEVLOG.md = Zeitleisten-Erzählung.
• Wartungsspezifikation: Siehe maintenance-spec.md für genaue Aktualisierungsauslöser, Inhaltsgrenzen und verbotene Praktiken.
• Projektspezifische Pfade/Klassennamen in STATE/DEVLOG sind zu erwarten – dies sind Projektdokumente, keine wiederverwendbaren Handbücher.