Concepts

The terms at a glance#

How the pieces fit#

flowchart LR
    Q["Squad Coach<br/>advice only, no state"] -.-> A
    A["init<br/>create the team"] --> B["Work request<br/>research, plan, implement, review"]
    B --> C["Deliverables<br/>research, plans, changes, reviews, docs"]
    B --> D["Team memory<br/>decisions.md, history/, state.json"]
    D --> E["New chat?<br/>resume from the files"]
    E --> B
    A -.-> F["promote<br/>optional: one team becomes a federation"]
      

HVE Squad and HVE Core#

HVE Core is a library of agents, prompts, instructions and skills for structured engineering work: research, planning, implementation, review, requirements, architecture and more. Used directly, you pick one agent at a time.

HVE Squad sits on top of it. It adds coordinators that read your request, choose the roles that should handle it, dispatch the matching HVE Core agents, and write down what happened. HVE Squad pins a specific HVE Core revision and keeps that pin aligned with each of its releases, so the agents it dispatches are the ones that release was tested with.

A practical rule when something surprises you: if the question is about how a research, plan or review agent itself behaves, it is an HVE Core convention. If it is about teams, profiles, packs, routing, approvals or the files the squad writes, it is HVE Squad.

Agents and skills#

An agent is a persona with a job and a set of tools. A skill is a reusable procedure that an agent loads when it needs it, such as the HVE Core research, planning, implementation and review skills.

That is why you will see two shapes in a roster. A Squad-prefixed worker such as Squad Researcher, Squad Lead, Squad Implementor or Squad Reviewer is a thin agent that loads the matching HVE Core skill. Other roles, such as the BRD Builder or the UX UI Designer, dispatch an HVE Core agent directly. This is configured explicitly in the team's roster (team.md); the model does not decide it on the fly.

You only ever select a few agents yourself. The rest are dispatched for you:

More specialist agents, such as the governance report, document search and shared-learning agents, are listed in Usage. Researcher, Lead, Implementor, Reviewer and the other roles are never selected by you: the coordinator dispatches them.

Teams and federations#

A team (the documentation also says squad) is one roster of agents that share a plan, a decision log and a history. It lives in your repository under .copilot-tracking/squad/ and is created by init.

A federation is several teams in the same repository, side by side. Each team keeps its own roster, decisions and history under .copilot-tracking/squad/members/<name>/, and a registry (federation.md) plus a routing table (meta-routing.md) decide which team receives a request. You work with a federation through the Squad Federation Coordinator.

Start with one team. Choose a federation only when two or more workstreams have different owners, deliverables, cadences or access boundaries, for example a product team and a platform team that ship separately. A technology specialty is not a reason to federate: that is a pack. The full decision rule is in Profile, pack, or federation?.

Every team in a federation has a unique name that is also its folder name and the value you pass as squad=<name>. Names use kebab-case: lowercase words joined by hyphens, such as azure-migration.

Messages you send#

You talk to the squad by selecting an agent and sending it a chat message. The messages fall into a few kinds, and only the keyword at the start tells them apart. No slash command is needed in any host: the host tabs in this documentation show which agent to select and the exact text to send.

init, promote and work requests#

In chat, init and promote always ask you to confirm before anything is written, and they do not take a mode. (Watch Mode has no human in the loop, so it bootstraps its own teams; see Usage.) Add context after init to help the coordinator propose a fitting profile, and say that it should stop once the team is ready, so that it does not go on to start work:

/squad init Use the documents in docs/ as context. Set up one team for this planning work, and stop once the team is ready; I will send the work request next.

How to write a message#

A message has up to three parts: an optional keyword (init or promote) at the start, optional name=value options, and your request in plain language. In an agent chat you can write the request as ordinary text. The request="..." wrapper you see in some examples is the name of the input that prompt files use to carry the same text, and it is optional here.

/squad mode=autopilot Add input validation to the login form, with tests

Options go before or after your request. The examples put them first, on their own line, because that is easiest to read.

Message reference#

These are all the inputs the shipped Squad prompts accept. Anything not listed here is ordinary text for the team.

The Squad Coach accepts request= and host=vscode|cli|app only; both are optional.

Profiles and packs#

A profile is the team you are building: a ready-made cast of roles for one kind of work. Packs are optional extra specialists that you may add on top. You pick exactly one profile and zero or more packs.

If you choose product, you did not choose a feature: you chose a team made of a researcher, a lead, a developer, a tester and a scribe, plus the roles for requirements, design, product ownership, presentations and experiments. A pack never replaces that team; it adds a few technology specialists to it.

Choosing a profile#

The exact members of every profile are listed in Usage → Profiles. A profile is a starting set, not a ceiling: any role in the cast can be added later by asking the coordinator. When you are not sure, accept the profile the coordinator proposes from your repository and your request.

Packs are optional#

A pack adds the specialists for a technology your project is built on: power-platform, m365-copilot, aws or foundry. Skip packs unless your project uses that technology. The initialization question can list every registered pack, which makes it look like a recommendation; it is a menu, and each one is optional. Choosing no pack is a normal answer.

Most clients let you reply to a question in your own words instead of picking a listed option. Use that when you do not know what an option means: ask the coordinator to explain it and why your project would need it. Packs can be added or removed later without recreating the team or losing its history. A Power Platform app that also needs an audit trail is one team made of profile compliance plus pack power-platform.

Interactive and autopilot#

The squad can ask you before every step, or run the whole pipeline and ask only for the decisions that matter. You choose per work request by adding mode= to the message; there is no separate setting.

init and promote never use a mode: you confirm each proposal. The complete behavior is in Usage → Autonomy modes.

Squad autopilot is not your client's approvals#

Two separate layers decide when you are asked something. The squad's mode decides which work decisions it brings to you: a plan, a deployment, the final outcome. Your client's permission level decides whether Copilot asks before it edits a file, runs a command or calls a tool. mode=autopilot does not change the second layer.

That is why a long autopilot run can pause on prompts such as keeping file changes or allowing a command, even though the squad is not waiting for you. Approve them, or raise the permission level for this session. In VS Code, choose the permission level in the chat input, or send /yolo to bypass approvals for the current session (/disableYolo restores them); see Manage approvals and permissions. In Copilot CLI, use /allow-all (alias /yolo) in the session, or start with --allow-all-tools; see the CLI command reference.

Where the squad keeps its memory#

The chat is not the memory. The squad writes what it decides and does into files in your repository, and reads them back at the start of every turn. You are not tied to one chat window: the context travels with the repository.

The state folder#

Everything lives under .copilot-tracking/squad/ (or members/<name>/ for a federation member):

A federation adds federation.md and meta-routing.md at the top, and each member keeps the same files under its own folder. Because decisions.md and the history files are append-only, they work as an audit trail of how a result came to be.

Where deliverables go#

Each role writes its artifact to a fixed folder, so the squad can check that a stage really produced its output. The agent's history entry names the file it wrote on its Deliverable: line.

In a federation, every .copilot-tracking/ location moves under the member's folder, for example .copilot-tracking/squad/members/product/plans/. Only docs/ and outputs/ stay at the repository root, because published documentation and data outputs belong to the whole repository. Roles that return findings to the coordinator rather than a file, such as the cost manager and the deployer, are recorded in the history instead.

Change where a role writes#

1. Open .copilot-tracking/squad/team.md (or the member's own team.md in a federation).
2. Find the role's row and edit its Deliverable Root cell. Use a path relative to the repository root, in the same shape as the other cells, for example research-notes/.
3. Send your next request. The coordinator passes each agent the root it reads from the roster row, so the change applies to the very next dispatch with no re-initialization, and a roster refresh keeps your edit. The writing agent creates the folder; you do not have to.

Do not use .., an absolute path or ~. In a federation, keep a custom root inside docs/, outputs/ or the member's own folder: a deliverable written outside its team's folder has escaped its root, and the coordinator treats that as a failed stage and re-dispatches it. Edit only this column by hand: the other columns are maintained by the squad, so ask the coordinator when you want a role, a model or a name changed.

After the next dispatch, open the agent's history/<agent>.md and check that its Deliverable: path is the one you set. An artifact found at the agent's default path instead means the dispatch did not follow the roster; report it rather than accepting the location.

Starting a new chat is safe#

The coordinator reads the state folder at the start of every turn, so a new conversation resumes exactly where the files say the work is. Starting a new chat after init and between large stages is safe and often better: a fresh conversation keeps the context small, and nothing is lost. In the new chat, open the same repository folder, select the same agent again and say what you want next, for example Summarize where we are and continue from the last completed stage.

You never need to repeat init: it applies only when no team exists yet (or, with a federation, to add a team). The files are ordinary files in your repository, so you can commit or copy the folder to continue on another machine or to hand the project to a colleague.

What the squad works from#

There is no required folder structure. The team works from your repository and from whatever you point it at: requirements, specifications, transcripts, an existing codebase. Name those files in your message, as the hands-on workshop does with its knowledge-docs/ folder. That folder is that workshop's own input, not a layout HVE Squad asks you to create.

When a run is grounded in written inputs, the intake gate checks them before planning. When nothing is written down yet and your team is product or full, the discovery gate offers a short interview that produces the brief. See Discovery gate and Requirements intake gate.

Squad Coach#

The Squad Coach is an advice-only agent. It reads the code and documentation of the version you installed, looks at your project, and answers with a recommendation and a runbook of copy-ready messages. It never initializes a team, dispatches work, writes a file or changes your setup.

• Who it is for: anyone new to HVE Squad, or unsure which team shape, profile, packs or message fits a goal. It works before any team exists.
• When to skip it: you already know what you want (initialize one team, then send a work request), or you are following a fixed runbook such as the hands-on workshop, which deliberately uses fixed messages so that results can be compared.
• The words it uses: the terms on this page. If one is new, read its section here or ask the Coach to explain it in plain words before you continue.

See Getting Started → Squad Coach for how to start a conversation in your client.

Other words you will meet#