GitHub Stack

Utilisez gh stack pour la topologie et la synchronisation des branches. Utilisez la skill gh-create-pr du dépôt pour les corps de PR spécifiques à Cherry, l'approbation des spécifications, la couverture des critères d'acceptation, la vérification et le cycle de vie des notes d'agent.

Disponibilité et prérequis

Cette skill publique est suivie dans .agents/skills/ et découverte depuis le dépôt. Les développeurs n'installent pas de skill d'agent séparée. pnpm skills:sync maintient le lien de compatibilité .claude/skills/.

Exécutez cette vérification avant la première commande gh stack dans une tâche :

command -v gh >/dev/null 2>&1 || {
  echo "GitHub CLI is required: https://cli.github.com/" >&2
  exit 1
}
gh auth status
if ! gh stack --help >/dev/null 2>&1; then
  gh extension install github/gh-stack
fi
gh stack --help >/dev/null

Si l'authentification GitHub CLI, l'installation de l'extension ou la vérification finale échoue, arrêtez-vous et signalez la commande défaillante. Ne devinez pas la topologie de la stack avec des comparaisons ad hoc de branches.

Avant d'initialiser une stack, évitez les invites d'extension :

git config rerere.enabled true

Quand plusieurs remotes existent, résolvez le remote intentionnel et passez --remote <name> aux commandes qui l'acceptent. Ne modifiez pas silencieusement remote.pushDefault pour le développeur.

Modèle de stack

Une stack est une chaîne de dépendances linéaire. La branche inférieure est la plus proche du trunk ; chaque branche supérieure contient uniquement du travail qui dépend de la couche en dessous.

main
  -> spec
    -> implementation-core
      -> implementation-ui

Planifiez l'ordre de dépendance complet avant de créer les branches. Placez une modification de couche inférieure nouvellement découverte sur sa branche propriétaire, puis rebasez les branches upstack ; ne la cachez pas dans la couche actuelle.

Commandes sûres pour l'agent

Toutes les commandes doivent être non-interactives :

Toujours exécuter gh stack view --json ; plain view ouvre un TUI.
Toujours fournir les noms de branche à init, add et checkout.
Toujours utiliser --auto avec submit si cette commande est explicitement autorisée.
Passer --remote <name> à push, submit, sync ou link quand plus d'un remote existe.
Utiliser les commandes ordinaires git add et git commit -S --signoff pour que chaque couche soit créée intentionnellement.

Opérations courantes :

gh stack init --base main <bottom-branch> [<higher-branch>...]
gh stack add <new-top-branch>
gh stack view --json
gh stack push --remote <remote>
gh stack rebase --upstack --remote <remote>
gh stack sync --remote <remote>
gh stack checkout <branch-or-pr>
gh stack link --remote <remote> <bottom-pr> <higher-pr> [...]

Un code de sortie 2 de gh stack view --json signifie seulement que le checkout actuel n'a pas de métadonnées de stack locale correspondantes. Cela ne prouve pas qu'une PR existante est autonome sur GitHub. Dans un worktree jetable propre, exécutez gh stack checkout <pr-number-or-url> pour découvrir et hydrater la topologie distante, puis réexécutez gh stack view --json. Classifiez une PR existante comme autonome seulement après que la découverte distante confirme qu'elle n'est pas attachée à une stack GitHub.

Un code de sortie 3 signifie un conflit, mais la récupération dépend de la commande. gh stack rebase laisse l'état de récupération actif, alors résolvez le conflit et exécutez gh stack rebase --continue, ou gh stack rebase --abort. gh stack sync annule le rebase tenté avant de revenir ; démarrez un nouveau gh stack rebase pour résoudre ce conflit, et n'utilisez pas --continue ou --abort sauf si un rebase est actif. Un code de sortie 9 signifie que les PRs empilées GitHub ne sont pas disponibles pour le dépôt ; arrêtez plutôt que de publier silencieusement une forme de PR différente.

Création de PR Cherry

N'utilisez pas gh stack submit --auto pour créer des PRs Cherry rédigées par l'homme. Cela crée des PRs avant l'aperçu du corps requis et génère automatiquement des corps qui ne satisfont pas le modèle du dépôt.

Créez une stack conforme de bas en haut :

Poussez les branches avec gh stack push --remote <remote>.
Invoquez gh-create-pr pour chaque couche, en utilisant la branche parente comme base de cette couche.
Après que chaque PR ait son titre et son corps approuvés, liez les PRs existantes avec gh stack link --remote <remote> <bottom-pr> <higher-pr> [...].
Vérifiez la topologie résultante avec gh stack view --json.

gh stack submit --auto n'est autorisé que pour un flux de travail d'automatisation explicitement autorisé qui est exempté du modèle de PR humain. Ce n'est pas un raccourci autour de l'exigence d'aperçu de Cherry.

Modifications d'une stack existante

Quand vous modifiez une couche inférieure :

Vérifiez cette branche explicitement.
Faites et vérifiez la modification ciblée là.
Exécutez gh stack rebase --upstack --remote <remote>.
Poussez ou synchronisez la stack.
Pour chaque PR réécrite en direct, réexécutez pnpm change:scope --base <verified-parent-ref> et seulement les vérifications invalidées par cette portée réécrite.

Après gh stack sync, inspectez sa sortie et exécutez gh stack view --json ; une commande réussie seule ne prouve pas que chaque PR a toujours l'intention de base, la portée ou la vérification.

Limite de cycle de vie

Suivez .agents/skills/agent-notes/SKILL.md pour l'approbation des spécifications et les transitions de cycle de vie. Les couches d'implémentation intermédiaires gardent la note proposée. Seule la couche finale dont les preuves cumulées réellement exécutées couvrent chaque CA approuvé peut déplacer le triplet de note bilingue vers implemented/.