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

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 and the project’s GOVERNANCE.md charter.

Implement a Three-Phase Incremental Rollout

According to 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).

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 ¶56‑62).

• Instructions: {topic}.instructions.md (e.g., python-script.instructions.md)
• Agents: {workflow}.agent.md (e.g., code-review.agent.md)
• Prompts: {action}.prompt.md (e.g., generate-tests.prompt.md)
• Skills: {skill-name}/SKILL.md (e.g., pr-reference/SKILL.md)
• Collections: {collection-id}.collection.yml plus .collection.md (e.g., 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 (¶66‑73).

Define Your Governance Model

The project follows a liberal contribution model with three defined roles: Maintainer, Triage Contributor, and Contributor (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 ¶104‑112).

Conflict Resolution: When multiple artifacts apply, resolution follows this priority order: copilot-instructions.md → more specific applyTo patterns → artifact-owner decision (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 ¶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 ¶81‑95).

Onboard New Team Members Systematically

A repeatable onboarding checklist accelerates adoption and reduces support burden (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 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 ¶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 (¶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 ¶88‑93).

Deprecation Audits: Periodically audit low-usage artifacts and move them to the experimental or deprecated maturity level (docs/customization/team-adoption.md ¶84‑90).

Practical Implementation Examples

Sample Instruction File

Create .github/instructions/python-script.instructions.md following the kebab-case convention:

---
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:

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

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 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 (¶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 (¶118‑122): first, repository-level 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 ¶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 (¶81‑95).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}