Getting Started

Prerequisites

• PowerShell 7+
• Git
• APM CLI installed and available in PATH
• Access to the microsoft/hve-core repository
• Authenticated GitHub access (gh auth login or GITHUB_TOKEN) — strongly recommended; see the note in step 1

1. Install the package

Run apm install from the root of the project you want the squad in.

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 branch

Option 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.

2. Run 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/. Invoke it with the /squad prompt in Copilot Chat:

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

The / picker shows two entries named squad: the prompt ("Hands a request to the Squad Coordinator…"), which runs the squad, and the skill ("Operating procedure for…"), which only loads the procedure as context. Pick the prompt.

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.

3. Rebuild (re-deploy) after updating

To pull a newer version of the package or refresh your deployed assets, re-run install with the version tag you want (include --target copilot if you have not declared targets: in your project's apm.yml):

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

To try something that has been merged but not released yet, install the rolling pre-release instead — apm install "Peter-N91/hve-squad#vX.Y.z-pre". Its exact tag is on the Releases page, marked as a pre-release. The tag moves on every merge, so use it to test and pin a released version for anything you depend on.

apm install re-flattens the package into .github/. Your squad state under .copilot-tracking/squad/ is created per-project and is never packaged, so re-installing does not overwrite your roster, routing, decisions, or history.

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.