help

name	help
description	Affiche le sommaire du workflow et oriente vers le bon skill — phases amont (vision, product-backlog), trois tracks (feature, refacto, tech), enchaînement et 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 — VISION PROJET (une fois, ou pivot)
                       ┌────────┐
                       │ vision │──▶ docs/vision.md (problème, audience, valeur,
                       └────────┘    North Star, principes, anti-objectifs)
                                     Lu par product-backlog puis feature-pitch.

                       PHASE 0.5 — PÉRIMÈTRE FONCTIONNEL & BACKLOG
                       ┌────────────────┐
                       │ 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.

                       PHASE 0 TECHNIQUE — CARTOGRAPHIE DE LA STACK
                       ┌───────┐
                       │ 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.

                        TRACK FEATURE (valeur utilisateur, structurante)
 (optionnel : besoin flou)
 ┌───────────────────┐
 │ feature-interview │┄┐
 └─────────┬─────────┘ ┊ brief.md
           ▼           ▼
 ┌───────────────┐   ┌──────────────┐   ┌────────────────┐   ┌────────┐   ┌────────┐   ┌────────┐   ┌──────┐
 │ feature-pitch │──▶│ feature-plan │──▶│ feature-implem │──▶│ review │──▶│ commit │──▶│ report │──▶│ sync │
 └───────┬───────┘   └───────┬──────┘   └────────┬───────┘   └────┬───┘   └────┬───┘   └────┬───┘   └───┬──┘
         │                   │                   │                │            │            │           │
     pitch.md             plan.md         code+migrations     review.md     commit      report.md   doc sync
                                          +nouveaux tests                    +push                 +changelog

                    TRACK REFACTO (comportement figé, code restructuré)
 ┌───────────────┐   ┌─────────────────┐   ┌────────┐   ┌────────┐   ┌────────┐   ┌──────┐
 │ refactor-plan │──▶│ refactor-implem │──▶│ review │──▶│ commit │──▶│ report │──▶│ sync │
 └───────┬───────┘   └────────┬────────┘   └────┬───┘   └────┬───┘   └────┬───┘   └───┬──┘
         │                    │                 │            │            │           │
      plan.md           verrou tests        review.md     commit      report.md   doc sync
                          + étapes                         +push
                        incrémentales

               TRACK TECH (perf, résilience, observabilité, sécu — non user-facing)
 ┌───────────┐   ┌─────────────┐   ┌────────┐   ┌────────┐   ┌────────┐   ┌──────┐
 │ tech-plan │──▶│ tech-implem │──▶│ review │──▶│ commit │──▶│ report │──▶│ sync │
 └─────┬─────┘   └──────┬──────┘   └────┬───┘   └────┬───┘   └────┬───┘   └───┬──┘
       │                │               │            │            │           │
    plan.md         baseline        review.md     commit      report.md   doc sync
                  + kill switch                    +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/.

Phase 0 — Vision projet

Avant le premier track, en tout début de projet (ou lors d'un pivot stratégique), poser la vision une fois pour toutes : 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.

#	Skill	Rôle	Produit
0	/vision	Atelier challengeur sur problème, audience, valeur, North Star, principes, anti-objectifs	docs/vision.md

docs/vision.md est lu par /product-backlog (en phase 0.5) puis par /feature-pitch à chaque nouvelle feature pour challenger l'alignement (problème adressé, audience, principes, impact North Star). Pas de lancement à chaque feature : la vision est un document fondateur, révisé seulement lors d'un pivot.

Phase 0.5 — Périmètre fonctionnel et backlog

Une fois la vision validée, traduire la vision en carte des capacités fonctionnelles + backlog priorisé de features candidates. Ce livrable est le pont entre la stratégie (vision) et le cadrage feature par feature (/feature-pitch).

#	Skill	Rôle	Produit
0.5	/product-backlog	Atelier fonctionnel : domaines → capacités → parcours → règles transverses → backlog MVP/V2/V3	docs/product-backlog.md

docs/product-backlog.md est document vivant : on le révise quand le périmètre fonctionnel évolue (nouvelle capacité identifiée, repriorisation, pivot). /feature-pitch le lit pour reprendre le pitch initial d'une ligne de backlog, ses capacités couvertes et ses dépendances. Ce skill est facultatif (on peut aller direct vision → feature-pitch), mais recommandé dès qu'on a plus de 3-4 features pressenties.

Phase 0 technique — Cartographie de la stack

En parallèle des phases vision/backlog, cartographier une fois la stack technique du projet : 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.

#	Skill	Rôle	Produit
0t	/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

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.

#	Skill	Rôle	Produit
0*	/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
2	/feature-plan	Concevoir la solution technique à partir du pitch	docs/story/NNN-f-slug/plan.md
3	/feature-implem	Implémenter sous-tâche par sous-tâche avec QA continue	Code + migrations + tests
4	/review	Code review (sécu, perf, qualité, conformité plan)	docs/story/NNN-f-slug/review.md
5	/commit	Commit Conventional Commits en français + push	Commit
6	/report	Documenter ce qui a été fait vs ce qui était prévu	docs/story/NNN-f-slug/report.md
7	/sync	Réaligner pitch et plan avec la réalité du code	Mise à jour pitch.md + plan.md

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.

#	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
4	/commit	Commit + push (souvent un commit par étape)	Commits
5	/report	Documenter l'exécution vs le plan	docs/story/NNN-r-slug/report.md
6	/sync	Réaligner le plan si la stratégie a dévié	Mise à jour plan.md

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.

#	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
4	/commit	Commit + push	Commits
5	/report	Documenter les critères atteints / non atteints vs le plan	docs/story/NNN-t-slug/report.md
6	/sync	Réaligner le plan si la stratégie a dévié	Mise à jour plan.md

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.

Clôture de track — /commit, /report, /sync

Les trois tracks (feature, refacto, tech) partagent les mêmes étapes de clôture après l'implémentation et la review. Ce sont des skills communs : seuls le contenu et le ton des artifacts changent selon le track.

/commit — Construire et pousser les commits

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. Sur un track refacto, on a souvent un commit par étape pour préserver la réversibilité.

/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.

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.

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>].
/migrate-legacy	Renommer les anciens dossiers docs/story/<f|r|t>-NNN-<slug>/ vers NNN-<f|r|t>-<slug>/, et migrer les artifacts feature.md/design.md → pitch.md/plan.md
/import-external	Importer une doc produite par Spec Kit, BMAD-METHOD ou GSD vers le format workflow
/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.

Agents (orchestrateurs multi-skills)

Les agents sont des orchestrateurs invocables via le tool Agent (pas via /). Ils enchaînent plusieurs skills ou pilotent une boucle d'exécution sans surveillance interactive permanente. Contrairement aux skills, ils ne s'utilisent pas en frappant un slash command — c'est Claude (ou toi, en demandant explicitement "lance l'agent X") qui les déclenche.

Agent	Rôle	Quand l'utiliser
report-and-sync	Enchaîne /forge:report puis /forge:sync pour une story livrée	Après livraison d'une feature/refacto/tech, pour produire le compte rendu et réaligner la doc d'intention en une seule passe
autopilot	Pilote autonome des skills /forge:feature-implem, /forge:refactor-implem, /forge:tech-implem — délègue chaque sous-tâche à un sous-agent isolé, trace l'avancement dans .autopilot.json (reprise possible), ne s'arrête qu'aux stop-points stratégiques (verrou caractérisation, baseline, écart majeur, tests finaux)	Quand l'implémentation est longue et que tu veux laisser tourner sans valider chaque sous-tâche — typiquement features structurées en 5+ sous-tâches, gros refactos Strangler Fig multi-étapes, évolutions tech avec mesure post-étape

Invocation type :

Agent({
  subagent_type: "autopilot",
  description: "Pilote autonome story <slug>",
  prompt: "Pilote en autopilot la story `<slug>`."
})

ou demander en langage naturel : "Lance l'agent autopilot sur checkout-express".

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.