# Team Adoption and Governance of HVE Core: Phased Rollout and Governance Best Practices

> Learn team adoption and governance best practices for HVE Core. Discover phased rollouts, naming conventions, contribution models, and key metrics for success.

- Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core)
- Tags: best-practices
- Published: 2026-03-09

---

**Successful team adoption and governance of HVE Core requires a three-phase incremental rollout, strict kebab-case naming conventions, a liberal contribution governance model with defined artifact ownership, and continuous measurement of both quantitative usage metrics and qualitative team confidence.**

The microsoft/hve-core repository provides a comprehensive framework for customizing GitHub Copilot through instructions, agents, prompts, and skills. Implementing effective team adoption and governance of HVE Core ensures that AI-assisted development workflows remain consistent, maintainable, and scalable across engineering organizations. The following best practices are derived directly from the official Team Adoption guide in [`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) and the project’s [`GOVERNANCE.md`](https://github.com/microsoft/hve-core/blob/main/GOVERNANCE.md) charter.

## Implement a Three-Phase Incremental Rollout

According to [`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) (¶18‑33), teams should adopt HVE Core incrementally to maximize ROI and build confidence before investing in complex artifacts.

**Phase 1 – Instructions:** Target `.github/*.instructions.md` files to shape Copilot’s baseline behavior with minimal effort. Write 2‑3 instruction files covering coding standards, PR conventions, or commit-message formats.

**Phase 2 – Agents & Prompts:** Introduce `.github/agents/` for repeatable multi-turn workflows (e.g., code-review agents) and `.github/prompts/` for one-shot tasks (e.g., boilerplate generators). Build an agent for your most common review pattern.

**Phase 3 – Skills & Collections:** Package domain knowledge into `.github/skills/` and `collections/*.collection.yml` files for organization-wide reuse. Bundle related agents, prompts, and instructions into a collection (e.g., [`ado.collection.yml`](https://github.com/microsoft/hve-core/blob/main/ado.collection.yml)).

This phased approach ensures that lightweight instructions deliver immediate value before teams invest in sophisticated multi-turn agents.

## Establish Strict Naming Conventions

The adoption guide enforces kebab-case patterns to ensure consistency across artifacts ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶56‑62).

- **Instructions:** `{topic}.instructions.md` (e.g., [`python-script.instructions.md`](https://github.com/microsoft/hve-core/blob/main/python-script.instructions.md))
- **Agents:** `{workflow}.agent.md` (e.g., [`code-review.agent.md`](https://github.com/microsoft/hve-core/blob/main/code-review.agent.md))
- **Prompts:** `{action}.prompt.md` (e.g., [`generate-tests.prompt.md`](https://github.com/microsoft/hve-core/blob/main/generate-tests.prompt.md))
- **Skills:** `{skill-name}/SKILL.md` (e.g., [`pr-reference/SKILL.md`](https://github.com/microsoft/hve-core/blob/main/pr-reference/SKILL.md))
- **Collections:** `{collection-id}.collection.yml` plus [`.collection.md`](https://github.com/microsoft/hve-core/blob/main/.collection.md) (e.g., [`ado.collection.yml`](https://github.com/microsoft/hve-core/blob/main/ado.collection.yml))

All collection IDs must be unique, lowercase, and kebab-cased (e.g., `coding-standards`, `security-planning`) per [`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) (¶66‑73).

## Define Your Governance Model

The project follows a **liberal contribution model** with three defined roles: **Maintainer**, **Triage Contributor**, and **Contributor** ([`GOVERNANCE.md`](https://github.com/microsoft/hve-core/blob/main/GOVERNANCE.md) ¶27‑39). Effective governance requires implementing these specific practices:

**Artifact Ownership:** Assign a dedicated owner per collection and use `.github/CODEOWNERS` to route reviews automatically.

**Mandatory Review Process:** Require PR review for any change to instructions, agents, or skills. Before merging, contributors must run `npm run lint:all` and `npm run plugin:generate` to validate changes ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶104‑112).

**Conflict Resolution:** When multiple artifacts apply, resolution follows this priority order: [`copilot-instructions.md`](https://github.com/microsoft/hve-core/blob/main/copilot-instructions.md) → more specific `applyTo` patterns → artifact-owner decision ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶118‑122).

**Structured Change Management:** Follow the pipeline: create → prompt-build → prompt-analyze → lint → update manifests → plugin generation → PR ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶61‑68).

**Deprecation Workflow:** Mark obsolete artifacts with `maturity: deprecated`, add a deprecation notice via Prompt Builder, communicate timelines, and eventually remove the artifact ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶81‑95).

## Onboard New Team Members Systematically

A repeatable onboarding checklist accelerates adoption and reduces support burden ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶37‑53):

1. **Getting Started:** Direct new hires to the official Getting Started guide.
2. **First Interaction:** Have them run an existing agent (e.g., the RPI workflow).
3. **Create an Instruction:** Follow the walkthrough to create a simple [`.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.instructions.md) file.
4. **Run Prompt Builder:** Use `/prompt-build` and `/prompt-analyze` to generate and validate the file.
5. **Submit PR:** Go through the standard review process with mandatory linting.

Pairing new members with an experienced mentor is strongly recommended.

## Measure Adoption Success

Collect both quantitative and qualitative indicators during sprint retrospectives ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶66‑93):

- **Quantitative metrics:** Artifact count, invocation frequency, error-rate reduction, and onboarding velocity.
- **Qualitative metrics:** Team confidence surveys, consistency checks, and feedback quality assessments.

Regularly review these metrics and adjust the adoption roadmap accordingly.

## Tailor Adoption by Role

The [`docs/customization/README.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/README.md) (¶71‑86) maps nine defined roles to focused entry points:

- **Engineer:** Start with Instructions, then build agents for code review.
- **TPM:** Begin with Prompts & Collections to automate status-report generation.
- **Tech Lead:** Combine Instructions and Agents to define architecture-review workflows.
- **Security Architect:** Implement Skills and Instructions for security-review agents.
- **Data Scientist:** Package analysis workflows using Skills and Prompts.
- **SRE / Ops:** Codify runbook standards with Instructions and Environment configurations.
- **Business PM:** Standardize sprint-planning prompts using Prompts and Team Adoption guides.
- **New Contributor:** Rapid onboarding via Instructions and Environment setup.
- **Utility:** Assemble cross-team toolkits using Collections and the Build System.

## Maintain Continuous Improvement

Sustainable governance requires active maintenance cycles:

**Feedback Loops:** Open a shared channel or document for customization gaps; integrate suggestions into the quarterly review cycle ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶88‑93).

**Deprecation Audits:** Periodically audit low-usage artifacts and move them to the *experimental* or *deprecated* maturity level ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶84‑90).

## Practical Implementation Examples

### Sample Instruction File

Create [`.github/instructions/python-script.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.github/instructions/python-script.instructions.md) following the kebab-case convention:

```markdown
---
title: Python-script coding style
description: Enforce PEP 8 formatting and naming conventions
applyTo: "**/*.py"
---

# Use 4-space indentation

# Prefer snake_case for variables and functions

# Run `black` on every PR

```

### Prompt Builder Workflow

Generate and validate new artifacts using the CLI commands referenced in the change-management pipeline:

```bash

# Generate a new agent skeleton

/prompt-build --type agent --name code-review.agent.md --reference agents/template.agent.md

# Analyze quality

/prompt-analyze code-review.agent.md

# Validate before PR

npm run lint:all
npm run plugin:generate

```

### Collection Manifest Structure

Define reusable packages in [`collections/ado.collection.yml`](https://github.com/microsoft/hve-core/blob/main/collections/ado.collection.yml):

```yaml
id: ado
name: Azure DevOps Integration
description: Agents, prompts, and skills that automate common ADO workflows
artifacts:
  agents:
    - .github/agents/ado/work-item.agent.md
  prompts:
    - .github/prompts/ado/create-pr.prompt.md
  skills:
    - .github/skills/ado/ado-skill/SKILL.md

```

## Summary

- **Adopt incrementally** through three phases: Instructions → Agents/Prompts → Skills/Collections.
- **Enforce kebab-case naming** for all artifacts to ensure consistency and parseability.
- **Implement liberal governance** with CODEOWNERS, mandatory PR reviews, and the lint/plugin generation pipeline.
- **Follow the change-management workflow**: create → build → analyze → lint → generate → PR.
- **Measure both quantitative usage** (artifact count, frequency) **and qualitative confidence** (surveys, consistency).
- **Tailor onboarding** by role, with Engineers starting at Instructions and TPMs at Prompts.
- **Maintain artifacts** through regular deprecation audits and quarterly feedback integration.

## Frequently Asked Questions

### What is the recommended first step for team adoption of HVE Core?

Start with **Phase 1: Instructions**. Create 2‑3 lightweight [`.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.instructions.md) files in `.github/` to establish coding standards or PR conventions. This provides immediate ROI and builds team confidence before investing in complex agents or skills, as detailed in [`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) (¶18‑33).

### How does HVE Core resolve conflicts between multiple instructions?

Conflict resolution follows a strict priority order defined in [`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) (¶118‑122): first, repository-level [`copilot-instructions.md`](https://github.com/microsoft/hve-core/blob/main/copilot-instructions.md); second, more specific `applyTo` glob patterns; third, the artifact-owner’s decision. This hierarchy ensures predictable behavior when multiple customization files target the same codebase.

### What commands must run before merging changes to HVE Core artifacts?

Every PR affecting instructions, agents, or skills must execute `npm run lint:all` and `npm run plugin:generate` before merging ([`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) ¶104‑112). These commands validate syntax, check naming conventions, and regenerate plugin manifests to ensure repository consistency.

### How do you deprecate an artifact in HVE Core?

Mark the artifact with `maturity: deprecated` in its frontmatter, add a deprecation notice using the Prompt Builder, communicate the timeline to stakeholders, and eventually remove the file after the sunset period. This structured workflow is documented in [`docs/customization/team-adoption.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/team-adoption.md) (¶81‑95).