hve-core/docs/getting-started/methods/multi-root.md at main · microsoft/hve-core

title

Multi-Root Workspace Installation

description

Set up your enterprise fork of HVE Core using VS Code multi-root workspaces

sidebar_position

author

Microsoft

ms.date

2026-10-07

ms.topic

how-to

keywords

multi-root workspace

installation

github copilot

codespaces

devcontainer

enterprise fork

estimated_reading_time

Forking HVE Core lets your enterprise customize agents, instructions, and skills for your organization while staying connected to upstream improvements. Multi-root workspaces bring that fork into any project workspace, giving teams a portable configuration that works across Local VS Code, Devcontainers, and Codespaces.

When to Use This Method

✅ Use this when:

Your enterprise maintains a fork of HVE Core with org-specific customizations
You need a single configuration that works across Local VS Code, Devcontainers, and Codespaces
Teams share a common set of customized agents, skills, and instructions
You want to pull upstream improvements on your own schedule

❌ Consider alternatives when:

Your team needs version-pinned dependencies without a fork → Submodule
You're contributing back to HVE Core itself → Peer Clone

How It Works

Your enterprise forks the microsoft/hve-core repository, adds org-specific agents, prompts, and instructions, then uses a .code-workspace file to bring that fork into any project as a secondary root. VS Code treats the fork as part of your project, making all paths work correctly.

┌──────────────────────────────────────────────────┐
│           VS Code Multi-Root Workspace           │
├──────────────────────────────────────────────────┤
│  📁 My Project (primary)                         │
│     └── Your application code                    │
│  📁 HVE Core Fork (secondary)                    │
│     └── .github/agents, prompts, instructions    │
│     └── Org-specific customizations              │
└──────────────────────────────────────────────────┘
         ↑
   .code-workspace file defines this

   microsoft/hve-core (upstream)
         ↓  sync on your schedule
   your-org/hve-core (fork)

Quick Start

Install the VS Code extension for the fastest setup. For guided installation-method selection, MCP configuration, or selective clone adoption, ask an agent to use the included hve-core-installer skill. Use the manual steps below for direct configuration.

Manual Setup

Step 1: Fork and Clone

If your organization has not already forked HVE Core, create a fork of microsoft/hve-core under your org's GitHub account. Then clone your fork.

Local VS Code

# Clone your org's fork next to your project
cd /path/to/your-projects
git clone https://github.com/your-org/hve-core.git

# Add upstream for syncing improvements
cd hve-core
git remote add upstream https://github.com/microsoft/hve-core.git

Codespaces/Devcontainer: Your fork will be cloned automatically (see Step 3).

Step 2: Create the Workspace File

Create .devcontainer/hve-core.code-workspace in your project:

Important

Use the actual clone path (not the folder display name) as the prefix in chat.*Locations settings. Folder display names do not resolve reliably as path prefixes.

Codespaces / Devcontainer

Use the absolute clone path:

{
  "folders": [
    {
      "name": "My Project",
      "path": ".."
    },
    {
      "name": "HVE Core Fork",
      "path": "/workspaces/hve-core"
    }
  ],
  "settings": {
    "chat.agentFilesLocations": {
      "/workspaces/hve-core/.github/agents/ado": true,
      "/workspaces/hve-core/.github/agents/data-science": true,
      "/workspaces/hve-core/.github/agents/design-thinking": true,
      "/workspaces/hve-core/.github/agents/github": true,
      "/workspaces/hve-core/.github/agents/project-planning": true,
      "/workspaces/hve-core/.github/agents/hve-core": true,
      "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
      "/workspaces/hve-core/.github/agents/security": true,
      "My Project/.github/agents": true
    },
    "chat.instructionsFilesLocations": {
      "/workspaces/hve-core/.github/instructions/ado": true,
      "/workspaces/hve-core/.github/instructions/coding-standards": true,
      "/workspaces/hve-core/.github/instructions/github": true,
      "/workspaces/hve-core/.github/instructions/hve-core": true,
      "/workspaces/hve-core/.github/instructions/shared": true,
      "My Project/.github/instructions": true
    },
    "chat.agentSkillsLocations": {
      "/workspaces/hve-core/.github/skills": true,
      "/workspaces/hve-core/.github/skills/accessibility": true,
      "/workspaces/hve-core/.github/skills/shared": true,
      "/workspaces/hve-core/.github/skills/coding-standards": true,
      "/workspaces/hve-core/.github/skills/data-science": true,
      "/workspaces/hve-core/.github/skills/design-thinking": true,
      "/workspaces/hve-core/.github/skills/hve-core": true,
      "/workspaces/hve-core/.github/skills/installer": true,
      "/workspaces/hve-core/.github/skills/project-planning": true,
      "/workspaces/hve-core/.github/skills/rai": true,
      "/workspaces/hve-core/.github/skills/rpi": true,
      "/workspaces/hve-core/.github/skills/security": true,
      "My Project/.github/skills": true
    }
  },
  "extensions": {
    "recommendations": [
      "github.copilot",
      "github.copilot-chat"
    ]
  }
}

Local VS Code

Use the relative clone path from the workspace file's directory:

{
  "folders": [
    {
      "name": "My Project",
      "path": ".."
    },
    {
      "name": "HVE Core Fork",
      "path": "../../hve-core"
    }
  ],
  "settings": {
    "chat.agentFilesLocations": {
      "../../hve-core/.github/agents/ado": true,
      "../../hve-core/.github/agents/data-science": true,
      "../../hve-core/.github/agents/hve-core": true,
      "../../hve-core/.github/agents/hve-core/subagents": true
    },
    "chat.instructionsFilesLocations": {
      "../../hve-core/.github/instructions/hve-core": true,
      "../../hve-core/.github/instructions/shared": true
    },
    "chat.agentSkillsLocations": {
      "../../hve-core/.github/skills": true,
      "../../hve-core/.github/skills/accessibility": true,
      "../../hve-core/.github/skills/coding-standards": true,
      "../../hve-core/.github/skills/data-science": true,
      "../../hve-core/.github/skills/design-thinking": true,
      "../../hve-core/.github/skills/hve-core": true,
      "../../hve-core/.github/skills/installer": true,
      "../../hve-core/.github/skills/project-planning": true,
      "../../hve-core/.github/skills/rai": true,
      "../../hve-core/.github/skills/rpi": true,
      "../../hve-core/.github/skills/security": true,
      "../../hve-core/.github/skills/shared": true
    }
  }
}

Adjust the relative path to match your clone location.

Step 3: Configure Devcontainer (Codespaces)

Update .devcontainer/devcontainer.json to clone your org's fork:

{
  "name": "My Project + HVE Core",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "onCreateCommand": "git clone --depth 1 https://github.com/your-org/hve-core.git /workspaces/hve-core 2>/dev/null || git -C /workspaces/hve-core pull --ff-only || true",

  "customizations": {
    "vscode": {
      "extensions": [
        "github.copilot",
        "github.copilot-chat"
      ]
    }
  }
}

Step 4: Open the Workspace

Warning

You must open the .code-workspace file, not the folder.

File → Open Workspace from File... → select hve-core.code-workspace (Local)
Run code .devcontainer/hve-core.code-workspace in terminal (Codespaces)

Note

The dev container spec has no workspaceFile property, so Codespaces and devcontainers always open in single-folder mode. You must manually switch to the workspace file after the container starts. For Codespaces without a fork, the Codespaces method avoids this extra step by configuring settings directly in devcontainer.json.

The VS Code title bar should show your workspace name, not just the folder name.

Path Resolution

Use the actual clone path as the prefix in chat.*Locations settings:

Path Style	Example	Recommended
Absolute path	`"/workspaces/hve-core/.github/agents"`	✅ Codespaces
Relative path	`"../../hve-core/.github/agents"`	✅ Local
Folder name	`"HVE Core Fork/.github/agents"`	❌ Unreliable

Folder display names ("name" field) label roots in the Explorer sidebar but do not resolve reliably as path prefixes in chat.*Locations settings. Always use the filesystem path from the folder's "path" field instead.

Keeping Your Fork Updated

Sync your fork with upstream microsoft/hve-core to pick up new agents, skills, and improvements. Pull from your fork into workspaces on a schedule that suits your team.

Syncing Upstream Changes into Your Fork

# From your fork's local clone
git fetch upstream
git merge upstream/main
# Resolve any conflicts with your org customizations, then push
git push origin main

Pulling Fork Updates into Workspaces

Strategy	Configuration	When Updates Apply
Manual	Run `git -C /workspaces/hve-core pull` when desired	On demand
On rebuild	Add `updateContentCommand` to devcontainer.json	Container rebuild
On every start	Add `postStartCommand` to devcontainer.json	Every startup

Tip

Update on rebuild for stability:

{
  "updateContentCommand": "git -C /workspaces/hve-core pull --ff-only || true"
}

Verification

After setup, verify HVE Core is working:

Check the Explorer sidebar shows both folders
Open Copilot Chat (Ctrl+Alt+I)
Click the agent picker dropdown
Verify RPI Agent and Documentation appear, then confirm /rpi-research is available

Troubleshooting

Agents not appearing

Confirm the workspace is open by checking that the title bar shows the workspace name
Ensure path values in .code-workspace point to the correct locations
Reload the window with Ctrl+Shift+P → "Developer: Reload Window"

"Folder not found" error

For local setups, verify HVE Core is cloned at the relative path specified
For Codespaces, check that onCreateCommand ran successfully in creation logs

Settings not applying

Folder settings override workspace settings, so check for conflicts at the folder level
Use the actual clone path (absolute or relative) in chat.*Locations settings, not folder display names

Next Steps

Your First Workflow - Try HVE Core with a real task
RPI Workflow - Research, Plan, Implement, Review methodology
Back to Installation Guide - Compare other methods

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

Navigation Menu

Repository navigation

multi-root.md

multi-root.md

When to Use This Method

How It Works

Quick Start

Manual Setup

Step 1: Fork and Clone

Local VS Code

Step 2: Create the Workspace File

Codespaces / Devcontainer

Local VS Code

Step 3: Configure Devcontainer (Codespaces)

Step 4: Open the Workspace

Path Resolution

Keeping Your Fork Updated

Syncing Upstream Changes into Your Fork

Pulling Fork Updates into Workspaces

Verification

Troubleshooting

Agents not appearing

"Folder not found" error

Settings not applying

Next Steps

FilesExpand file tree

multi-root.md

Latest commit

History

multi-root.md

File metadata and controls

When to Use This Method

How It Works

Quick Start

Manual Setup

Step 1: Fork and Clone

Local VS Code

Step 2: Create the Workspace File

Codespaces / Devcontainer

Local VS Code

Step 3: Configure Devcontainer (Codespaces)

Step 4: Open the Workspace

Path Resolution

Keeping Your Fork Updated

Syncing Upstream Changes into Your Fork

Pulling Fork Updates into Workspaces

Verification

Troubleshooting

Agents not appearing

"Folder not found" error

Settings not applying

Next Steps