lguidolin/ship-it

Ship It

Gère l'ensemble du cycle de vie de livraison : preparation, validation, commit, push, ouverture d'une PR, archivage des enregistrements de décision après fusion, et nettoyage.

Vue d'ensemble

Chaque modification passe par une branche et une PR. Ne jamais pusher directement sur main. Ce skill gère le cycle complet, y compris l'archivage de la documentation après fusion.

Les messages de commit sont la documentation. Le titre de la PR devient le commit squash-merge sur main et apparaît dans le changelog. Faites-le correctement dès la création de la PR.

Archiver après fusion, jamais avant. Les spécifications et les plans restent accessibles jusqu'à ce que la PR soit fusionnée. Ce n'est qu'après fusion que nous les convertissons en enregistrements de décision compacts.

Quand l'utiliser

• L'utilisateur dit "push", "ship it", "on livre", "ouvre une PR", "crée une PR"
• L'utilisateur dit "fusionné", "c'est mergé", "pull et nettoie" après qu'une PR a été ouverte
• L'utilisateur a terminé l'implémentation et veut finaliser
• Après avoir terminé un plan où la prochaine étape est de soumettre le travail

Quand NE PAS l'utiliser

• L'utilisateur veut explicitement pusher directement sur main (confirmer d'abord que c'est intentionnel)
• Le dépôt n'a pas de remote configurée
• Les modifications sont en cours (WIP) et l'utilisateur n'est pas prêt à pousser
• L'utilisateur veut seulement commiter sans livrer (utiliser conventional-commits-and-releases)

Processus

Phase 0 : Vérifier et détecter

Une suite rouge ne devient jamais une PR. Exécutez d'abord la suite de tests complète du projet. Si quelque chose échoue, signalez les échecs et arrêtez-vous — ne commitez pas, ne poussez pas et n'ouvrez pas de PR. Cette règle est une politique interne et n'est pas déléguée.

La détection de l'environnement (dépôt normal vs. worktree nommé-branche vs. HEAD détaché) et la détermination de la branche de base sont déléguées à superpowers:finishing-a-development-branch, qui gère déjà les trois cas.

Vérifiez la disponibilité de la bonne manière : cherchez finishing-a-development-branch dans votre propre liste de skills disponibles. S'il est listé, il est invocable. S'il n'est pas listé, il ne l'est pas — passez à la solution de repli.

Ne sondez pas le système de fichiers pour cela. ~/.claude/plugins/cache/ contient chaque version jamais récupérée, y compris les plugins installés mais désactivés, et les skills peuvent être fournis par d'autres mécanismes que le cache de plugins. L'existence d'un chemin dans le cache ne prouve rien quant à votre capacité à invoquer le skill.

S'il est disponible — invoquez-le pour la vérification des tests, la détection de l'environnement et la détermination de la branche de base, puis arrêtez-vous avant son menu d'option.

La décision d'intégration est déjà prise par règle interne et n'appartient pas à l'utilisateur de refaire ici : ce projet fusionne uniquement via une PR, car la PR est ce qui produit le déploiement de prévisualisation et ce que la CI contrôle. Son option "fusionner dans <base> localement" est indisponible. Son option "garder la branche en l'état" reste valide — c'est une décision de reporter, pas de contourner la règle.

S'il manque — passez à la solution de repli, sans rien perdre de ce qui garantit la justesse :

• Exécutez la suite de tests directement.
• Considérez l'upstream de la branche, ou main, comme la base ; confirmez avec l'utilisateur avant de continuer.
• Ignorez le nettoyage de worktree dans la Phase 6 ; supprimez la branche normalement.

Phase 1 : Stage & Commit

git status --short
git branch --show-current
git log --oneline @{upstream}..HEAD 2>/dev/null || echo "No upstream set"

Arbre de décision :

• Sur main avec des modifications non validées → créer une branche, commit, push, PR
• Sur une branche de fonctionnalité avec des modifications non validées → commit, push, PR (ou mettre à jour la PR existante)
• Sur une branche de fonctionnalité avec des commits non poussés → push, PR (ou mettre à jour la PR existante)
• Sur une branche de fonctionnalité avec une PR existante → push (la PR existe déjà)

S'il y a des modifications non staged :

• Demandez à l'utilisateur si toutes les modifications doivent être incluses ou des fichiers spécifiques
• Si les modifications concernent plusieurs sujets, suggérez de les séparer

Rédigez le message de commit :

Type	Quand
feat	Nouvelle fonctionnalité
fix	Corrections de bugs
docs	Documentation uniquement
chore	Configuration, dépendances, outillage
refactor	Restructuration du code, sans changement de comportement
test	Ajout ou modification de tests
ci	Modifications de CI/CD

Format : <type>[scope optionnel]: <description impérative>

Règles :

• Mode impératif ("ajoute", pas "ajouté" ou "ajoute")
• Première lettre en minuscule après le deux-points
• Pas de point à la fin
• Court (50 caractères ou moins pour le sujet)
• Décrivez ce que fait le commit, pas comment

Présentez le message de commit proposé à l'utilisateur et confirmez avant de commiter.

Phase 2 : Branche & Push

Si sur main, créez une branche :

<type>/<courte-description>

Exemples :

• feat/oauth-login
• fix/null-response-handling
• docs/release-workflow-permissions

Push :

git push -u origin $(git branch --show-current)

Phase 3 : Ouvrir la PR

Titre de la PR = message de commit conventionnel (utilisé pour squash-merge sur main).

Structure du corps de la PR :

## Ce qui a changé

[Description spécifique des ajouts/modifications/suppressions]

## Pourquoi

[Motivation — quel problème cela résout-il ?]

Créez avec l'outil gh :

gh pr create --title "<message de commit conventionnel>" --body "<corps de la PR>"

Si gh n'est pas disponible, fournissez l'URL de la PR à partir de la sortie de git push ou construisez-la.

Vérifiez que l'environnement de prévisualisation est opérationnel. Si le projet déploie des prévisualisations par PR, attendez ce workflow et confirmez que l'environnement est accessible avant de remettre la PR :

gh pr checks --watch

Si la prévisualisation échoue à se déployer, signalez-le et arrêtez-vous. Une PR que personne ne peut examiner n'est pas livrée.

Où ce skill s'arrête. ship-it termine sa conscience de déploiement à la prévisualisation. La promotion vers le staging et la production n'est pas son travail — elle appartient au skill de livraison du projet (cloud-delivery-aks, ou équivalent). Les phases 4 à 6 ci-dessous concernent l'hygiène git et la documentation, pas le déploiement.

Phase 4 : Attendre le merge

Après la création de la PR, demandez : "Faites-moi savoir quand elle sera fusionnée et je gérerai le nettoyage et l'archivage."

Attendez la confirmation de l'utilisateur (par exemple, "fusionné", "c'est bon", "c'est mergé").

Phase 5 : Après fusion — Archivage des enregistrements de décision

Les spécifications et les plans sont verbeux par conception — bons pour un humain lisant l'historique, coûteux chaque fois que Claude en charge un. Les convertir en enregistrements de décision compacts permet de garder les décisions essentielles peu coûteuses à lire tandis que le récit complet reste sur le disque, archivé, sans coût jusqu'à ce que quelqu'un l'ouvre délibérément.

Uniquement après la fusion de la PR, vérifiez la présence de spécifications/plans non convertis :

ls docs/superpowers/specs/ 2>/dev/null
ls docs/superpowers/decisions/ 2>/dev/null

Le skill recording-decisions fournit deux assistants pour cela. Localisez-les — le skill peut être installé dans le projet ou globalement :

for base in .claude/skills ~/.claude/skills; do
  d="$base/recording-decisions/scripts"
  [ -d "$d" ] && echo "$d" && break
done

S'ils sont trouvés, $d/doc-archive.sh liste les spécifications non converties et affiche une invite de conversion, et $d/index-rebuild.sh régénère l'index. S'ils ne sont pas trouvés, effectuez le même travail manuellement en utilisant les étapes ci-dessous — elles sont autonomes.

Si des spécifications/plans non convertis existent :

1. Demandez à l'utilisateur : "J'ai trouvé des spécifications/plans qui pourraient correspondre à ce travail. Voulez-vous les convertir en enregistrements de décision compacts et archiver les originaux ?"

2. Si oui, pour chaque spécification :

   • Lisez le contenu de la spécification
   • Générez un enregistrement de décision avec un frontmatter YAML :

     ---
     title: <extrait de la spécification>
     date: <à partir du nom de fichier de la spéc>
     component: <déduit du contenu>
     status: implémenté
     supersedes: null
     dependencies: [<déduit>]
     ---
     

   • Écrivez environ 30 à 50 lignes capturant : décisions clés, interfaces, contraintes
   • Enregistrez dans docs/superpowers/decisions/<date>-<sujet>.md
   • Déplacez la spécification originale vers docs/superpowers/archive/specs/
   • Déplacez le plan correspondant vers docs/superpowers/archive/plans/

3. Reconstruisez l'index maître — régénérez docs/superpowers/index.md à partir des frontmatters de chaque enregistrement de décision, regroupé dans une table Décisions actives (composant, titre, date, dépendances) et une table Remplacées (composant, titre, remplacée par). Exécutez $d/index-rebuild.sh si vous l'avez localisé ci-dessus ; sinon, écrivez le fichier directement.

4. Validez l'archivage :

   git add docs/superpowers/
   git commit -m "docs: archiver les specs et mettre à jour l'index des décisions"
   git push
   

Phase 6 : Nettoyage

git checkout main
git pull
git branch -d <nom-de-branche>
git push origin --delete <nom-de-branche> 2>/dev/null || true
git fetch --prune

Vérifiez l'état propre :

git branch --show-current
git log --oneline -3

Si le travail a eu lieu dans un git worktree, déléguez le démontage à superpowers:finishing-a-development-branch (son nettoyage basé sur la provenance — il sait quels worktrees il possède et laisse intacts ceux gérés en externe). Si ce skill n'est pas disponible, supprimez le worktree manuellement avec git worktree remove <chemin> et confirmez d'abord avec l'utilisateur.

Principes clés

• Une suite rouge ne devient jamais une PR — vérifiez avant toute chose (Phase 0)
• Ne jamais pusher directement sur main — toujours branche + PR. La PR est le déploiement de prévisualisation et la porte de CI ; une fusion locale contourne les deux. Cela remplace tout workflow qui propose la fusion locale comme choix.
• La livraison s'arrête à la prévisualisation — le merge, l'archivage et le nettoyage sont de l'hygiène ; la promotion vers le staging et la production est le travail d'un skill séparé
• Les commits conventionnels — le titre de la PR est l'entrée du changelog
• Archiver seulement après fusion — les spécifications restent accessibles pendant la revue
• Les enregistrements de décision sont compacts — ~30 à 50 lignes, indexés en YAML, optimisés pour LLM
• Nettoyez complètement — pas de branches obsolètes ni de références de suivi