| name | help |
| description | Affiche le sommaire du workflow et oriente vers le bon skill — quatre phases (décor, cadrage, implem, clôture), trois tracks (feature, refacto, tech) et leurs artifacts. À utiliser quand tu ne sais pas par où commencer ou quel skill correspond. |
| user_invocable | true |
| disable-model-invocation | true |
| allowed-tools | ["Read","Glob"] |
/help — Guide du workflow de développement
Schéma global du pipeline
PHASE 0 — POSER LE DÉCOR (une fois par projet, ou pivot)
┌────────┐
│ vision │──▶ docs/vision.md (problème, audience, valeur,
└────────┘ North Star, principes, anti-objectifs)
Lu par product-backlog puis feature-pitch.
┌────────────────┐
│ product-backlog│──▶ docs/product-backlog.md (domaines, capacités,
└────────────────┘ parcours, règles transverses, backlog priorisé MVP/V2/V3)
Lu par feature-pitch pour situer chaque feature.
┌───────┐
│ stack │──▶ docs/stack.md (langages, backend, frontend, données,
└───────┘ ops, CI — chaque techno prouvée par un fichier source)
Lu par feature-implem/refactor-implem/tech-implem/review.
PHASES 1 À 3 — CADRER, IMPLÉMENTER, CLÔTURER : une story emprunte UN SEUL des trois tracks.
La phase dit quand ; le track dit avec quelles skills. Dans chaque track ci-dessous :
les plans = phase 1, l'implem = phase 2, review → report → sync → commit = phase 3.
TRACK FEATURE (valeur utilisateur, structurante)
(optionnel : besoin flou)
┌───────────────────┐
│ feature-interview │┄┐
└─────────┬─────────┘ ┊ brief.md
▼ ▼
┌───────────────┐ ┌──────────────┐ ┌────────────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐
│ feature-pitch │──▶│ feature-plan │──▶│ feature-implem │──▶│ review │──▶│ report │──▶│ sync │──▶│ commit │
└───────┬───────┘ └───────┬──────┘ └────────┬───────┘ └────┬───┘ └────┬───┘ └───┬──┘ └────┬───┘
│ │ │ │ │ │ │
pitch.md plan.md code+migrations review.md report.md doc sync commit
+nouveaux tests +changelog +push
TRACK REFACTO (comportement figé, code restructuré)
┌───────────────┐ ┌─────────────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐
│ refactor-plan │──▶│ refactor-implem │──▶│ review │──▶│ report │──▶│ sync │──▶│ commit │
└───────┬───────┘ └────────┬────────┘ └────┬───┘ └────┬───┘ └───┬──┘ └────┬───┘
│ │ │ │ │ │
plan.md verrou tests review.md report.md doc sync commit
+ étapes +changelog +push
incrémentales
TRACK TECH (perf, résilience, observabilité, sécu — non user-facing)
┌───────────┐ ┌─────────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐
│ tech-plan │──▶│ tech-implem │──▶│ review │──▶│ report │──▶│ sync │──▶│ commit │
└─────┬─────┘ └──────┬──────┘ └────┬───┘ └────┬───┘ └───┬──┘ └────┬───┘
│ │ │ │ │ │
plan.md baseline review.md report.md doc sync commit
+ kill switch +changelog +push
+ étapes mesurées
UTILITAIRES (hors pipeline, à la demande)
┌─────────────────┐ ┌─────┐ ┌──────┐
│ test-scenario │ │ adr │ │ help │ ← tu y es
└─────────────────┘ └──┬──┘ └──────┘
Playwright MCP live │ ce sommaire
▼
docs/adr/NNNN-slug.md
(depuis pitch/plan/review/report
ou topic libre)
┌──────────────┐ ┌─────────┐ ┌──────────┐
│ doc-feature │ │ release │ │ estimate │
└──────┬───────┘ └────┬────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
docs/feature-map/ vX.Y.Z + estimate.md
NNN-slug/overview.md CHANGELOG.md (temps facturable
(rétro-doc à partir + tag annoté tout compris, en
du code livré) + GitHub rel. heures : réf. + IA)
Règle d'or : ne jamais passer à l'étape suivante sans validation explicite du user ("ok", "go", "validé", "c", etc.).
Convention dossiers docs/story/
Tous les artifacts vivent dans docs/story/ à plat, numérotés globalement puis taggés par type. Format : NNN-<f|r|t>-<slug>. Le numéro vient en premier pour que le tri lexicographique de ls corresponde à l'ordre chronologique.
| Tag | Type | Doc d'intention | Exemple |
|---|
f | Feature | pitch.md + plan.md | docs/story/042-f-checkout-express/ |
r | Refacto | plan.md | docs/story/043-r-extract-pricing/ |
t | Évolution tech | plan.md | docs/story/044-t-redis-cache/ |
Tous les tracks produisent un plan.md (cadrage technique exécutable). Le track feature a en amont un pitch.md (cadrage fonctionnel) qui formalise le problème utilisateur avant le plan.
Les numéros s'incrémentent globalement (042-f → 043-r → 044-t → 045-f…), ce qui permet de lire la timeline d'évolution du projet en listant simplement docs/story/.
Un format commun à tous les documents : brief.md, pitch.md, plan.md, review.md, report.md et estimate.md partagent un contrat de format unique (references/document-format.md). Chaque document sert un seul but, dans un seul registre — annoncé dans son en-tête : le brief et le pitch sont fonctionnels (aucun nom de classe, de service ou de framework), les plans et la review sont techniques, le report est factuel, l'estimation est économique. Les documents de décision (review, report, estimation) ouvrent sur leur ## Synthèse : on doit pouvoir ne lire qu'elle. Les trois plans partagent le même squelette de sections, quel que soit le track — leurs spécificités (caractérisation d'un refacto, kill switch d'un tech) sont des sections additionnelles. La timeline, elle, ne vit dans aucun .md : elle est dans le metadata.json de la story.
Les deux axes : phases et tracks
Le pipeline se lit sur deux axes qu'il ne faut pas confondre :
- La phase dit quand. Quatre phases, dans l'ordre : 0 poser le décor (une fois par projet), puis 1 cadrer, 2 implémenter, 3 clôturer — traversées par chaque story.
- Le track dit avec quelles skills. À phase égale, une feature, un refacto et une évolution technique n'appellent pas les mêmes skills. Le track se choisit à l'entrée de la phase 1 et ne change pas les phases traversées : la phase 3 est identique pour les trois.
Phase 0 — Poser le décor
Avant le premier track, en tout début de projet (ou lors d'un pivot), poser le décor une fois pour toutes : pourquoi ce produit existe, ce qu'on va construire, et sur quoi on marche. Les trois documents sont vivants (4 modes : Création / Enrichir / Éditer / Pivot, avec changelog) et vivent à la racine de docs/, pas dans une story.
| Skill | Rôle | Produit |
|---|
/vision | Atelier challengeur sur problème, audience, valeur, North Star, principes, anti-objectifs | docs/vision.md |
/product-backlog | Atelier fonctionnel : domaines → capacités → parcours → règles transverses → backlog MVP/V2/V3 | docs/product-backlog.md |
/stack | Scanne tous les manifestes (langages, backend, frontend, données, ops, CI), interroge pour combler les trous, prouve chaque techno par un fichier source | docs/stack.md |
Vision — pourquoi ce produit existe, pour qui, quelle valeur il crée, comment on mesure le succès, et ce qu'on refuse explicitement de faire. Lue par /product-backlog puis par /feature-pitch à chaque nouvelle feature pour challenger l'alignement (problème adressé, audience, principes, impact North Star). Pas de lancement à chaque feature : c'est un document fondateur, révisé seulement lors d'un pivot.
Product-backlog — le pont entre la stratégie (vision) et le cadrage feature par feature : carte des capacités fonctionnelles + backlog priorisé de features candidates. On le révise quand le périmètre évolue (nouvelle capacité, repriorisation, pivot). /feature-pitch le lit pour reprendre le pitch initial d'une ligne de backlog, ses capacités couvertes et ses dépendances. Facultatif (on peut aller direct vision → feature-pitch), mais recommandé dès qu'on a plus de 3-4 features pressenties.
Stack — sur quoi on marche, avant de cadrer la moindre évolution. Indispensable sur un legacy non documenté, utile sur un projet neuf dès que la stack se stabilise. Lu en priorité par les skills techniques (/feature-plan, /refactor-plan, /tech-plan, /review) pour décider sur des bases factuelles. Il constate l'existant — il ne justifie pas un choix (c'est le rôle d'/adr) ni ne décide d'une évolution (/tech-plan).
docs/stack.md est un document vivant (mêmes 4 modes que vision/backlog : Création / Enrichir / Éditer / Pivot, avec changelog). Il est lu en priorité par les tracks techniques (/feature-plan, /refactor-plan, /tech-plan, /review) pour décider sur des bases factuelles. Il constate l'existant — il ne justifie pas un choix (c'est le rôle d'/adr) ni ne décide d'une évolution (/tech-plan).
Choisir son track
| Question | Si oui → |
|---|
| Un utilisateur final ou un admin peut décrire ce qu'il voit de nouveau ? | Feature (f-) |
| Le comportement externe reste strictement identique (mêmes réponses, events, logs, timings) et on restructure juste le code ? | Refacto (r-) |
| Un observateur externe (test, monitoring, log consumer, autre service) peut détecter la différence, mais c'est pour mieux (plus rapide, plus résilient, plus observable, plus sûr) sans nouvelle valeur user ? | Tech (t-) |
| Moins de 3 fichiers, pas de migration, pas d'impact transverse ? | Fast |
Piège : un changement qui mélange les catégories. Règle : si tu ne peux pas scinder ton diff en commits distincts (le refacto pur, puis l'ajout de la brique tech, puis la feature qui s'en sert), tu as probablement mélangé deux tracks. Sépare.
Track feature — Valeur utilisateur
Pour tout changement qui introduit une nouvelle fonctionnalité ou modifie un comportement observable par l'utilisateur.
| Phase | Skill | Rôle | Produit |
|---|
| 1 | /feature-interview | (optionnel) Découvrir un besoin flou par interview avant de pouvoir le pitcher | docs/story/NNN-f-slug/brief.md |
| 1 | /feature-pitch | Cadrer et challenger une fonctionnalité (lit le brief.md amont s'il existe) | docs/story/NNN-f-slug/pitch.md |
| 1 | /feature-plan | Concevoir la solution technique à partir du pitch | docs/story/NNN-f-slug/plan.md |
| 2 | /feature-implem | Implémenter sous-tâche par sous-tâche avec QA continue | Code + migrations + tests |
| 3 | /review | Code review (sécu, perf, qualité, conformité plan) | docs/story/NNN-f-slug/review.md |
| 3 | /report | Documenter ce qui a été fait vs ce qui était prévu | docs/story/NNN-f-slug/report.md |
| 3 | /sync | Réaligner pitch et plan avec la réalité du code | Mise à jour pitch.md + plan.md |
| 3 | /commit | En dernier : embarque code + report + docs réalignées, Conventional Commits + push | Commit |
Track refacto — Comportement figé, code restructuré
Pour restructurer du code sans toucher au comportement externe (dette, couplage, préparer une feature à venir, extraire un service, décomposer une god class…).
Principe : comportement externe strictement préservé, verrou tests de caractérisation AVANT de toucher, exécution incrémentale réversible.
| Phase | Skill | Rôle | Produit |
|---|
| 1 | /refactor-plan | Cadrer un refacto (motivation, cible, caractérisation, étapes) | docs/story/NNN-r-slug/plan.md |
| 2 | /refactor-implem | Exécuter : verrou tests puis étapes incrémentales, non-régression | Code restructuré + tests |
| 3 | /review | Code review focus non-régression | docs/story/NNN-r-slug/review.md |
| 3 | /report | Documenter l'exécution vs le plan | docs/story/NNN-r-slug/report.md |
| 3 | /sync | Réaligner le plan si la stratégie a dévié | Mise à jour plan.md |
| 3 | /commit | En dernier : embarque tout, souvent un commit par étape | Commits |
Track tech — Perf, résilience, observabilité, sécu (non user-facing)
Pour ajouter ou modifier une brique technique observable (latence, taux d'erreur, format de log, timing) qui n'apporte pas de nouvelle valeur utilisateur fonctionnelle : cache, retry, circuit breaker, queue async, logs structurés, index SQL, health check, CSP, bump de CVE…
Principe : métrique cible chiffrée obligatoire, baseline mesurée AVANT toute modif, kill switch activable, étapes incrémentales avec mesure après chaque.
| Phase | Skill | Rôle | Produit |
|---|
| 1 | /tech-plan | Cadrer l'évolution (problème, brique, métriques cibles, rollback) | docs/story/NNN-t-slug/plan.md |
| 2 | /tech-implem | Exécuter : baseline, kill switch, étapes mesurées, validation | Code + config + observabilité |
| 3 | /review | Code review (kill switch, compatibilité, non-régression) | docs/story/NNN-t-slug/review.md |
| 3 | /report | Documenter les critères atteints / non atteints vs le plan | docs/story/NNN-t-slug/report.md |
| 3 | /sync | Réaligner le plan si la stratégie a dévié | Mise à jour plan.md |
| 3 | /commit | En dernier : embarque code + report + docs réalignées, + push | Commits |
Track fast — Bugfixes et petits changements
Conditions (toutes requises) :
- Moins de 3 fichiers modifiés
- Pas de changement de schéma (migration) ni de nouveau service/entité
- Pas d'impact transverse (multi-channel, multi-thème, API publique…)
Processus :
coder → QA du stack → tests ciblés → /review (optionnel) → /commit
En cas de doute → partir sur le track approprié (feature, refacto ou tech). Il est toujours possible de basculer du structurant vers le fast si l'analyse révèle que c'est trivial.
Phase 3 — Clôturer (/review, /report, /sync, /commit)
Les trois tracks (feature, refacto, tech) partagent les mêmes étapes de clôture après l'implémentation, dans cet ordre. Ce sont des skills communs : seuls le contenu et le ton des artifacts changent selon le track. Le /commit vient en dernier : review, report et sync travaillent tous sur le diff du working tree (non committé), puis le commit embarque d'un coup le code, le report.md et les documents réalignés.
/report — Documenter la livraison réelle
Crée report.md dans le dossier de track (docs/story/NNN-<f|r|t>-slug/). Documente ce qui a été fait vs ce qui était prévu : écart entre intention (pitch.md/plan.md) et exécution réelle — ajouts non prévus, choix qui ont dévié, dette laissée, métriques effectivement obtenues (en track tech : valeur cible vs mesurée, kill switch armé ou non). C'est la mémoire factuelle de la livraison, utile pour les rétros, l'onboarding futur et la traçabilité produit.
/sync — Réaligner la doc d'intention avec le code
Met à jour pitch.md ou plan.md quand l'implémentation a obligé à dévier (modèle de données ajusté, route renommée, lib remplacée, étape rajoutée…). Le but : que la doc d'intention se lise comme si elle avait été écrite correctement dès le départ, sans cicatrice de l'historique de décisions. Une phase finale propage aussi les écarts vers les documents de phase 0 quand ils existent (modes Enrichir/Éditer, toujours validés) : stack.md gagne une dépendance/service détecté dans le diff, product-backlog.md marque la feature livrée, et vision.md évolue avec le produit — une feature qui étend le périmètre enrichit la vision, une feature qui contredit un anti-objectif le fait retirer. La vision suit les features, elle ne les bloque pas ; seule une divergence stratégique large est renvoyée vers un /vision en mode Pivot.
Différence /report vs /sync : /report raconte l'histoire de la livraison une fois pour toutes (document figé, lecture chronologique). /sync met à jour le document d'intention en place, comme une révision documentaire. Les deux sont complémentaires : on garde la trace dans report.md et on rend les docs d'intention à nouveau fiables pour les futurs lecteurs.
/commit — Construire et pousser les commits
Dernière étape : une fois report et sync passés, lit le diff git, regroupe les changements en lots cohérents, propose des messages au format Conventional Commits en français (feat(scope): …, fix(scope): …, refactor(scope): …, etc.), demande validation, commit et push. Le commit embarque ainsi le code, le report.md et les docs réalignées en une fois. Sur un track refacto, on a souvent un commit par étape pour préserver la réversibilité.
Ne pas confondre /sync avec /doc-feature : /sync recale un document d'intention récent que tu viens de modifier dans un track structuré. /doc-feature (voir Utilitaires) cartographie une feature ancienne ou jamais passée par le pipeline, en partant du code livré, sans dossier de track préalable.
Utilitaires (hors pipeline)
| Skill | Rôle |
|---|
/test-scenario | Tester un scénario utilisateur via Playwright MCP (navigateur piloté en live) |
/adr | Rédiger un Architecture Decision Record (docs/adr/NNNN-slug.md) depuis un artifact (pitch, plan, review, report) ou un topic libre — format MADR léger, backlinks et index automatiques |
/estimate | Chiffrer le temps « tout compris » d'une story à facturer (feature, refacto, tech) — toutes phases comprises (cadrage, implem, tests, review, doc, release en forfait fixe 30 min), pas seulement le code. Lit brief.md/pitch.md/plan.md selon ce qui existe (plus la matière est riche, plus c'est fiable), chiffre chaque phase justifiée par un signal + une marge d'incertitude, en heures, en deux colonnes (référence sans IA / temps réel avec assistant IA — l'écart = la marge). Produit docs/story/NNN-<f|r|t>-<slug>/estimate.md. Du temps, pas de montant. |
/doc-feature | Cartographier une feature existante en lisant le code (entités, flux, routes, services, templates, points d'extension) — stack-agnostique avec détection auto (Sylius, Symfony, autre). Produit docs/feature-map/NNN-slug/overview.md. Utile pour onboarder sur un module legacy ou documenter une zone du code jamais passée par le pipeline. À distinguer de /sync (qui met à jour une doc d'intention récente). |
/release | Créer une release versionnée bout en bout — détermine le bump SemVer (major/minor/patch) depuis les Conventional Commits depuis le dernier tag, met à jour CHANGELOG.md (format Keep a Changelog), crée un tag annoté vX.Y.Z, push, puis publie la release sur GitHub via gh. Demande validation avant toute action publique. Argument-hint : [major|minor|patch] [--no-push] [--draft] [--pre <suffix>]. |
/help | Ce sommaire — pour se rappeler le workflow et les skills disponibles |
Des plugins complémentaires (ex: sylius, symfony) peuvent exposer des skills plus tactiques (procédures spécifiques au framework : créer une Resource, diagnostiquer un Twig Hook, etc.). Ils se combinent naturellement avec le workflow via l'auto-découverte de Claude Code.
Règles framework
Le workflow détecte automatiquement le stack du projet (Symfony, Sylius) via composer.json / package.json et charge les références correspondantes, bundlées avec le plugin :
- procédure de détection du stack
- règles Symfony — Doctrine, services, forms, Twig, QA, sécu, perf
- delta e-commerce Sylius — Resources, channels, thèmes, Twig Hooks…
Les skills concernées chargent ces références automatiquement après détection — rien à lire manuellement. Les conventions propres à ton projet (commandes QA exactes, credentials de test, noms de thèmes utilisés, branches…) vivent dans le CLAUDE.md à la racine du projet — les skills le lisent en complément des références stack.
Outillage et autorisations
Les skills d'implémentation (/feature, /refactor, /tech) n'imposent aucun outillage : elles ne présument ni de ton gestionnaire de paquets, ni de ton lanceur de tests. Les commandes réelles se lisent dans ton CLAUDE.md, la référence stack, ou ton manifeste de tâches (Makefile, package.json, composer.json, justfile…) — et si elles ne les trouvent pas, elles demandent au lieu de deviner.
Conséquence pratique : c'est à ton projet de pré-autoriser son outillage, dans son .claude/settings.json. Sans ça, Claude Code demandera confirmation à chaque commande de build ou de test — c'est fonctionnel, juste bavard.
{
"permissions": {
"allow": ["Bash(make:*)", "Bash(vendor/bin/*:*)", "Bash(npm:*)"]
}
}
C'est aussi le bon endroit pour poser une interdiction dure (permissions.deny) : contrairement aux allowed-tools d'un skill — qui ne font que pré-autoriser — un deny projet est souverain et ne se contourne pas.
