Zions-store/project-ledger

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

project-docs

Crée et maintient un système de connaissance projet composé de trois documents. Prend en charge tous les types de projet détectés par project-onboard — sélectionne automatiquement le modèle approprié en fonction du type de votre projet.

Système à trois documents

Fichier	Objectif	Fréquence de mise à jour
AGENTS.md	Vue d'ensemble du projet : identité, structure des répertoires, architecture des classes, points d'entrée, dépendances, notes	Par jalon (~3-5 nouveaux fichiers/classes)
PROJECT_STATE.md	Document vivant : spectre complet des classes/sources (avec paramètres), configuration, carte des modules, flux système, liste des tâches accomplies/à faire	À chaque fin de session
DEVLOG.md	Journal de développement : entrées chronologiques — ce qui a été fait, pourquoi, ce qui a été appris	Par jour ou par jalon de fonctionnalité

Voir maintenance-spec.md pour les règles détaillées sur les déclencheurs de mise à jour, les limites de contenu et les vérifications de cohérence.

Sélection du modèle

Les modèles suivent le même motif de découverte automatique que les packs de règles de project-onboard. Le skill tente de charger templates/<type>/PROJECT_STATE.md.tmpl où <type> est la valeur Type (en minuscules) des Informations de base dans AGENTS.md. Si aucun modèle spécifique au type n'existe, il utilise le modèle générique templates/PROJECT_STATE.md.tmpl.

templates/<type>/PROJECT_STATE.md.tmpl existe ? → l'utiliser
                                             non → utiliser templates/PROJECT_STATE.md.tmpl (générique de secours)

Ajouter la prise en charge d'un nouveau moteur ou framework : créez templates/<type>/PROJECT_STATE.md.tmpl. Aucune modification de code nécessaire — le skill le découvre automatiquement.

Tous les types partagent templates/DEVLOG.md.tmpl (indépendant du type de projet).

Mappage des champs AGENTS.md → PROJECT_STATE.md

Lors du pré-remplissage de PROJECT_STATE.md à partir des données de AGENTS.md, utilisez ce mappage :

Section AGENTS.md	Champ AGENTS.md	Section du modèle STATE	Placeholder STATE
Informations de base	Type, Langage, Framework/Moteur, Dépendances clés	§1 Identité du projet	{{PROJECT_TYPE}}, {{LANGUAGE}}, {{FRAMEWORK}}, {{KEY_DEPENDENCIES}}
Informations de base	Moteur (pour les projets de jeux)	§1 Identité du projet	{{ENGINE_VERSION}}
Structure des répertoires	Répertoires et descriptions	§2 Structure des répertoires	{{DIRECTORY_TREE}} (générique) ou Source/{{MODULE_NAME}}/... (UE)
Architecture principale	Fichiers/classes clés et rôles	§3 Spectre source/script	{{CLASS_NAME}}, {{RESPONSIBILITY}}, {{FILE_NAME}}
Dépendances	Résumé des packages	§4 Configuration / §7 Dépendances	{{CONFIG_KEY}}, {{DEP_NAME}} (selon le contexte)
Construction & Exécution	Commandes de construction/test	§9 Construction & Exécution	{{BUILD_CMD}}, {{RUN_CMD}}, {{TEST_CMD}}
Points d'entrée	Fichier/scène de démarrage et rôle	§1 Identité du projet (Module)	{{MODULE_NAME}}

Pour les sorties non anglaises : traduisez les en-têtes de section, les étiquettes et les descriptions des placeholders, mais conservez les marqueurs {{PLACEHOLDER}} intacts.

Quand utiliser ce skill

• L'utilisateur dit "init project docs" / "建立文档体系" / "project-docs"
• Un nouveau projet a besoin de PROJECT_STATE.md et DEVLOG.md
• Un projet existant a AGENTS.md mais les deux autres fichiers manquent
• L'utilisateur demande de mettre à jour l'état du projet après une session

Flux de travail

1. Initialisation (nouveau projet / documents manquants)

0. Demandez à l'utilisateur dans quelle langue générer les documents. Par défaut, anglais s'il saute ou dit "Je m'en fiche". Toute langue que le LLM peut produire est prise en charge — l'agent gère la traduction au moment de la génération :

   "Dans quelle langue les documents du projet doivent-ils être rédigés ? Par défaut : anglais. Toute langue que le LLM peut produire est prise en charge."

1. Vérifiez si AGENTS.md existe.

   • Si non : Proposez d'exécuter d'abord le skill project-onboard pour générer AGENTS.md. Arrêtez-vous ici.
   • Si oui : Lisez AGENTS.md et extrayez :
     • Nom du projet
     • Type (à partir des Informations de base — par exemple, "unreal", "unity", "nodejs", "python")
     • Architecture principale (classes, fichiers, rôles)

2. Détection du modèle : En fonction du Type extrait (en minuscules), essayez de charger un modèle spécifique au type. Si aucune correspondance, utilisez le modèle générique :

   • Essayez d'abord templates/<type>/PROJECT_STATE.md.tmpl
   • Si ce fichier n'existe pas, utilisez templates/PROJECT_STATE.md.tmpl (générique)

3. Générez PROJECT_STATE.md à partir du modèle sélectionné :

   • Pré-remplissez les §1-§3 à partir des données de AGENTS.md en utilisant le tableau de mappage des champs ci-dessus.
   • Laissez les sections restantes avec leur structure de placeholder pour les futures mises à jour.

4. Générez DEVLOG.md à partir de templates/DEVLOG.md.tmpl :

   • Renseignez le nom du projet.
   • Laissez le modèle d'entrée prêt pour la première entrée du journal de développement.

5. Ajoutez le bloc suivant au début de AGENTS.md, directement après la ligne d'en-tête # Nom du projet (mais avant le reste du contenu) :

   ## Lisez d'abord ceci
   
   1. Lisez `PROJECT_STATE.md` — statut actuel des tâches et éléments à faire (§10)
   2. Lisez `DEVLOG.md` — historique de développement récent
   
   ---
   

6. Rapportez ce qui a été créé, quel modèle a été utilisé et dans quelle langue.

2. Mise à jour (documents existants)

1. Lisez PROJECT_STATE.md → identifiez la liste de tâches §10
2. Demandez à l'utilisateur ce qui a été accompli / ce qui a changé
3. Mettez à jour les sections concernées :
   • §1-§2 : si l'identité du projet ou la structure des répertoires a changé
   • §3 : nouvelles classes, fichiers ou membres clés
   • §4 : modifications de configuration (propriétés de blueprint, paramètres de prefab ou configuration générique)
   • §5 : liaisons d'entrée, mappages d'actions ou modifications de module/package
   • §6 : logique système, flux d'architecture ou modifications de système de jeu
   • §7 : configuration de scène/niveau ou modifications de services externes
   • §8 : toute modification de paramètre numérique
   • §9 : problèmes de construction, nouvelles erreurs de compilation ou modifications de commandes
   • §10 : toujours mettre à jour — liste des tâches accomplies, liste des tâches à faire, problèmes connus
4. Ajoutez une entrée dans DEVLOG.md (selon le format de maintenance-spec.md)
5. Si l'architecture a changé (nouvelles classes, plugins, répertoires) → mettez à jour AGENTS.md

3. Vérification de cohérence

Après toute mise à jour, vérifiez :

• Aucune donnée en double entre AGENTS.md et PROJECT_STATE.md (vue d'ensemble de l'architecture vs détails des paramètres)
• Les entrées de la structure des répertoires dans AGENTS.md ont toutes leurs homologues dans PROJECT_STATE.md
• Les valeurs des paramètres §8 dans PROJECT_STATE.md correspondent aux valeurs par défaut réelles des sources (par exemple, valeurs par défaut .h, valeurs de fichier de configuration, overrides BP CDO)
• La liste des tâches §10 dans PROJECT_STATE.md ne contredit pas la dernière entrée de DEVLOG.md (si DEVLOG dit "fait", STATE doit correspondre)
• Aucune information en double dans les trois documents (un fait = un emplacement)

Modèles

Les modèles sont découverts automatiquement par type de projet — pas de tableau de mappage codé en dur. Le répertoire reflète la structure de référence de project-onboard :

templates/
├── DEVLOG.md.tmpl              ← Tous les types (générique)
├── PROJECT_STATE.md.tmpl       ← Secours (générique)
├── unreal/PROJECT_STATE.md.tmpl     ← Unreal Engine
└── unity/PROJECT_STATE.md.tmpl      ← Unity

Les fichiers templates/<type>/PROJECT_STATE.md.tmpl sont facultatifs. Le skill essaie d'en charger un correspondant au Type de AGENTS.md ; s'il est absent, il utilise le modèle générique racine.

Ajouter un nouveau type : créez templates/<type>/PROJECT_STATE.md.tmpl avec des sections spécifiques au type. Le skill le découvre lors de la prochaine exécution — zéro modification de code.

Règles

• Ne jamais écraser les fichiers existants. Si un document existe, mettez-le à jour sur place.
• Respectez les limites de contenu : AGENTS.md = vue d'ensemble de l'architecture. PROJECT_STATE.md = détails des paramètres + statut. DEVLOG.md = récit chronologique.
• Spécifications de maintenance : Voir maintenance-spec.md pour les déclencheurs de mise à jour exacts, les limites de contenu et les pratiques interdites.
• Les chemins/noms de classe spécifiques au projet dans STATE/DEVLOG sont attendus — ce sont des documents de projet, pas des manuels réutilisables.