Team Adoption and Governance

Adoption Strategy

Adopt HVE Core incrementally. A phased approach lets your team build confidence with simpler artifacts before advancing to complex ones.

Phase 1: Instructions

Start with instructions files. They require the least effort and deliver immediate value by shaping Copilot's behavior for every conversation. Write two or three instructions covering your team's coding standards, commit message format, or PR conventions.

Phase 2: Agents and Prompts

Once the team is comfortable with instructions, introduce custom agents for repeatable workflows (code reviews, research tasks, implementation patterns) and prompts for one-shot operations (generating boilerplate, formatting outputs).

Phase 3: Skills and Collections

Package domain knowledge into skills for complex, multi-step workflows. Bundle related artifacts into collections for distribution and reuse across teams.

Measuring Adoption Progress

Track adoption through observable indicators:

• Number of team members using custom agents in daily work
• Frequency of instructions and prompt invocations
• Reduction in repetitive manual tasks
• Quality improvements in generated code and documentation

Naming Conventions

Consistent naming makes artifacts discoverable and their purpose clear at a glance. Follow kebab-case patterns throughout.

File Naming Patterns

Artifact Type	Pattern	Example
Instructions	{topic}.instructions.md	python-script.instructions.md
Agents	{workflow}.agent.md	code-review.agent.md
Prompts	{action}.prompt.md	generate-tests.prompt.md
Skills	{skill-name}/SKILL.md	pr-reference/SKILL.md
Collections	{collection-id}.collection.yml and .collection.md	ado.collection.yml

Collection IDs

Collection IDs serve as directory names throughout .github/ and must be unique, lowercase, and kebab-cased. Choose IDs that reflect the domain or team the collection serves:

• ado for Azure DevOps integration
• coding-standards for language-specific conventions
• security-planning for security architecture workflows

Directory Organization

Place artifacts under their collection ID in the appropriate .github/ subdirectory:

.github/
  agents/{collection-id}/
  instructions/{collection-id}/
  prompts/{collection-id}/
  skills/{collection-id}/

Artifacts at the root of .github/agents/, .github/instructions/, .github/prompts/, or .github/skills/ (without a subdirectory) are treated as repo-specific and excluded from collection manifests, plugin generation, and extension packaging.

Governance Model

Ownership

Assign clear ownership for each artifact category:

• A designated maintainer or team owns each collection
• Individual instructions files can have separate owners when they span multiple domains
• The copilot-instructions.md file at the repository root reflects cross-cutting concerns and requires broader review

Review and Approval

Treat Copilot customization files with the same rigor as production code:

• Require pull request review for changes to instructions, agents, and skills
• Use CODEOWNERS to route reviews to artifact owners
• Validate changes with npm run lint:all before merging
• Run npm run plugin:generate after modifying collection manifests

Handling Conflicting Instructions

When multiple instructions files provide contradictory guidance, resolution follows priority order:

1. copilot-instructions.md highest-priority rules override everything
2. More specific applyTo patterns take precedence over broader ones
3. When two instructions at the same specificity conflict, the artifact owner resolves the conflict through a pull request

Onboarding New Team Members

Step-by-Step Onboarding

1. Point new members to the Getting Started guide for installation.
2. Walk through a first interaction using an existing agent (the RPI workflow is a good starting point).
3. Show how instructions files shape Copilot behavior by editing one together.
4. Introduce the team's custom agents and explain when to use each.
5. Share the team's naming conventions and governance expectations.

First Customization Walkthrough

Have new team members create their first instructions file as an onboarding exercise. A simple coding-style instruction works well:

1. Create a file at .github/instructions/{collection-id}/my-style.instructions.md with minimal frontmatter (description and applyTo fields)
2. Run /prompt-build and reference an existing instructions file the team uses, so Prompt Builder generates the body following established patterns
3. Run /prompt-analyze against the generated file to check for quality gaps
4. Iterate with /prompt-build to address any issues the analysis found
5. Test by opening a Copilot chat and verifying the instructions influence responses
6. Submit the file for review following the team's PR process

TIP

Pair the new member with someone experienced during their first customization. Seeing how Prompt Builder generates and refines an artifact builds intuition for the full authoring workflow.

Change Management

Introducing New Artifacts

Follow a structured process when adding new instructions, agents, or skills:

1. Create the artifact file with minimal frontmatter in a feature branch
2. Run /prompt-build with reference files to generate the body
3. Run /prompt-analyze and iterate with /prompt-build until quality checks pass
4. Run npm run lint:all to validate formatting and frontmatter
5. Update affected collection manifests in collections/
6. Run npm run plugin:generate to regenerate plugin outputs
7. Submit a pull request with clear description of what the artifact does and why

Communication Patterns

Announce changes that affect team workflows:

• New agents: share the agent name, purpose, and invocation example
• Modified instructions: explain what changed and why
• Deprecated artifacts: provide migration steps and a timeline

Deprecation Workflow

HVE Core uses maturity levels to signal artifact lifecycle stage. Transition artifacts through these stages:

Level	Meaning
experimental	Early-stage artifact; behavior may change without notice
preview	Functional but subject to refinement based on feedback
stable	Production-ready; changes follow semver-style considerations
deprecated	Scheduled for removal; migration path documented

To deprecate an artifact:

1. Update the artifact's frontmatter to include maturity: deprecated
2. Run /prompt-build to add a deprecation notice pointing to the replacement
3. Announce the deprecation and provide a migration timeline
4. Remove the artifact after the agreed-upon transition period

Role-Based Adoption Paths

Each role enters customization at a different level. These paths provide starting points and progression for each of the nine roles.

Engineer

1. Create an instructions file for your team's coding standards
2. Build a custom agent for your most common code review patterns
3. Package domain knowledge into a skill with scripts and references

TPM (Technical Program Manager)

1. Use the RPI workflow to research and document project status
2. Create prompts for generating status reports and risk summaries
3. Build an agent that tracks cross-team dependencies

Tech Lead

1. Write instructions for architecture decision conventions
2. Create a code review agent that enforces team standards
3. Establish a collection that bundles your team's full workflow

Security Architect

1. Add security-focused instructions for threat modeling
2. Create a security review agent that checks for common vulnerabilities
3. Build a skill that integrates with security scanning tools

Data Scientist

1. Create instructions for notebook conventions and data handling
2. Build prompts for exploratory data analysis patterns
3. Package statistical methodology into a skill with reference datasets

SRE/Operations

1. Write instructions for runbook format and incident response
2. Create an agent for infrastructure review workflows
3. Build a collection integrating monitoring, alerting, and deployment tools

Business PM (Product Manager)

1. Use prompts to generate user story drafts from requirements
2. Create an agent for requirements analysis
3. Build a Design Thinking workflow with custom agents

New Contributor

1. Follow the Getting Started guide and complete your first interaction
2. Create your first instructions file with the onboarding walkthrough above
3. Propose a new agent or skill for a workflow gap you've identified

Utility

1. Use existing prompts and agents without modification
2. Customize instructions for your specific workflow context
3. Contribute improvements to shared collections based on usage patterns

Measuring Success

Quantitative Indicators

• Artifact count: track the number of instructions, agents, skills, and collections over time
• Invocation frequency: monitor how often team members activate custom agents and prompts
• Error reduction: measure before-and-after rates for common mistakes the customizations target
• Onboarding velocity: compare time-to-productivity for members who use HVE Core versus those who do not

Qualitative Indicators

• Team confidence: survey whether members feel more effective with AI-assisted workflows
• Consistency: review whether generated outputs (code, docs, PRs) follow team conventions more reliably
• Feedback quality: assess whether Copilot suggestions require fewer manual corrections

Feedback Collection

Establish regular feedback cycles:

• Include Copilot customization effectiveness in sprint retrospectives
• Maintain a shared channel or document for reporting customization gaps
• Review and adjust artifacts quarterly based on accumulated feedback
• Track which artifacts are rarely used and consider deprecation

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.