Getting Started
Install hve-squad in your Copilot environment, select the coordinator, and run your first request.
1. Install for your environment#
All hosts and platforms: install PowerShell 7+ (pwsh).
The Squad Scribe writes the cost ledger and runs its end-of-turn self-check with
Measure-SquadLedger.ps1, and routing=ranked|manual resolves models
with Resolve-SquadModelRoute.ps1. Both require PowerShell 7 or later — Windows
PowerShell 5.1 is not enough. Without pwsh the squad still runs, but falls back to
deriving the ledger by hand, which is slower, uses more tokens and is less reliable. The
optional Azure scaffold scripts require it outright. The plugin hooks do not need it: they ship
bash equivalents.
Windows: winget install --id Microsoft.PowerShell -e · macOS:
brew install --cask powershell · Linux: follow
Installing PowerShell.
Check with pwsh --version, then restart your Copilot client so it finds
pwsh on PATH.
Copilot CLI#
Install GitHub Copilot CLI, sign in with an account that has Copilot access, and open a terminal in your own project repository. Install both marketplace entries:
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
copilotIn the agent picker, Squad Coordinator may be displayed as hve-squad:squad-coordinator. Continue with initialization below after checking the installation.
Check agent availability#
Ask the coordinator to run squad-doctor before dispatching work. The plugin distribution can lack HVE Core domains. If the report identifies missing domains, use the documented full-package remedy in your repository:
apm install github/microsoft/hve-core --target copilotDo not install the official hve-core plugin alongside hve-squad-hve-core. For updates, reinstall the companion entry rather than using plugin update on it. Follow the CLI installation and update guide.
Copilot App#
Open your project in the GitHub Copilot desktop app and sign in with Copilot access. In the app's plugin settings, register Peter-N91/hve-squad-plugin and install both hve-squad and hve-squad-hve-core. Names and settings locations can vary by app version; follow the desktop installation guide.
Verify the pair is installed in the app itself. A terminal installation may use a different COPILOT_HOME and does not prove the app has the same plugins.
Look for the Squad Coordinator agent, possibly listed as hve-squad:squad-coordinator, not a similarly named skill. Ask for squad-doctor and resolve missing agents before work starts; the plugin documentation records current domain gaps and the full APM package remedy.
Do not add a second, official hve-core plugin alongside the companion. Update both entries in the app's plugin home, reinstalling hve-squad-hve-core when its pin changes.
VS Code#
Open your project in VS Code with GitHub Copilot Chat enabled and authenticated. Choose either the plugin installation or the repository package route below.
Option 1 — Install through the plugin from the integrated terminal#
Open the VS Code integrated terminal with Terminal → New Terminal, change to the root of your project repository, and paste:
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
copilotIn the agent picker, Squad Coordinator may be displayed as hve-squad:squad-coordinator. Continue with initialization below after checking the installation.
Do not install the official hve-core plugin alongside hve-squad-hve-core. For updates, reinstall the companion entry rather than using plugin update on it. Follow the CLI installation and update guide.
Option 2 — Install the package into the repository with APM#
This route installs the full cast into the repository through APM.
Prerequisites
- PowerShell 7+ (
pwsh) on every platform — see the note above; on macOS and Linux the APM commands below run in your usualzsh/bashshell - Git
- APM CLI 0.29.0 installed and available in
PATH - Access to the microsoft/hve-core repository
- Authenticated GitHub access (
gh auth loginorGITHUB_TOKEN) — strongly recommended; see the note in step 1
APM CLI 0.29.0 is required for the APM installation path.
APM 0.29.0 is the latest version known to install all HVE Squad dependencies
successfully. A regression in 0.29.1 and 0.30.0, which an unversioned installer may
select, causes the same 11 dependencies to fail. The APM CLI version and the HVE Squad
package version are separate pins: apm --version must report
0.29.0, while #vX.Y.z selects the HVE Squad release.
Install 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
If the version is still wrong, open a new PowerShell window and check again. Use
Get-Command apm -All to find an older executable that appears earlier in
PATH.
macOS (Apple Silicon or 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
If you prefer an isolated installation rather than changing the Homebrew-managed copy,
install the same version with uv tool install apm-cli@0.29.0. Resolve any
PATH ambiguity before continuing.
Install the package#
Run apm install from the root of the project you want the squad in.
Replace vX.Y.z in the examples with a published tag from Releases.
Heads-up (APM 0.18.0+). APM no longer silently defaults to the Copilot
harness. In a project with no existing .github/agents/,
.github/prompts/, .github/instructions/, .claude/,
.cursor/, etc., apm install fails with
[x] No harness detected after downloading sources into
apm_modules/ but before deploying anything into
.github/. Tell APM which harness to deploy to using one of the options below.
Authenticate first — it makes the install fast. This package pulls
hundreds of files from microsoft/hve-core.
Unauthenticated GitHub access is rate limited to 60 requests/hour, which can stretch a
first install to 30+ minutes — APM waits on the rate-limit reset rather than failing, so it
looks stuck. Run gh auth login (APM detects it automatically) or set
GITHUB_TOKEN before installing to get 5,000 requests/hour. hve-core
is public, so a token with basic read scope is enough. See
Troubleshooting if an install is already crawling.
Option A — pass --target copilot on every install (one-off)#
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 branchOption B — declare the target once in your project's apm.yml (persistent, recommended)#
Create an apm.yml at the root of your consumer project:
name: my-project
version: 0.1.0
targets:
- copilot
Then apm install "Peter-N91/hve-squad#vX.Y.z" (no flag needed) deploys to
Copilot from now on. This also makes future apm install / apm update
runs reproducible.
Either way, this deploys the bundled HVE Core agents, prompts, instructions, and skills —
plus the squad — into your project's .github/ tree. Consumers do not
need sync-deps or install-sync; those are maintainer-only scripts.
If your first install already failed with No harness detected:
the sources are already in apm_modules/. Re-run with --target copilot
(Option A) or add the targets: block to apm.yml (Option B) and
re-run apm install; APM re-runs the deploy step and populates
.github/.
Re-deploy after an update#
Re-run install with the published tag you want, including --target copilot unless your project declares targets::
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilotTo test merged work before release, follow Install and test the pre-release for the current tag and exact command. That tag moves; pin a stable release for work you depend on. Reinstallation refreshes .github/, not your state under .copilot-tracking/squad/.
Install and test the pre-release#
These docs follow main, which can be ahead of the latest stable release.
A Pre-release only badge identifies a feature that has merged but has not
shipped in a stable release. The notice on every page shows both versions, and each badge
links here. Use stable releases for work you depend on.
Test in a separate scratch repository with PowerShell 7+ and APM CLI 0.29.0;
confirm with apm --version. The published site fills in the current command below.
You can also find the tag marked as a pre-release on
Releases.
Install the rolling pre-release in a scratch project: v0.19.0-pre
apm install "Peter-N91/hve-squad#v0.19.0-pre" --target copilot- Install the full APM package in the scratch repository. The plugin and MCP mirrors follow stable releases; installing or updating those does not install this pre-release. Do not mix the stable plugins and the APM preview in the same test environment.
- Restart your Copilot client, select Squad Coordinator, send
init, and confirm the proposed team. - Send a small request exercising the badged feature and inspect the resulting artifacts. Report unexpected behavior with the pre-release tag, the resolved commit in
apm.lock.yaml, reproduction steps, and expected versus actual results; remove private project data before sharing.
The rolling tag moves on every merge. Re-run the install to refresh it, and check the notice again because a higher release bump can rename the tag. Use the command below to return to stable; reinstallation does not reset your local squad state, so keep preview testing isolated.
Install the stable release, or return to it after testing: v0.18.1
apm install "Peter-N91/hve-squad#v0.18.1" --target copilot2. Initialize the squad#
The squad is a user-invocable Squad Coordinator that routes your request to a cast of HVE
Core agents and persists its state under .copilot-tracking/squad/.
Initialize and confirm the proposed team first:
/squad init3. Send a work request#
After confirmation, send a separate work request. Use mode=autopilot to sequence the work while keeping required human approvals, or omit it to approve each step:
/squad request="add input validation to the login form" mode=autopilot
In VS Code Copilot Harness, open the agents dropdown and select Squad Coordinator
before sending each request. Send the request text shown above without the /squad
prefix. The @squad.prompt.md route remains available, but it adds intermediary agent
calls and is slower.
On a fresh project the coordinator inspects your repo and proposes a profile before creating anything. See Usage for profiles, autonomy modes, and remote approval.
Optional: set a model-spend ceiling#
Add cost-ceiling=<positive USD> when you want the squad to forecast the
remaining work before dispatching it. The ceiling governs estimated model spend for the
current run; it is not a GitHub invoice guarantee and does not govern Azure workload cost.
/squad request="add input validation to the login form" cost-ceiling=10
If the forecast is above the ceiling, the squad shows the estimate and lets you stop or
proceed in bounded sequential units. It starts no new unit after accumulated estimated spend
reaches the ceiling. On a fresh project, confirmed initialization runs outside the ceiling
so the Scribe can create the state and pricing files; the ceiling applies before the original
request starts work. Omit the argument on later requests to inherit the ceiling within the
same run, or use cost-ceiling=unset to remove it. See
Usage → Cost admission control for the
full lifecycle and examples.
Optional: scaffold the Azure execution layer#
If you seed the azure profile, the squad can scaffold an Azure build-and-deploy
toolchain into your repo — a dev container, azure/login@v2 OIDC deploy workflows
for Bicep and Terraform, a one-time OIDC setup script, a governance policy baseline, and the
infra/ folder convention. Ask the coordinator to scaffold it, then review and
commit the copied files. Deploys always run behind the Impactful-Action Gate, so nothing
reaches Azure without your approval.
- An Azure subscription (Owner or User Access Administrator to run the one-time OIDC setup).
- The Azure CLI (
az) and GitHub CLI (gh) — both provided by the bundled dev container.
See Usage → Azure execution layer for the full scaffolding flow.