Installing HVE-Core

HVE-Core provides GitHub Copilot customizations (custom agents, instructions, and prompts) that enhance your development workflow. This guide helps you choose the right installation method for your environment.

Recommended: VS Code Extension ⭐

For most users, the simplest method is to install directly from the VS Code Marketplace:

VS Code → Extensions → Search "HVE Core" → Install

Or visit: HVE Core on Marketplace

Why choose the extension

✅ Zero configuration required
✅ Automatic updates via VS Code
✅ Works everywhere (local, devcontainers, Codespaces)
✅ No project files needed
✅ Instant availability

When to use alternatives

❌ You need to customize components → Use custom installation methods below
❌ Team needs version control → Use Submodule
❌ Contributing to HVE-Core → Use Peer Clone

See Extension Installation Guide for complete documentation.

Custom Installation Methods

If you need customization or version control of HVE-Core, choose from the methods below.

Quick Start

Starter prompt: "Help me choose how to install this library"

Open Copilot Chat, select the hve-core-installer agent, and use this prompt. The agent will ask three questions about your environment and recommend the best method.

Help Me Choose

Answer these questions to find your recommended installation method:

What's your development environment?
- Local VS Code (no devcontainer)
- Local devcontainer (Docker Desktop)
- GitHub Codespaces
- Both local and Codespaces
Solo or team development?
- Solo: Just you, no version control of HVE-Core needed
- Team: Multiple people, need reproducible setup
Update preference?
- Auto: Always get latest HVE-Core
- Controlled: Pin to specific version, update explicitly

Decision Matrix

Environment	Team	Updates	Recommended Method
Any (simplest)	Any	Auto	VS Code Extension ⭐
Local (no container)	Solo	Manual	Peer Directory Clone
Local (no container)	Team	Controlled	Submodule
Local devcontainer	Solo	Auto	Git-Ignored Folder
Local devcontainer	Team	Controlled	Submodule
Codespaces only	Solo	Auto	GitHub Codespaces
Codespaces only	Team	Controlled	Submodule
Both local + Codespaces	Any	Any	Multi-Root Workspace
Advanced (shared install)	Solo	Auto	Mounted Directory

⭐ VS Code Extension is the recommended method for most users who don't need customization.

Collection Packages

HVE-Core organizes artifacts into role-based collections. The VS Code extension installs the Full collection. Clone-based methods let you select any collection during setup.

Collection	Collection ID	Maturity	Description
Full ⭐	`hve-core-all`	Stable	All stable artifacts (recommended for most)
HVE Core Workflow	`hve-core`	Stable	RPI workflow with Git commit, merge, and pull request prompts
Azure DevOps	`ado`	Stable	Work item management, build monitoring, and PR creation
Coding Standards	`coding-standards`	Stable	Language-specific instructions for bash, Bicep, C#, Python, etc.
Data Science	`data-science`	Stable	Data specs, Jupyter notebooks, and Streamlit dashboards
Design Thinking	`design-thinking`	Preview	AI-enhanced Design Thinking coaching across nine methods
GitHub Backlog	`github`	Stable	Issue discovery, triage, sprint planning, and backlog execution
Installer	`installer`	Stable	Interactive installer agent for workspace configuration
Project Planning	`project-planning`	Stable	PRDs, BRDs, ADRs, and architecture diagrams
Security Planning	`security-planning`	Stable	Security plans, incident response, and risk assessment
Experimental	`experimental`	Experimental	Artifacts not yet promoted to stable collections

Extension Installation (Full Collection)

The VS Code Marketplace extension installs the Full collection containing all stable artifacts. This is the recommended approach for most users.

Clone Methods (Collection Filtering)

Clone-based installation methods support collection-based agent filtering through the installer agent:

Clone the repository using your preferred method
Run the hve-core-installer agent
In Phase 7 (Agent Customization), select your role-based collection or install all agents

The installer reads collection assignments from the collection manifests (collections/*.collection.yml) and copies only the agents assigned to your selected collection. Agents marked for all collections are always included.

NOTE

Collection filtering applies to agents only. Copying of related prompts, instructions, and skills based on collection is planned for a future release.

Quick Decision Tree

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  Want the simplest setup?                                       │
│  └─ Yes ──────────────────────────────► VS Code Extension ⭐   │
│                                                                 │
│  Need to customize HVE-Core?                                    │
│  ├─ Local VS Code only ──────────────► Peer Directory Clone    │
│  ├─ Local devcontainer only ─────────► Git-Ignored Folder      │
│  ├─ Codespaces only ─────────────────► GitHub Codespaces       │
│  └─ Both local + Codespaces ─────────► Multi-Root Workspace    │
│                                                                 │
│  Working in a team?                                             │
│  └─ Yes, need version control ───────► Submodule               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Installation Methods

Simplest Method (Recommended for Most Users)

Method	Best For	Complexity
VS Code Extension ⭐	Anyone wanting zero-config setup	Minimal

Consumer Methods (Customization + Version Control)

These methods are for projects that want to use and potentially customize HVE-Core's components:

Method	Best For	Complexity
Multi-Root Workspace	Any environment, portable	Low
Submodule	Teams needing version control	Medium

Developer Methods

These methods are for HVE-Core contributors or advanced scenarios:

Method	Best For	Complexity
Peer Directory Clone	Local VS Code, solo	Low
Git-Ignored Folder	Local devcontainer, solo	Low
Mounted Directory	Advanced devcontainer sharing	High
GitHub Codespaces	Codespaces-only projects	Medium

Using the Installer Agent

The hve-core-installer agent automates any installation method:

Open GitHub Copilot Chat in VS Code (Ctrl+Alt+I)
Select hve-core-installer from the agent picker
Answer the environment detection questions
The agent executes your chosen method

The agent handles:

Environment detection (Local VS Code, Devcontainer, Codespaces)
Repository cloning or configuration
VS Code settings updates
Devcontainer configuration
Validation of the installation

Validation

After installation, verify everything works:

Open GitHub Copilot Chat (Ctrl+Alt+I)
Click the agent picker dropdown
Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder)
Select an agent and submit a test prompt

Run the installer in validation mode:

"Validate my HVE-Core installation"

Post-Installation: Update Your .gitignore

HVE-Core agents create ephemeral workflow artifacts in a .copilot-tracking/ folder within your project. These files include research documents, implementation plans, PR review tracking, and other machine-generated content that should typically not be committed to version control.

Add this line to your project's `.gitignore`

.copilot-tracking/

IMPORTANT

This applies to all installation methods (extension, submodule, peer clone, etc.). The .copilot-tracking/ folder is created in your project directory, not in HVE-Core itself.

What gets stored there

Research documents from task-researcher
Implementation plans from task-planner
PR review artifacts from pr-review
Work item planning files for ADO workflows
Temporary prompt files used by agents

These artifacts are useful during your workflow session but are ephemeral by design. They help agents maintain context across sessions without polluting your repository history.

MCP Server Configuration (Optional)

Some HVE-Core agents use MCP (Model Context Protocol) servers to integrate with Azure DevOps, GitHub, or documentation services. These are optional enhancements; agents work without MCP configuration.

If you use agents like ado-prd-to-wit or github-backlog-manager, see MCP Server Configuration for setup instructions. That guide includes:

Which agents require which MCP servers
Complete configuration templates
Method-specific placement notes (extension, submodule, Codespaces, etc.)
Troubleshooting for common issues

Next Steps

Your First Workflow - Try HVE-Core with a real task
RPI Workflow - Research, Plan, Implement methodology
Contributing - Contribute to HVE-Core

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

Recommended: VS Code Extension ⭐​

Why choose the extension​

When to use alternatives​

Custom Installation Methods​

Quick Start​

Help Me Choose​

Decision Matrix​

Collection Packages​

Extension Installation (Full Collection)​

Clone Methods (Collection Filtering)​

Quick Decision Tree​

Installation Methods​

Simplest Method (Recommended for Most Users)​

Consumer Methods (Customization + Version Control)​

Developer Methods​

Using the Installer Agent​

Validation​

Post-Installation: Update Your .gitignore​

Add this line to your project's .gitignore​

What gets stored there​

MCP Server Configuration (Optional)​

Next Steps​