Installer et utiliser Forge

Prérequis

Forge n'est ni un binaire ni une dépendance de votre projet : c'est un ensemble d'instructions markdown que Claude Code charge. Il n'y a donc rien à compiler et aucun runtime à installer.

• Claude Code, dans n'importe laquelle de ses formes (CLI, application desktop, web ou extension IDE).
• Un dépôt git initialisé. Les skills /forge:commit et /forge:release écrivent dans git ; les autres se contentent de lire le code et d'écrire des fichiers markdown.
• Le CLI gh authentifié, uniquement pour /forge:release, qui publie la release sur GitHub.
• Un serveur MCP Playwright, uniquement pour /forge:test-scenario, qui pilote un navigateur en live.

Aucune contrainte de langage ou de framework : le pipeline est stack-agnostique. Il détecte Symfony et Sylius pour charger des règles plus précises, mais fonctionne sur n'importe quelle base de code.

Installation

Les trois commandes se tapent dans une session Claude Code, pas dans un terminal. Elles valent pour n'importe quel projet.

1. Ajouter la marketplace

   Enregistre le catalogue de plugins depuis GitHub. Rien n'est installé à ce stade.

   ❯ /plugin marketplace add gabrielmustiere/forge

2. Installer le plugin

   La syntaxe est plugin@marketplace. Le plugin forge et la marketplace forge portent le même nom — la répétition est normale.

   ❯ /plugin install forge@forge

3. Recharger les plugins

   Rend les 26 skills disponibles dans la session courante.

   ❯ /reload-plugins

Vérifier l'installation

Lancez le sommaire du pipeline. S'il répond, tout est en place.

❯ /forge:help

Aucune skill ne se déclenche toute seule : c'est un choix de conception. Le triage automatique entre skills voisines est probabiliste, donc faux un jour sur N — et un mauvais aiguillage produit le mauvais document. C'est vous qui appelez la skill.

Mettre à jour

Forge évolue en continu. Pour récupérer la dernière version publiée :

❯ /plugin marketplace update forge
❯ /reload-plugins

Les versions suivent le SemVer et sont annoncées dans le CHANGELOG au format Keep a Changelog.

La règle d'or

La conséquence pratique : un artefact bancal se corrige à l'étape où il naît, pas trois étapes plus loin dans du code déjà écrit.

Artefacts et docs/story/

Tous les artefacts vivent à plat dans docs/story/, numérotés globalement puis taggés par track. Le numéro vient en premier pour que le tri lexicographique d'un simple ls donne la timeline du projet.

docs/story/042-f-checkout-express/   # f = feature
docs/story/043-r-extract-pricing/    # r = refacto
docs/story/044-t-redis-cache/        # t = évolution technique

Le format est NNN-<f|r|t>-<slug>. Les numéros s'incrémentent globalement, tous tracks confondus : 042-f → 043-r → 044-t → 045-f.

Les documents d'une story

Un 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 n'y a sa place. Les plans et la review sont techniques. Les documents de décision (review, report, estimation) ouvrent sur leur section ## Synthèse — on doit pouvoir ne lire qu'elle.

Choisir son track

Quatre questions, dans l'ordre. La première qui répond « oui » donne le track.

Ce que chaque track impose

• Feature — un cadrage fonctionnel (pitch.md) avant tout plan technique : quel problème utilisateur, pour qui, pourquoi maintenant. C'est le seul track à passer par cette étape.
• Refacto — comportement externe strictement préservé, verrou de tests de caractérisation posé avant de toucher au code, exécution incrémentale et réversible — souvent un commit par étape.
• Tech — une métrique cible chiffrée, une baseline mesurée avant toute modification, un kill switch activable, et une mesure après chaque étape.

Le track ne change pas les phases que vous traversez : il change les skills que vous appelez à l'intérieur de chacune. Voir la référence des skills.

Le track fast

Tout ne mérite pas un pitch. Le track fast couvre les bugfixes et petits changements, sous trois conditions cumulatives :

• Moins de 3 fichiers modifiés ;
• Pas de changement de schéma (migration) ni de nouveau service ou entité ;
• Pas d'impact transverse (multi-channel, multi-thème, API publique…).

coder → QA du stack → tests ciblés → /forge:review (optionnel) → /forge:commit

En cas de doute, partez sur le track approprié : on peut toujours basculer du structurant vers le fast si l'analyse révèle que c'est trivial. L'inverse coûte plus cher.

Phase 0 — poser le décor

Une fois en début de projet, puis révisé lors d'un pivot. Ces trois documents sont vivants : ils supportent quatre modes (Création, Enrichir, Éditer, Pivot) et tiennent leur propre changelog.

docs/vision.md est lu par /forge:product-backlog puis par /forge:feature-pitch à chaque feature, pour challenger l'alignement. docs/stack.md est lu en priorité par les skills techniques. Il constate l'existant — il ne justifie pas un choix (c'est /forge:adr) ni ne décide d'une évolution (c'est /forge:tech-plan).

/forge:product-backlog est facultatif : on peut aller directement de la vision au pitch. Il devient recommandé dès qu'on a plus de trois ou quatre features pressenties.

Phase 1 — cadrer

Le point d'entrée de toute story : on choisit son track, puis on formalise l'intention avant d'écrire la moindre ligne. C'est la phase où un désaccord coûte le moins cher — corriger un pitch prend cinq minutes, corriger le code qui en découle prend la journée.

Les trois tracks produisent un plan.md — le cadrage technique exécutable — et partagent le même squelette de sections ; leurs spécificités (caractérisation d'un refacto, kill switch d'un tech) s'y ajoutent. Seul le track feature intercale un pitch.md en amont, parce que lui seul doit d'abord répondre à une question fonctionnelle.

Phase 2 — implémenter

Une skill par track, toutes bâties sur le même principe : avancer par étapes courtes, avec la QA du projet après chacune, plutôt que produire un gros diff à vérifier à la fin.

Phase 3 — clôturer

Commune aux trois tracks : les mêmes skills, quel que soit le chemin parcouru en phases 1 et 2. Seuls le contenu et le ton des artefacts changent — la review d'un track tech s'intéresse au kill switch, celle d'un refacto à la non-régression.

Utilitaires — hors pipeline

Permissions et outillage

Les skills d'implémentation n'imposent aucun outillage : elles ne présument ni de votre gestionnaire de paquets, ni de votre lanceur de tests. Elles lisent les commandes réelles dans votre CLAUDE.md, la référence stack, ou votre 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 à votre 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 via permissions.deny : contrairement aux allowed-tools d'une skill — qui ne font que pré-autoriser — un deny projet est souverain et ne se contourne pas.

Le CLAUDE.md du projet

Les références stack embarquées dans le plugin couvrent le générique. Ce qui est propre à votre projet — commandes QA exactes, identifiants de test, noms de thèmes, conventions de branches — vit dans le CLAUDE.md à la racine. Les skills le lisent en complément.

/forge:claude-md le génère pour vous, en prouvant chaque affirmation par un fichier du dépôt. Si une règle est scopable à une zone du code, préférez /forge:rules : elle produit un fichier dans .claude/rules/ qui n'est chargé que quand Claude ouvre un fichier concerné — le contexte reste léger.

Règles framework

Le workflow détecte le stack via composer.json / package.json et charge les références correspondantes, bundlées avec le plugin :

• la procédure de détection du stack ;
• les règles Symfony — Doctrine, services, forms, Twig, QA, sécu, perf ;
• le delta e-commerce Sylius — Resources, channels, thèmes, Twig Hooks…

Le chargement est automatique après détection : rien à lire manuellement. Des marketplaces complémentaires (par exemple gabrielmustiere/skills) exposent des skills plus tactiques, propres à un framework, qui se combinent naturellement avec le pipeline.

Dépannage

/forge:xxx est introuvable

Lancez /reload-plugins. C'est nécessaire après l'installation et après chaque mise à jour de la marketplace. Vérifiez aussi le préfixe : c'est /forge:help, pas /help.

Une skill ne se déclenche pas toute seule

C'est le comportement attendu, pas un bug : aucune skill Forge ne s'auto-déclenche. Le triage automatique entre skills voisines est probabiliste, et un mauvais aiguillage produirait le mauvais document. Appelez la skill explicitement.

Claude demande confirmation à chaque commande

Votre projet n'a pas pré-autorisé son outillage. Voir Permissions et outillage.

Le Forge Board n'affiche pas mes stories correctement

Le Board lit le metadata.json de chaque story et ne l'écrit jamais. Sur des stories antérieures à cette convention, le fichier n'existe pas : lancez /forge:backfill-metadata pour le reconstruire depuis l'historique git.

Développer le plugin

Pour tester une modification locale du plugin avant publication, lancez Claude Code depuis n'importe quel projet en pointant le dossier du plugin :

$ claude --plugin-dir /chemin/vers/forge/plugins/forge

Pendant la session, /reload-plugins recharge après chaque modification.

Structure d'une skill : un dossier skills/<nom>/SKILL.md, dont le name en frontmatter YAML doit matcher le nom du dossier. Les dossiers skills/, commands/, agents/ et hooks/ vivent à la racine du plugin — seul plugin.json habite .claude-plugin/.

Le code, l'inventaire complet des skills et le changelog sont sur GitHub.