Multi-Root Workspace Installation

Forking HVE Core lets your enterprise customize agents, prompts, 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, prompts, 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 setup with installation method selection and MCP configuration, install the HVE Core Installer extension and ask any agent "help me customize hve-core installation". 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.promptFilesLocations": {
      "/workspaces/hve-core/.github/prompts/ado": true,
      "/workspaces/hve-core/.github/prompts/design-thinking": true,
      "/workspaces/hve-core/.github/prompts/github": true,
      "/workspaces/hve-core/.github/prompts/hve-core": true,
      "/workspaces/hve-core/.github/prompts/security": true,
      "My Project/.github/prompts": true
    },
    "chat.instructionsFilesLocations": {
      "/workspaces/hve-core/.github/instructions/ado": true,
      "/workspaces/hve-core/.github/instructions/coding-standards": true,
      "/workspaces/hve-core/.github/instructions/design-thinking": 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/shared": 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
    }
  }
}

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

1. Check the Explorer sidebar shows both folders
2. Open Copilot Chat (Ctrl+Alt+I)
3. Click the agent picker dropdown
4. Verify HVE Core agents appear (task-planner, task-researcher, etc.)

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