Levix-Digital/plan-memory

📐 Compétence Mémoire de Planification de Projet (plan-memory)

Chemins : <skills_root> est le dossier qui contient cette compétence (le parent du dossier de ce SKILL.md). Utilisez le chemin absolu réel lors de l'exécution des commandes.

La compétence plan-memory conserve des plans architecturaux, des feuilles de route stratégiques et des plans en plusieurs étapes à 100% complets et non compressés d'un projet, partagés par tous ceux qui y travaillent.

• Source de vérité : un fichier Markdown par plan dans le dépôt du projet, docs/plans/<plan_id>.md (frontmatter YAML + corps du plan). Les plans sont versionnés, révisés et fusionnés avec le code. Modifiez le dossier avec "plans_dir" dans le fichier .dev-cycle.json du projet.
• Index de recherche : une ChromaDB locale à ~/.ai-code-agent-memory/plan-memory/db (à remplacer par PLAN_MEMORY_DB), collection plan_index. Il est jetable : chaque commande le synchronise à partir des fichiers (par SHA-256), et rebuild_index (moteur) le recrée.
• Projet : résolu à partir du dépôt Git du répertoire courant (ou --dir) : project_name dans .dev-cycle.json, sinon le nom du dossier du dépôt, normalisé en kebab-case. --project le remplace.
• Niveaux : le backlog (docs/BACKLOG.md) capture le travail en secondes, sans découverte, regroupé sous des epics ; la feuille de route (docs/ROADMAP.md) ordonne les releases et leur assigne des éléments ; un plan est créé lorsque l'utilisateur promeut des éléments du backlog et contient la découverte et la planification (voir "Backlog" et "Feuille de route").
• Enveloppes Spec Kit : lorsque le projet utilise Spec Kit, un plan de fonctionnalité est une enveloppe (spec_dir) d'un dossier Spec Kit (specs/NNN-slug/) qui contient les détails ; la recherche, la détection de dérive et get_plan lisent les artefacts du dossier avec le plan (voir "Plans avec Spec Kit").
• Principe directeur : Zéro Compactage / Zéro Perte. Les plans sont conservés dans leur intégralité (diagrammes Mermaid, tableaux, étapes, formules, justifications) en tant que connaissance persistante pour chaque développeur et chaque session.

---

🏛️ Format du fichier de plan

---
plan_id: my_app_blueprint_v1_2_0_two_stage_search
project: my-app
title: Recherche en deux étapes avec reclassement local
kind: feature              # feature (par défaut) | bug
version: v1.2.0
status: in_progress        # draft | planned | active | in_progress | completed | superseded
author: Jane Doe           # git user.name du créateur
created_at: '2026-10-15T16:36:00'
updated_at: '2026-10-16T09:10:00'
session_id: 8abbc3bf-...   # conversation où le plan a été conçu (optionnel)
tags: [search, reranker]
supersedes: my_app_blueprint_v1_1_0_search
superseded_by: null
parent_plan_id: null
backlog_items: [FEAT-004]  # éléments du backlog que le plan livre (optionnel)
spec_dir: specs/004-reranker  # dossier Spec Kit avec les détails du plan (optionnel)
milestones:
- name: M1 Base d'exécution
  done: true
  done_at: '2026-10-15'
  by: Jane Doe
- name: M2 Reclasseur
  done: false
status_log:
- at: '2026-10-15T16:36:00'
  by: Jane Doe
  status: active
  note: Plan créé
---

# Titre du plan

...corps complet du plan en Markdown...

• Les scripts ne réécrivent que le frontmatter ; le corps est écrit une fois par save_plan (ou modifié à la main). Les changements de jalons et de statut produisent des diffs petits et lisibles.
• Le nom du fichier est l'ID du plan. Les champs de lignée (supersedes, superseded_by, parent_plan_id) référencent d'autres IDs de plan.
• Les scripts ne commitent jamais. L'agent commit les fichiers de plan avec le travail qu'ils décrivent (voir "Workflow d'équipe").

---

⚙️ Commandes

Tous les scripts sont dans <skills_root>/plan-memory/ et acceptent --dir <répertoire du projet> (par défaut : répertoire courant) et --project <nom>.

1. Sauvegarder / Mettre à jour un Plan avec Lignée (save_plan)

Écrit docs/plans/<plan_id>.md avec le plan complet, sans coupures ni résumés. Sauvegarder un ID existant met à jour le titre, le corps et les champs, en conservant l'auteur, la date de création et la progression des jalons. --supersedes marque l'ancien plan comme superseded. save_plan s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan \
  --title "Feuille de route intégrée : Python -> Rust, Routeur de modèle & Kit de modèle" \
  --file "chemin/vers/plan.md" \
  --version "v1.2.0" \
  --tags "roadmap,rust_refactor,model_router" \
  --milestones "Priorité 1,Priorité 2,Jalon 3" \
  --status "active" \
  --session-id "<session_id>" \
  --supersedes "<old_plan_id>"

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory save_plan [arguments] à la place. Options : --id (par défaut : slug <projet>_<titre>), --parent-id, --content au lieu de --file, --kind feature|bug, --backlog-items "BUG-001,FEAT-002" (lie les éléments, qui deviennent planned), --spec-dir specs/NNN-slug (le plan est l'enveloppe de ce dossier Spec Kit).

2. Suivi des Jalons et de la Progression (check_milestone)

check_milestone s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

# Progression et liste de contrôle du dernier plan actif (ou --id <plan_id>) :
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --list

# Marquer un jalon comme terminé (enregistre la date et l'auteur) :
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Priorité 1" --notes "Terminé via PR #319"

# Revenir un jalon à l'état en attente :
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Priorité 1" --uncheck

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory check_milestone [arguments] à la place. Le premier jalon terminé fait passer un plan active à in_progress ; le dernier le fait passer à completed.

3. Détecteur de Dérive Architecturale (detect_drift)

Compare toute proposition de mise en œuvre, tout problème ou toute nouvelle invite par rapport au plan actif : similarité sémantique, couverture et ordre des jalons, et les propres règles anti-patron du projet. detect_drift s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "Priorité 1 : construire l'orchestrateur ReAct natif en Rust, en remplaçant le Python LangGraph"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --file "chemin/vers/proposition.md" --strict   # code de sortie != 0 en cas de conflit

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory detect_drift [arguments] à la place.

Les règles anti-patron se trouvent dans la clé drift_rules du fichier .dev-cycle.json du projet (recherché à partir de --dir vers le haut). Sans règles, seuls la similarité et les jalons sont vérifiés.

"drift_rules": [
  { "tech": "langchain", "conflict_msg": "Le plan de référence supprime LangChain." },
  {
    "tech": "base de données parallèle",
    "negative_markers": ["source unique", "settings.db"],
    "proposal_allow": [],
    "conflict_msg": "La proposition suggère une base de données parallèle, violant la source de vérité unique."
  }
]

Une règle soulève un conflit lorsqu'un plan en vigueur (active / in_progress) mentionne tech avec un marqueur de rejet, et que la proposition mentionne tech sans une expression autorisée.

• negative_markers (optionnel) : mots qui marquent le rejet. Par défaut : remove, replace, without, forbidden, ... ainsi que leurs équivalents portugais, conservés tant que les plans existants ne sont pas encore traduits.
• proposal_allow (optionnel) : expressions qui rendent une mention acceptable. Par défaut : without <tech>, remove <tech>, replace <tech>, ... ainsi que leurs équivalents portugais.

4. Lister les Plans (list_plans)

list_plans s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans [--status active] [--kind bug]

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory list_plans [arguments] à la place.

5. Lire un Plan Complet (get_plan)

get_plan s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan --id "<plan_id>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan                  # dernier plan actif

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory get_plan [arguments] à la place.

6. Recherche Sémantique (search_plans)

search_plans s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory search_plans --query "comment implémenter le routeur de modèle dans le chat" [--limit 5] [--all-projects]

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory search_plans [arguments] à la place.

7. Mettre à Jour le Statut du Cycle de Vie (update_plan_status)

Définit le statut du plan, l'enregistre dans le journal des statuts et met à jour les éléments du backlog liés. update_plan_status s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory update_plan_status --id "<plan_id>" --status "completed" --notes "Priorité 1 et 2 livrées."

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory update_plan_status [arguments] à la place.

8. Exporter (export_plan)

Copie un plan ailleurs, au format JSON ou Markdown avec ou sans frontmatter. export_plan s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory export_plan --id "<plan_id>" --format json --output-dir "out/"

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory export_plan [arguments] à la place.

9. Reconstruire l'Index (rebuild_index)

rebuild_index s'exécute sur le moteur natif. Dans les shells sh (Linux, macOS, Git Bash) :

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory rebuild_index [--project <nom>] [--dir <chemin>]

Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory rebuild_index [arguments] à la place.

---

📥 Backlog (backlog)

Le premier niveau de planification : un fichier Markdown (backlog.file dans .dev-cycle.json, par défaut docs/BACKLOG.md), créé par le premier add à partir de templates/BACKLOG_TEMPLATE.md.

## Bugs | Fonctionnalités | Améliorations | Ajustements | Epics | Fermé

### BUG-001 : Le préréglage Frontier sélectionne un identifiant de modèle obsolète
- **Gravité** : haute              # bugs : critique | haute | moyenne | basse
- **Statut** : ouvert                # ouvert | planifié | en_cours (terminé | abandonné | doublon | remplacé sous Fermé)
- **Trouvé** : 2026-10-16, v0.45.0, PR #333
- **Plan** : -                     # identifiant du plan une fois promu
- **Description** : `/preset frontier` définit `claude-3-7-sonnet`, que le fournisseur peut rejeter.

Les fonctionnalités (FEAT-NNN), les améliorations (IMP-NNN) et les ajustements (ADJ-NNN) ont une Priorité (haute, moyenne, basse) au lieu de Gravité. Tout élément autre qu'un epic peut avoir - **Epic**: EPIC-NNN. Les Epics (EPIC-NNN, section ## Epics) regroupent les éléments du produit complet ; ils ont une Priorité, un Statut (ouvert jusqu'à fermeture), Trouvé et Description, pas de Plan, et ne sont jamais promus : ce sont leurs éléments qui le sont. validate avertit d'un epic ouvert dont tous les éléments sont fermés. Les IDs ne sont jamais réutilisés : les éléments fermés restent dans ## Fermé avec une note - **Fermé**: (date et pull request, raison, doublon de <ID>, ou remplacé par <ID>[, <ID>...]). Un élément est remplacé lorsqu'il est remplacé par des éléments différents et mieux définis (une idée divisée ou remodelée après sa création) ; un doublon est la même demande capturée deux fois.

backlog s'exécute sur le moteur natif : "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory backlog <commande> [arguments] dans les shells sh (Linux, macOS, Git Bash). Dans PowerShell, exécutez & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory backlog [arguments] à la place.

Tâche	Commande
Capturer	backlog add --type bug|feature|improvement|adjustment|epic --title "<t>" --description "<d>" [--severity S] [--priority P] [--epic EPIC-NNN] [--found-in "v1.2.0, PR #12"]
Capturer des tests manuels échoués	backlog add --from-failed --run vX.Y.Z-rc.N [--severity S]
Résumé (bugs avant tout nouveau travail en premier)	backlog summary [--json]
Lister, afficher	backlog list [--type T] [--status S] [--epic EPIC-NNN] [--all] [--json], backlog show <ID>
Modifier	backlog set <ID> [--title] [--description] [--severity] [--priority] [--status] [--plan] [--epic ID|-]
Promouvoir en plan	backlog promote <ID> [<ID> ...] [--title T] [--id PLAN_ID] [--version V] ou --into <PLAN_ID>
Fermer	backlog close <ID> [--ref "PR #12"], drop <ID> --reason R, duplicate <ID> --of <ID>, supersede <ID> --by <ID>[,<ID>...], reopen <ID>
Valider	backlog validate

• Capturer ne coûte rien : pas de découverte, pas de plan. L'utilisateur le fait avec la commande /backlog ; l'agent le fait pour les bugs qu'il trouve en dehors du périmètre actuel.
• La promotion crée un plan draft à partir de templates/BUG_PLAN_TEMPLATE.md (chaque élément un bug : reproduction, preuve et cause racine, conception du correctif, test de régression) ou templates/FEATURE_PLAN_TEMPLATE.md, avec les éléments copiés dans sa section Éléments du backlog, et lie les deux sens. La découverte est écrite dans ce plan ; il est à nouveau sauvegardé comme active, avec des jalons, pour approbation.
• Les éléments liés suivent leur plan : planned tant que le plan est draft ou active, in_progress lorsqu'il est en cours, fermé comme done lorsqu'il est terminé (check_milestone et update_plan_status sur le moteur).
• Le tri est la décision de l'utilisateur : l'agent ne promeut, n'abandonne ni ne réordonne jamais de son propre chef.
• Le script ne commit jamais et refuse de réécrire un fichier dont il ne peut pas lire la structure, de sorte que les modifications manuelles ne sont jamais perdues.

---

🗺️ Feuille de route (roadmap)

Les versions du produit dans l'ordre de livraison (roadmap.file dans .dev-cycle.json, par défaut docs/ROADMAP.md), créées par le premier add à partir de templates/ROADMAP_TEMPLATE.md.

# Feuille de route du projet (projet)

## v1.0.0 - Version initiale
**Statut :** planifié | en cours | livré | abandonné
**Date de livraison prévue :** 2026-10-30 (optionnelle, juste une note)
**Description :** La version initiale fournit...</p>`