---
description: Mettre à jour la section README CONCEPTS avec les dernières fonctionnalités et concepts Claude Code
argument-hint: [number of changelog versions to check, default 10]
---

# Workflow Changelog — README Concepts

Tu es un coordinateur pour le projet claude-code-best-practice. Ta mission consiste à lancer deux agents de recherche en parallèle, attendre leurs résultats, fusionner les constats et présenter un rapport unifié sur la dérive de la **section README CONCEPTS** (`README.md`).

**Versions à vérifier :** `$ARGUMENTS` (par défaut : 10 si vide ou non numérique)

Il s’agit d’un workflow **lire puis rapporter**. Lance les agents, fusionne les résultats et produis un rapport. N’agis que si l’utilisateur approuve.

---

## Phase 0 : lancer les deux agents en parallèle

**Immédiatement**, lance les deux agents avec l’outil Task **dans le même message** (lancement parallèle) :

### Agent 1 : workflow-concepts-agent

Lance avec `subagent_type: "workflow-concepts-agent"`. Donne-lui ce prompt :

> Research the claude-code-best-practice project for README CONCEPTS section drift. Check the last $ARGUMENTS versions (default: 10).
>
> Fetch these 3 external sources:
> 1. Claude Code Docs Index: https://code.claude.com/docs/en
> 2. Claude Code Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
> 3. Claude Code Features Overview: https://code.claude.com/docs/en/overview
>
> Then read the local README.md (specifically the CONCEPTS table), CLAUDE.md, and `reports/claude-global-vs-project-settings.md`. Analyze differences between what the official docs list as Claude Code concepts/features and what our README CONCEPTS table documents. Return a structured findings report covering missing concepts, changed concepts, deprecated concepts, URL accuracy, description accuracy, and badge accuracy.

### Agent 2 : claude-code-guide

Lance avec `subagent_type: "claude-code-guide"`. Donne-lui ce prompt :

> Research the latest Claude Code features and concepts. I need you to find the COMPLETE list of all Claude Code concepts/features that should be documented. For each, provide:
> 1. Official feature name
> 2. Official docs URL
> 3. File system location (e.g., `.claude/commands/`, `~/.claude/teams/`)
> 4. Brief description (one line)
> 5. When it was introduced (version/date if known)
>
> Specifically check for these potentially missing concepts:
> - **Worktrees** — git worktree isolation for parallel development
> - **Agent Teams** — multi-agent coordination
> - **Tasks** — persistent task lists across sessions
> - **Auto Memory** — Claude's self-written project learnings
> - **Keybindings** — custom keyboard shortcuts
> - **Remote Connections** — SSH, Docker, cloud development
> - **IDE Integration** — VS Code, JetBrains extensions
> - **Model Configuration** — model selection and routing
> - **GitHub Integration** — PR reviews, issue triage
> - Any other concept from recent Claude Code versions
>
> Be thorough — search the web, fetch docs, and provide concrete version numbers and details for everything you find.

Les deux agents s’exécutent indépendamment et retourneront leurs constats.

---

## Phase 0.5 : lire la checklist de vérification

**Pendant que les agents s’exécutent**, lis `changelog/best-practice/concepts/verification-checklist.md` si le fichier existe. Ce fichier contient les règles de vérification accumulées. S’il n’existe pas encore, saute cette étape — il sera créé en Phase 2.

---

## Phase 1 : lire les entrées précédentes du changelog

**Avant de fusionner les constats**, lis le fichier `changelog/best-practice/concepts/changelog.md` s’il existe, afin d’obtenir les entrées précédentes du changelog. Chaque entrée est séparée par `---`. Analyse les actions prioritaires des entrées précédentes pour pouvoir les comparer aux constats actuels. Cela permet d’identifier :
- **Éléments récurrents** — problèmes déjà apparus et encore non résolus
- **Éléments nouvellement résolus** — problèmes des exécutions précédentes désormais corrigés
- **Nouveaux éléments** — problèmes apparaissant pour la première fois dans cette exécution

Si le fichier n’existe pas encore, tous les éléments sont `NEW`.

---

## Phase 2 : fusionner les constats et générer le rapport

**Attends que les deux agents terminent.** Une fois que tu as :
- **Constats de workflow-concepts-agent** — analyse détaillée avec lectures de fichiers locaux, récupérations de docs externes et détection de dérive
- **Constats de claude-code-guide** — recherche indépendante sur les dernières fonctionnalités et concepts Claude Code

Croise les deux. L’agent dédié fournit l’analyse de dérive spécifique à CONCEPTS, tandis que claude-code-guide peut faire remonter des éléments qu’il a manqués (par exemple des changements très récents, des fonctionnalités non documentées ou du contexte issu de recherches web). Signale toute contradiction entre les deux pour résolution par l’utilisateur.

**Exécute la checklist de vérification (si elle existe) :** pour chaque règle dans `changelog/best-practice/concepts/verification-checklist.md`, effectue la vérification. Inclus une section **Verification Log** dans le rapport.

**Mets à jour la checklist si nécessaire :** si un constat révèle un nouveau type de dérive qu’aucune règle existante ne couvre, ajoute une nouvelle règle à `changelog/best-practice/concepts/verification-checklist.md`. Si le fichier n’existe pas, crée-le. La règle doit inclure : catégorie, quoi vérifier, niveau de profondeur, source de comparaison, date d’ajout et origine.

Compare aussi les constats actuels aux entrées précédentes du changelog (depuis la Phase 1). Pour chaque action prioritaire, marque-la comme :
- `NEW` — première apparition du problème
- `RECURRING` — déjà apparu lors d’une exécution précédente et encore non résolu (inclure la date de première apparition)
- `RESOLVED` — apparu lors d’une exécution précédente mais désormais corrigé (inclure la date de résolution)

Produis un rapport structuré avec ces sections :

1. **Missing Concepts** — Fonctionnalités/concepts présents dans la documentation officielle mais absents du tableau CONCEPTS, avec :
   - Nom officiel et URL de documentation
   - Valeur recommandée pour la colonne Location
   - Valeur recommandée pour la colonne Description — **badges et liens complémentaires uniquement ; pas de descriptions en prose** (la colonne Description est conventionnellement une colonne de liens, pas un résumé de fonctionnalité)
   - Ligne de tableau markdown exacte prête à coller
   - Version d’introduction (si connue)
2. **Changed Concepts** — Concepts dont le nom, l’URL, l’emplacement ou la description a changé
3. **Deprecated/Removed Concepts** — Concepts du tableau CONCEPTS qui ne figurent plus dans la documentation officielle
4. **URL Accuracy** — Vérification URL par concept
5. **Description Accuracy** — Vérification description/emplacement par concept
6. **Badge Accuracy** — Vérification des liens de badges et recommandations de badges manquants
7. **claude-code-guide Agent Findings** — Informations uniques de l’agent non capturées par l’agent dédié. N’inclus que les constats qui ajoutent une nouvelle information. Signale les contradictions.

Termine par un tableau récapitulatif priorisé **Action Items** :

```text
Priority Actions:
#  | Type                | Action                                     | Status
1  | Missing Concept     | Add <concept> row to CONCEPTS table         | NEW
2  | Changed URL         | Update <concept> docs link                  | NEW
3  | Changed Description | Update <concept> description                | RECURRING (first seen: <date>)
4  | Deprecated Concept  | Remove <concept> row from CONCEPTS table    | NEW
5  | Broken Badge        | Fix badge link for <concept>                | NEW
```

Inclus aussi une section **Resolved Since Last Run** listant les éléments de l’exécution précédente qui ne sont plus des problèmes.

---

## Phase 2.5 : ajouter le résumé au changelog

**Cette phase est OBLIGATOIRE — exécute-la toujours avant de présenter le rapport à l’utilisateur.**

Lis le fichier `changelog/best-practice/concepts/changelog.md` existant, puis **ajoute** (ne remplace PAS) une nouvelle entrée à la fin. Si le fichier n’existe pas, crée-le avec un tableau Status Legend puis la première entrée. Le format de l’entrée doit être exactement :

```markdown
---

## [<YYYY-MM-DD HH:MM AM/PM PKT>] Claude Code v<VERSION>

| # | Priority | Type | Action | Status |
|---|----------|------|--------|--------|
| 1 | HIGH/MED/LOW | <type> | <action description> | <status> |
| ... | ... | ... | ... | ... |
```

**Format de statut — DOIT utiliser l’un de ces trois formats :**
- `COMPLETE (reason)` — l’action a été réalisée et résolue avec succès
- `INVALID (reason)` — le constat était incorrect, non applicable ou intentionnel
- `ON HOLD (reason)` — action différée, en attente d’une dépendance externe ou d’une décision utilisateur

Le `(reason)` est obligatoire et doit expliquer brièvement ce qui a été fait ou pourquoi.

**Règles d’ajout :**
- Toujours ajouter — ne jamais écraser ou remplacer les entrées précédentes
- La date et l’heure correspondent à l’exécution de la commande en Pakistan Standard Time (PKT, UTC+5) ; obtiens-les avec `TZ=Asia/Karachi date "+%Y-%m-%d %I:%M %p PKT"`. La version vient des constats de l’agent
- Chaque entrée est séparée par `---`
- **Inclure uniquement les éléments de priorité HIGH, MEDIUM ou LOW** — omettre les éléments de priorité NONE

---

## Phase 2.6 : mettre à jour le badge Last Updated

**Cette phase est OBLIGATOIRE — exécute-la toujours immédiatement après la Phase 2.5, avant de présenter le rapport.**

Mets à jour le badge "Last Updated" en haut de `README.md` (ligne 3). Exécute `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"` pour obtenir l’heure, encode-la pour URL (espaces en `%20`, virgules en `%2C`) et remplace la portion date du badge.

**Ne journalise PAS les mises à jour de badge comme action items dans le changelog ou le rapport.**

---

## Phase 2.7 : valider toutes les URLs CONCEPTS

**Cette phase est OBLIGATOIRE — exécute-la toujours après la Phase 2.6, avant de présenter le rapport.**

Pour chaque concept du tableau CONCEPTS :

1. **URLs de docs externes** (par exemple `https://code.claude.com/docs/en/skills`) : récupérer chaque URL avec WebFetch et vérifier qu’elle retourne une page valide. Signaler tout lien mort ou déplacé.
2. **Liens de badges locaux** (par exemple `best-practice/claude-commands.md`) : vérifier que le fichier existe avec l’outil Read. Signaler tout lien cassé.
3. **Liens de badges d’implémentation** (par exemple `.claude/commands/`) : vérifier que le chemin existe.

Inclus un **URL Validation Log** dans le rapport :

```text
URL Validation Log:
#  | Concept     | URL Type  | URL                                           | Status | Notes
1  | Commands    | External  | https://code.claude.com/docs/en/skills         | OK     |
2  | Commands    | Badge     | best-practice/claude-commands.md               | OK     |
3  | Sub-Agents  | External  | https://code.claude.com/docs/en/sub-agents     | OK     |
...
```

**Si des URLs sont cassées**, ajoute-les comme action items de priorité HIGH.

---

## Phase 3 : proposer d’agir

Après avoir présenté le rapport (et confirmé que le changelog a été mis à jour), demande à l’utilisateur :

1. **Execute all actions** — Ajouter les concepts manquants, mettre à jour ceux qui ont changé, supprimer les dépréciés
2. **Execute specific actions** — L’utilisateur choisit les numéros à exécuter
3. **Just save the report** — Aucun changement

Pendant l’exécution :
- **Concepts manquants** : ajouter une nouvelle ligne au tableau CONCEPTS dans `README.md` en suivant le format existant :
  ```markdown
  | [**Name**](docs-url) | `location` | [![Best Practice](!/tags/best-practice.svg)](...) [![Implemented](!/tags/implemented.svg)](...) [Supplementary Link](...) |
  ```
  La troisième colonne contient **badges et liens uniquement — jamais de prose**. Ajouter les badges (best-practice, implemented) seulement si les fichiers correspondants existent. Si aucun badge ou lien ne s’applique, laisser la cellule vide (simplement `|  |`).
- **Concepts modifiés** : mettre à jour les colonnes spécifiques qui ont changé
- **Concepts dépréciés** : confirmer avec l’utilisateur avant de supprimer des lignes
- **URLs cassées** : corriger l’URL vers la version valide actuelle
- **Corrections de badges** : mettre à jour les liens de badges vers les bons chemins de fichiers
- Maintenir l’ordre alphabétique ou logique cohérent avec le tableau existant
- Après toutes les actions, revérifier la cohérence du tableau CONCEPTS

---

## Règles critiques

1. **Lancer les DEUX agents en parallèle** dans un seul message — jamais séquentiellement
2. **Attendre les deux agents** avant de générer le rapport
3. **Ne jamais deviner** versions, URLs ou dates — utiliser les données des agents
4. **Les concepts manquants sont PRIORITAIRES** — le tableau CONCEPTS est la première chose que voient les développeurs
5. **Vérifier chaque URL** — les liens cassés dégradent la confiance dans tout le projet
6. **Ne pas auto-exécuter** — toujours présenter le rapport d’abord
7. **TOUJOURS ajouter au changelog** — la Phase 2.5 est obligatoire. Ne jamais la sauter. Ne jamais écraser les entrées précédentes.
8. **Comparer avec les exécutions précédentes** — lire les entrées précédentes du changelog et marquer chaque action item comme NEW, RECURRING ou RESOLVED.
9. **Exécuter la checklist de vérification si elle existe** — lire verification-checklist.md et exécuter chaque règle. Créer le fichier s’il n’existe pas et que des constats justifient des règles persistantes.
10. **TOUJOURS mettre à jour le badge Last Updated** — la Phase 2.6 est obligatoire.
11. **TOUJOURS valider toutes les URLs CONCEPTS** — la Phase 2.7 est obligatoire. Les URLs cassées sont prioritaires HIGH.
12. **Fournir des lignes prêtes à coller** — pour les concepts manquants, inclure la ligne markdown exacte afin que l’exécution soit copier-coller.
13. **Respecter le format de tableau existant** — faire correspondre la structure de colonnes, le motif de badges et le style de liens des lignes existantes.
14. **La colonne Description sert aux badges et liens uniquement** — jamais de prose. La troisième colonne du tableau CONCEPTS (y compris le sous-tableau Hot) contient badges (best-practice, implemented, beta) et liens complémentaires (docs, articles de blog, rapports liés). Ne jamais écrire une description en prose de ce que fait une fonctionnalité — le nom de fonctionnalité pointe vers la documentation officielle, où l’explication appartient. Si une ligne n’a ni badge ni lien, laisse la cellule vide.
