Menu
HVE Squad
Documentation Bien démarrer
Sur cette page
Guide utilisateur

Bien démarrer

Installez hve-squad dans votre environnement Copilot, sélectionnez le coordinateur et lancez votre première demande.

1. Installer pour votre environnement#

Tous les hôtes et toutes les plateformes : installez PowerShell 7 ou version ultérieure (pwsh). Le Squad Scribe écrit le registre des coûts et exécute son autocontrôle de fin de tour avec Measure-SquadLedger.ps1, et routing=ranked|manual résout les modèles avec Resolve-SquadModelRoute.ps1. Ces deux scripts exigent PowerShell 7 ou version ultérieure — Windows PowerShell 5.1 ne suffit pas. Sans pwsh, la squad fonctionne toujours, mais calcule le registre à la main, ce qui est plus lent, consomme plus de jetons et est moins fiable. Les scripts facultatifs de préparation Azure l'exigent dans tous les cas. Les hooks du plugin n'en ont pas besoin : ils sont fournis avec des équivalents bash.

Windows : winget install --id Microsoft.PowerShell -e · macOS : brew install --cask powershell · Linux : suivez Installing PowerShell. Vérifiez avec pwsh --version, puis redémarrez votre client Copilot pour qu'il trouve pwsh dans le PATH.

Copilot CLI#

Installez GitHub Copilot CLI, connectez-vous avec un compte disposant d'un accès à Copilot et ouvrez un terminal dans le dépôt de votre projet. Installez les deux entrées du marketplace :

copilot plugin marketplace add Peter-N91/hve-squad-plugin
copilot plugin install hve-squad@hve-squad-plugin
copilot plugin install hve-squad-hve-core@hve-squad-plugin
copilot

Dans le sélecteur d'agents, Squad Coordinator peut apparaître sous le nom hve-squad:squad-coordinator. Après avoir vérifié l'installation, passez à l'initialisation ci-dessous.

Vérifier la disponibilité des agents#

Demandez au coordinateur d'exécuter squad-doctor avant de déléguer le travail. Certains domaines HVE Core peuvent manquer dans la distribution plugin. Si le rapport signale des domaines absents, appliquez la solution documentée en installant le package complet dans votre dépôt :

apm install github/microsoft/hve-core --target copilot

N'installez pas le plugin officiel hve-core à côté de hve-squad-hve-core. Pour les mises à jour, réinstallez l'entrée compagnon au lieu d'utiliser la commande de mise à jour du plugin. Suivez le guide d'installation et de mise à jour pour CLI.

Copilot App#

Ouvrez votre projet dans l'application de bureau GitHub Copilot et connectez-vous avec un accès à Copilot. Dans les paramètres des plugins de l'application, enregistrez Peter-N91/hve-squad-plugin et installez à la fois hve-squad et hve-squad-hve-core. Les noms et l'emplacement des paramètres peuvent varier selon la version de l'application ; suivez le guide d'installation de l'application de bureau.

Vérifiez que la paire est installée dans l'application elle-même. Une installation depuis un terminal peut utiliser un autre COPILOT_HOME et ne prouve pas que l'application dispose des mêmes plugins.

Cherchez l'agent Squad Coordinator, éventuellement répertorié sous le nom hve-squad:squad-coordinator, et non un skill au nom similaire. Demandez squad-doctor et résolvez les problèmes d'agents manquants avant de commencer le travail ; la documentation du plugin recense les domaines actuellement absents et la solution consistant à installer le package APM complet.

N'ajoutez pas un second plugin, le hve-core officiel, à côté du compagnon. Mettez les deux entrées à jour dans le répertoire de plugins de l'application, en réinstallant hve-squad-hve-core lorsque sa référence épinglée change.

VS Code#

Ouvrez votre projet dans VS Code avec GitHub Copilot Chat activé et authentifié. Choisissez ci-dessous l'installation via le plugin ou l'installation du package dans le dépôt.

Option 1 — Installer via le plugin depuis le terminal intégré#

Ouvrez le terminal intégré de VS Code avec Terminal → Nouveau terminal, placez-vous à la racine du dépôt de votre projet, puis collez :

copilot plugin marketplace add Peter-N91/hve-squad-plugin
copilot plugin install hve-squad@hve-squad-plugin
copilot plugin install hve-squad-hve-core@hve-squad-plugin
copilot

Dans le sélecteur d'agents, Squad Coordinator peut apparaître sous le nom hve-squad:squad-coordinator. Après avoir vérifié l'installation, passez à l'initialisation ci-dessous.

N'installez pas le plugin officiel hve-core à côté de hve-squad-hve-core. Pour les mises à jour, réinstallez l'entrée compagnon au lieu d'utiliser la commande de mise à jour du plugin. Suivez le guide d'installation et de mise à jour pour CLI.

Option 2 — Installer le package dans le dépôt avec APM#

Cette méthode installe l'ensemble des agents dans le dépôt via APM.

Prérequis

  • PowerShell 7 ou version ultérieure (pwsh) sur toutes les plateformes — voir la note ci-dessus ; sous macOS et Linux, les commandes APM ci-dessous s'exécutent dans votre shell zsh/bash habituel
  • Git
  • APM CLI 0.29.0 installé et disponible dans PATH
  • Accès au dépôt microsoft/hve-core
  • Accès GitHub authentifié (gh auth login ou GITHUB_TOKEN) — vivement recommandé ; voir la note à l'étape 1

APM CLI 0.29.0 est requis pour la méthode d'installation APM. APM 0.29.0 est la dernière version connue qui installe toutes les dépendances HVE Squad correctement. Une régression dans les versions 0.29.1 et 0.30.0, qu'un installateur sans version explicite peut sélectionner, provoque l'échec des mêmes 11 dépendances. La version d'APM CLI et celle du package HVE Squad sont épinglées séparément : apm --version doit afficher 0.29.0, tandis que #vX.Y.z sélectionne la version HVE Squad.

Installer APM CLI 0.29.0#

Windows (PowerShell)

$env:VERSION = 'v0.29.0'; irm https://aka.ms/apm-windows | iex
apm --version  # must report 0.29.0

Si la version reste incorrecte, ouvrez une nouvelle fenêtre PowerShell et vérifiez à nouveau. Utilisez Get-Command apm -All pour repérer un ancien exécutable placé plus tôt dans PATH.

macOS (Apple Silicon ou Intel)

# Run this only if Homebrew currently manages apm; the pinned installer cannot overwrite it.
brew uninstall apm

curl -sSL https://aka.ms/apm-unix | sh -s -- @v0.29.0

# The installer uses ~/.local/bin. Add this line to ~/.zshrc to persist it.
export PATH="$HOME/.local/bin:$PATH"
hash -r
apm --version  # must report 0.29.0

Si vous préférez une installation isolée plutôt que de modifier la copie gérée par Homebrew, installez la même version avec uv tool install apm-cli@0.29.0. Résolvez toute ambiguïté de PATH avant de continuer.

Installer le package#

Exécutez apm install depuis la racine du projet dans lequel vous souhaitez utiliser la squad.

Remplacez vX.Y.z dans les exemples par un tag publié sur la page Releases.

Attention (APM 0.18.0 et versions ultérieures). APM ne choisit plus implicitement l'environnement Copilot par défaut. Dans un projet sans dossiers .github/agents/, .github/prompts/, .github/instructions/, .claude/, .cursor/, etc., apm install échoue avec [x] No harness detected après avoir téléchargé les sources dans apm_modules/ mais avant d'avoir déployé quoi que ce soit dans .github/. Indiquez à APM l'environnement de déploiement avec l'une des options ci-dessous.

Authentifiez-vous d'abord — l'installation sera rapide. Ce package récupère des centaines de fichiers depuis microsoft/hve-core. L'accès non authentifié à GitHub est limité à 60 requêtes par heure, ce qui peut prolonger une première installation au-delà de 30 minutes — APM attend la réinitialisation du quota au lieu d'échouer, ce qui donne l'impression d'un blocage. Exécutez gh auth login (APM le détecte automatiquement) ou définissez GITHUB_TOKEN avant l'installation pour bénéficier de 5 000 requêtes par heure. hve-core étant public, un jeton doté de droits de lecture de base suffit. Consultez Dépannage si une installation est déjà très lente.

Option A — passer --target copilot à chaque installation (ponctuel)#

apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot  # pinned (recommended)
# or
apm install Peter-N91/hve-squad --target copilot           # latest on default branch

Créez un fichier apm.yml à la racine de votre projet utilisateur :

name: my-project
version: 0.1.0
targets:
  - copilot

Dès lors, apm install "Peter-N91/hve-squad#vX.Y.z" (sans option supplémentaire) déploie vers Copilot. Cela rend également reproductibles les prochaines exécutions de apm install / apm update.

Dans les deux cas, les agents, prompts, instructions et skills HVE Core inclus — ainsi que la squad — sont déployés dans l'arborescence .github/ de votre projet. Les utilisateurs n'ont pas besoin de sync-deps ni d'install-sync ; ces scripts sont réservés aux mainteneurs.

Si votre première installation a déjà échoué avec No harness detected : les sources sont déjà dans apm_modules/. Relancez avec --target copilot (option A), ou ajoutez le bloc targets: dans apm.yml (option B) puis relancez apm install ; APM réexécute l'étape de déploiement et remplit .github/.

Redéployer après une mise à jour#

Relancez l'installation avec le tag publié souhaité, en incluant --target copilot sauf si votre projet déclare targets: :

apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

Pour tester les modifications fusionnées avant leur publication, consultez Installer et tester la préversion pour obtenir le tag actuel et la commande exacte. Ce tag évolue ; épinglez une version stable pour les travaux dont vous dépendez. La réinstallation actualise .github/, pas votre état sous .copilot-tracking/squad/.

Installer et tester la préversion#

Cette documentation suit main, qui peut devancer la dernière version stable. Un badge Préversion uniquement identifie une fonctionnalité fusionnée mais pas encore publiée dans une version stable. L'encart de chaque page affiche les deux versions, et chaque badge renvoie ici. Utilisez les versions stables pour les travaux dont vous dépendez.

Testez dans un dépôt de test distinct avec PowerShell 7+ et APM CLI 0.29.0 ; vérifiez avec apm --version. Le site publié renseigne la commande actuelle ci-dessous. Vous pouvez aussi trouver le tag marqué comme préversion sur Releases.

Installer la préversion glissante dans un projet de test : v0.19.0-pre

apm install "Peter-N91/hve-squad#v0.19.0-pre" --target copilot
  1. Installez le package APM complet dans le dépôt de test. Les miroirs plugin et MCP suivent les versions stables ; leur installation ou mise à jour n'installe pas cette préversion. Ne mélangez pas les plugins stables et la préversion APM dans le même environnement de test.
  2. Redémarrez votre client Copilot, sélectionnez Squad Coordinator, envoyez init et confirmez l'équipe proposée.
  3. Envoyez une petite demande qui exerce la fonctionnalité portant un badge et examinez les livrables produits. Signalez les comportements inattendus avec le tag de préversion, le commit résolu dans apm.lock.yaml, les étapes de reproduction et les résultats attendus et observés ; retirez les données privées du projet avant tout partage.

Le tag glissant se déplace à chaque fusion. Relancez l'installation pour l'actualiser et revérifiez l'encart, car une incrémentation de version supérieure peut renommer le tag. Utilisez la commande ci-dessous pour revenir à la version stable ; la réinstallation ne réinitialise pas l'état local de votre squad, donc isolez les tests de préversion.

Installer la version stable, ou y revenir après les tests : v0.18.1

apm install "Peter-N91/hve-squad#v0.18.1" --target copilot

2. Initialiser la squad#

La squad repose sur un Squad Coordinator que l'utilisateur peut invoquer pour répartir sa demande entre les agents HVE Core et conserver son état sous .copilot-tracking/squad/. Commencez par initialiser et confirmer l'équipe proposée : 

/squad init

3. Envoyer une demande de travail#

Après confirmation, envoyez une demande de travail distincte. Utilisez mode=autopilot pour enchaîner le travail tout en conservant les approbations humaines obligatoires, ou omettez ce paramètre pour approuver chaque étape :

/squad request="add input validation to the login form" mode=autopilot

Dans Copilot Harness pour VS Code, ouvrez le sélecteur d'agents et choisissez Squad Coordinator avant d'envoyer chaque demande. Envoyez le texte de la demande affiché ci-dessus sans le préfixe /squad. La voie @squad.prompt.md reste disponible, mais elle ajoute des appels d'agents intermédiaires et est plus lente.

Dans un nouveau projet, le coordinateur examine votre dépôt et propose un profil avant de créer quoi que ce soit. Consultez Utilisation pour les profils, les modes d'autonomie et l'approbation à distance.

Facultatif : fixer un plafond de dépenses pour les modèles#

Ajoutez cost-ceiling=<positive USD> pour demander à la squad d'estimer le coût du travail restant avant de le déléguer. Le plafond porte sur les dépenses estimées des modèles pour l'exécution en cours ; il ne garantit pas le montant de la facture GitHub et ne régit pas le coût des charges de travail Azure. 

/squad request="add input validation to the login form" cost-ceiling=10

Si la prévision dépasse le plafond, la squad affiche l'estimation et vous laisse choisir entre arrêter ou poursuivre par unités séquentielles bornées. Elle ne lance aucune nouvelle unité une fois que les dépenses estimées cumulées atteignent le plafond. Dans un nouveau projet, l'initialisation confirmée se déroule hors plafond pour que le Scribe puisse créer les fichiers d'état et de tarification ; le plafond s'applique avant le début du travail de la demande initiale. Omettez le paramètre dans les demandes ultérieures pour conserver le plafond au sein de la même exécution, ou utilisez cost-ceiling=unset pour le supprimer. Consultez Utilisation → Contrôle d'admission par le coût pour le cycle de vie complet et des exemples.

Facultatif : préparer la couche d'exécution Azure#

Si vous initialisez le profil azure, la squad peut mettre en place dans votre dépôt une chaîne d'outils de construction et de déploiement Azure — un conteneur de développement, des workflows de déploiement OIDC azure/login@v2 pour Bicep et Terraform, un script de configuration OIDC à exécuter une seule fois, un socle de stratégies de gouvernance et la convention de dossiers infra/. Demandez au coordinateur de les mettre en place, puis examinez et validez les fichiers copiés dans Git. Les déploiements restent toujours soumis à l'Impactful-Action Gate, de sorte que rien n'atteint Azure sans votre approbation.

  • Un abonnement Azure (rôle Owner ou User Access Administrator pour exécuter la configuration OIDC initiale).
  • Azure CLI (az) et GitHub CLI (gh) — tous deux fournis dans le conteneur de développement inclus.

Consultez Utilisation → Couche d'exécution Azure pour la procédure complète de mise en place.

Voir le fichier source

Rechercher dans la documentation

Recherchez dans la documentation française. Appuyez sur Échap pour fermer.

Chargement de la recherche…