Install Guide

Install via Copilot CLI

Register the plugin's marketplace, install it, and confirm the hve-squad namespace resolves before dispatching an agent.

Prerequisites

Install both plugins, always as a pair. This marketplace publishes two entries: hve-squad (the squad's own agents and skills) and hve-squad-hve-core (the microsoft/hve-core agents and skills the squad dispatches to). Most squad roles resolve to an hve-core agent, so installing hve-squad alone leaves those roles unresolvable.

Install hve-squad-hve-core from this marketplace rather than from microsoft/hve-core directly. This marketplace's entry is pinned to the exact commit SHA that the matching hve-squad release was built and validated against — the same pin recorded in that release's apm.yml and checked by its cast-delta guard. Installing hve-core from its own source instead gives you whatever is current there, which can be ahead of the routing tables and role charters your installed squad version references.

1. Register the marketplace

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

2. Install both plugins

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

The suffix after @ is the marketplace name (hve-squad-plugin, the name field in marketplace.json) — not the repository owner. Installed plugins land under installed-plugins/hve-squad-plugin/<plugin>/, which mirrors the same marketplace/plugin shape.

Installing hve-squad reads this repository's .github/plugin/plugin.json manifest and registers everything it points at: the 27 agents under agents/squad/, the squad skill and its invocation skills under skills/squad/, the hooks.json enforcement scripts, and the .mcp.json server registration for @hve-squad/mcp. hve-squad-hve-core then supplies the hve-core agents and skills those squad roles dispatch to, at the pinned commit.

3. Verify the install

copilot plugin list

Confirm both hve-squad and hve-squad-hve-core appear with a status indicating they are active. If only one appears, re-run the missing install from step 2 — a squad with no hve-core installed will escalate rather than dispatch when a role's agent cannot be found.

🖼️
Screenshot placeholder
copilot plugin list output showing hve-squad registered

4. Namespace resolution

Once installed, every agent this plugin ships is addressable under the hve-squad:squad-* namespace — the plugin name (hve-squad, from plugin.json) prefixed to each agent's own name. For example: 

# 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"

If two installed plugins ship an agent with the same short name, the namespace prefix is what disambiguates them — always safe to use explicitly.

Updating later

This marketplace deliberately does not set autoUpdate. The two entries are a matched pair: an unattended update that moved hve-squad forward while leaving hve-squad-hve-core behind (or the reverse) would reintroduce exactly the version skew the pinned entry exists to prevent. Updates are therefore explicit, and both entries move together.

To take a new release:

# 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 does not work for hve-squad-hve-core. Uninstall it, then install it. This is not a preference — the update path cannot detect a new pin for this entry, and will leave you on the old hve-core while reporting success.

The reason is that plugin update compares the version recorded at install time against the version it resolves now, and for this entry both of those come from upstream hve-core's own plugin.json (for example 3.2.2) — not from the version field of this marketplace's entry. When an hve-squad release bumps only source.sha and upstream hve-core's own version has not changed, the two numbers still match, so the CLI answers already at latest and keeps the previously fetched tree. The pin moved; the files on disk did not.

Uninstalling first clears that recorded state, so the follow-up install resolves source.sha fresh and fetches the tree the current release was validated against. Do this every time you take a release, even when copilot plugin update hve-squad-hve-core@hve-squad-plugin claims there is nothing to do.

Never update one without the other. Each hve-squad release pins the hve-core commit it was validated against. When a release bumps that pin, the hve-squad-hve-core entry's SHA changes with it — so updating hve-squad alone leaves you running new squad content against the older hve-core it was not built for. If you are ever unsure what state you are in, uninstall and reinstall both entries.

One plugin home per client. The CLI stores plugins under $COPILOT_HOME, and clients that embed the Copilot CLI (desktop apps, IDE integrations) commonly point that at their own directory rather than ~/.copilot. Updating in a terminal therefore does not update the copy an embedding client uses. Run the uninstall/install pair once per plugin home you actually dispatch the squad from.

Do not also install the official hve-core plugin

If you run the squad, install hve-core only through this marketplace's hve-squad-hve-core entry. Do not additionally install the official hve-core plugin from microsoft/hve-core, and do not register hve-core's own marketplace alongside this one.

The two entries ship the same agent, skill, and instruction files under different plugin names, and the official one tracks whatever is current upstream instead of the validated commit. With both installed you get two registered copies of every hve-core artifact, usually at two different commits. Squad roles resolve to hve-core agents by name, so a dispatch can land on the unpinned copy — and the routing tables, role charters, and cast-delta guarantees your installed hve-squad release was built against no longer hold. Symptoms are ambiguous: duplicated or shadowed agents in copilot plugin list, roles that resolve to an agent whose charter does not match the routing table, or dispatches that behave differently between two machines on the same hve-squad version.

The hve-squad-hve-core entry is named distinctly so the two can be registered side by side without a name collision at install time. That is a packaging safeguard so a pre-existing install does not block this one — it is not a recommendation to run both. If you already have the official plugin installed, remove it before dispatching the squad: 

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

If you need the official plugin for unrelated work, keep it in a separate plugin home (a different $COPILOT_HOME) rather than alongside the squad.

Install flow

sequenceDiagram participant U as User participant CLI as Copilot CLI participant MP as Marketplace (this repo) participant Repo as hve-squad-plugin participant Core as microsoft/hve-core participant Reg as Local plugin registry U->>CLI: copilot plugin marketplace add Peter-N91/hve-squad-plugin CLI->>MP: fetch .github/plugin/marketplace.json MP-->>CLI: 2 entries — hve-squad (ref main), hve-squad-hve-core (pinned sha) U->>CLI: copilot plugin install hve-squad@hve-squad-plugin CLI->>Repo: fetch plugin.json, then agents/, skills/, hooks.json, .mcp.json CLI->>Reg: register 27 agents + squad skill + hooks + MCP server U->>CLI: copilot plugin install hve-squad-hve-core@hve-squad-plugin CLI->>Core: fetch content at the pinned commit SHA CLI->>Reg: register hve-core agents + skills Reg-->>CLI: namespaces active, squad roles resolvable U->>CLI: hve-squad:squad-coordinator ... CLI-->>U: dispatches Squad Coordinator, which can now reach hve-core roles