Guide d’installation

Installation via Copilot CLI

Enregistrez la marketplace du plugin, installez-le et vérifiez que l’espace de noms hve-squad est correctement résolu avant d’invoquer un agent.

Prérequis#

GitHub Copilot CLI installé, avec une session connectée
Un accès en lecture à Peter-N91/hve-squad-plugin (dépôt public — aucune autorisation d’accès supplémentaire requise)

Installez les deux plugins, toujours ensemble. Cette marketplace publie deux entrées : hve-squad (les agents et skills propres à la squad) et hve-squad-hve-core (les agents et skills de microsoft/hve-core auxquels la squad délègue le travail). La plupart des rôles de la squad correspondent à un agent hve-core ; installer hve-squad seul laisse donc ces rôles impossibles à résoudre.

Installez hve-squad-hve-core depuis cette marketplace plutôt que directement depuis microsoft/hve-core. L’entrée de cette marketplace est épinglée au SHA exact du commit sur lequel la version correspondante de hve-squad a été construite et validée — le même épinglage que celui enregistré dans le fichier apm.yml de cette version et vérifié par son contrôle cast-delta. Installer hve-core depuis sa propre source fournit au contraire la version qui y est actuellement disponible, laquelle peut être en avance sur les tables de routage et les chartes de rôle auxquelles votre version installée de la squad fait référence.

1. Enregistrer la marketplace#

copilot plugin marketplace add Peter-N91/hve-squad-plugin

2. Installer les deux plugins#

copilot plugin install hve-squad@hve-squad-plugin
copilot plugin install hve-squad-hve-core@hve-squad-plugin

Le suffixe après @ est le nom de la marketplace (hve-squad-plugin, le champ name dans marketplace.json) — et non le propriétaire du dépôt. Les plugins installés se trouvent dans installed-plugins/hve-squad-plugin/<plugin>/, qui reprend la même structure marketplace/plugin.

L’installation de hve-squad lit le manifeste .github/plugin/plugin.json de ce dépôt et enregistre tout ce qu’il référence : les 27 agents dans agents/squad/, le skill squad et ses skills d’invocation dans skills/squad/, les scripts de contrôle de hooks.json et l’enregistrement du serveur dans .mcp.json pour @hve-squad/mcp. hve-squad-hve-core fournit ensuite les agents et skills hve-core auxquels ces rôles de la squad délèguent le travail, à la version du commit épinglé.

3. Vérifier l’installation#

copilot plugin list

Vérifiez que les deux plugins, hve-squad et hve-squad-hve-core, apparaissent avec un statut indiquant qu’ils sont actifs. Si un seul apparaît, relancez l’installation manquante de l’étape 2 — une squad sans hve-core installé fera remonter le problème plutôt que de déléguer lorsqu’un agent associé à un rôle est introuvable.

🖼️

Emplacement réservé à une capture d’écran

Sortie de copilot plugin list montrant hve-squad enregistré

4. Résolution des espaces de noms#

Une fois le plugin installé, tous les agents fournis sont accessibles sous l’espace de noms hve-squad:squad-* — le nom du plugin (hve-squad, issu de plugin.json) est ajouté en préfixe au nom de chaque agent. Par exemple :

# Ask Copilot CLI to dispatch the coordinator directly
hve-squad:squad-coordinator

# Or let natural language resolve to it
"use the squad to research this codebase"

Si deux plugins installés fournissent un agent portant le même nom court, le préfixe d’espace de noms permet de les distinguer — vous pouvez toujours l’utiliser explicitement sans risque d’ambiguïté.

Mises à jour ultérieures#

Cette marketplace ne définit délibérément pas autoUpdate. Les deux entrées forment une paire assortie : une mise à jour sans intervention qui ferait évoluer hve-squad tout en laissant hve-squad-hve-core à son ancienne version (ou l’inverse) réintroduirait précisément le décalage de versions que l’entrée épinglée vise à éviter. Les mises à jour sont donc explicites, et les deux entrées évoluent ensemble.

Pour adopter une nouvelle version :

# 1. Refresh the marketplace so the CLI sees the new entries and their pins
copilot plugin marketplace update Peter-N91/hve-squad-plugin

# 2. Update hve-squad in place
copilot plugin update hve-squad@hve-squad-plugin

# 3. Replace hve-squad-hve-core — uninstall THEN install, never update
copilot plugin uninstall hve-squad-hve-core@hve-squad-plugin
copilot plugin install hve-squad-hve-core@hve-squad-plugin

# 4. Confirm both moved
copilot plugin list

copilot plugin update ne fonctionne pas pour hve-squad-hve-core. Désinstallez-le, puis installez-le. Ce n’est pas une préférence — le mécanisme de mise à jour ne peut pas détecter un nouvel épinglage pour cette entrée et vous laissera sur l’ancienne version de hve-core tout en signalant une réussite.

La raison est que plugin update compare la version enregistrée au moment de l’installation à celle qu’il détermine maintenant ; pour cette entrée, ces deux versions proviennent du fichier plugin.json propre à hve-core en amont (par exemple 3.2.2) — et non du champ version de l’entrée de cette marketplace. Lorsqu’une version de hve-squad ne modifie que source.sha et que la version propre à hve-core en amont n’a pas changé, les deux numéros restent identiques ; le CLI répond donc already at latest et conserve l’arborescence précédemment récupérée. Le commit épinglé a changé ; les fichiers sur disque, non.

Une désinstallation préalable efface cet état enregistré : l’installation suivante résout donc source.sha à nouveau et récupère l’arborescence sur laquelle la version actuelle a été validée. Faites-le à chaque adoption d’une nouvelle version, même lorsque copilot plugin update hve-squad-hve-core@hve-squad-plugin affirme qu’il n’y a rien à faire.

Ne mettez jamais l’un à jour sans l’autre. Chaque version de hve-squad épingle le commit hve-core sur lequel elle a été validée. Lorsqu’une version change ce commit épinglé, le SHA de l’entrée hve-squad-hve-core change aussi — mettre à jour hve-squad seul vous fait donc exécuter le nouveau contenu de la squad avec un ancien hve-core pour lequel il n’a pas été conçu. Si vous avez un doute sur l’état de votre installation, désinstallez puis réinstallez les deux entrées.

Un répertoire de plugins par client. Le CLI stocke les plugins dans $COPILOT_HOME, et les clients qui intègrent Copilot CLI (applications de bureau, intégrations dans les IDE) font couramment pointer cette variable vers leur propre répertoire plutôt que vers ~/.copilot. Une mise à jour dans un terminal ne met donc pas à jour la copie utilisée par un client qui intègre le CLI. Exécutez la paire désinstallation/installation une fois pour chaque répertoire de plugins depuis lequel vous invoquez effectivement la squad.

N’installez pas également le plugin officiel hve-core#

Si vous utilisez la squad, installez hve-core uniquement via l’entrée hve-squad-hve-core de cette marketplace. N’installez pas en plus le plugin officiel hve-core depuis microsoft/hve-core, et n’enregistrez pas la marketplace propre à hve-core à côté de celle-ci.

Les deux entrées fournissent les mêmes fichiers d’agents, de skills et d’instructions sous des noms de plugin différents, et l’entrée officielle suit la version courante en amont plutôt que le commit validé. Avec les deux installées, vous obtenez deux copies enregistrées de chaque artefact hve-core, généralement à deux commits différents. Les rôles de la squad sont associés aux agents hve-core par leur nom : une délégation peut donc aboutir à la copie non épinglée — les tables de routage, les chartes de rôle et les garanties du contrôle cast-delta sur lesquelles votre version installée de hve-squad a été construite ne s’appliquent plus. Les symptômes sont ambigus : agents dupliqués ou masqués dans copilot plugin list, rôles associés à un agent dont la charte ne correspond pas à la table de routage, ou délégations qui se comportent différemment entre deux machines utilisant la même version de hve-squad.

L’entrée hve-squad-hve-core porte un nom distinct afin que les deux puissent être enregistrées côte à côte sans conflit de noms à l’installation. Il s’agit d’une précaution de distribution pour qu’une installation préexistante ne bloque pas celle-ci — ce n’est pas une recommandation d’utiliser les deux. Si le plugin officiel est déjà installé, supprimez-le avant d’invoquer la squad :

copilot plugin list
copilot plugin uninstall hve-core@<its-marketplace>

Si vous avez besoin du plugin officiel pour un autre travail, conservez-le dans un répertoire de plugins distinct (avec une valeur différente de $COPILOT_HOME) plutôt qu’à côté de la squad.

Déroulement de l’installation#

Source du schéma


sequenceDiagram
    participant U as Utilisateur
    participant CLI as Copilot CLI
    participant MP as Marketplace (ce dépôt)
    participant Repo as hve-squad-plugin
    participant Core as microsoft/hve-core
    participant Reg as Registre local des plugins

    U->>CLI: copilot plugin marketplace add Peter-N91/hve-squad-plugin
    CLI->>MP: récupère .github/plugin/marketplace.json
    MP-->>CLI: 2 entrées — hve-squad (réf. main), hve-squad-hve-core (SHA épinglé)

    U->>CLI: copilot plugin install hve-squad@hve-squad-plugin
    CLI->>Repo: récupère plugin.json, puis agents/, skills/, hooks.json, .mcp.json
    CLI->>Reg: enregistre 27 agents + la compétence squad + les hooks + le serveur MCP

    U->>CLI: copilot plugin install hve-squad-hve-core@hve-squad-plugin
    CLI->>Core: récupère le contenu au SHA du commit épinglé
    CLI->>Reg: enregistre les agents et compétences hve-core

    Reg-->>CLI: espaces de noms actifs, rôles de la squad résolus
    U->>CLI: hve-squad:squad-coordinator ...
    CLI-->>U: invoque Squad Coordinator, qui peut désormais appeler les rôles hve-core