# How to Fork and Extend HVE Core While Maintaining Upstream Synchronization

> Learn to fork and extend HVE Core while keeping upstream synchronization. Customize agents and prompts, and set up a workflow to resolve conflicts and preserve changes.

- Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core)
- Tags: how-to-guide
- Published: 2026-03-09

---

**To fork and extend HVE Core while maintaining upstream synchronization, create a GitHub fork of `microsoft/hve-core`, add the original repository as an upstream remote, customize agents and prompts in the `.github/` directory, and implement a recurring fetch-merge workflow that resolves conflicts in metadata files while preserving your organizational changes.**

Forking the `microsoft/hve-core` repository gives your organization full control over AI agents, Copilot prompts, and build pipelines while retaining the ability to integrate Microsoft’s latest improvements. This guide walks through creating a sustainable fork that supports deep customization—from VS Code extension templates to multi-root workspace configurations—without losing upstream compatibility.

## Prerequisites

Before forking HVE Core, ensure your environment meets these requirements:

- **GitHub CLI** (`gh`) installed for streamlined repository operations
- **Node.js 18+** and npm for dependency management and build validation
- **VS Code** with GitHub Copilot extensions for agent development
- A GitHub organization to host the fork

## Step 1: Create the Fork and Configure Upstream

Start by creating your fork using the GitHub CLI, which automatically handles repository cloning and remote configuration.

```bash
gh repo fork microsoft/hve-core --org your-org --clone
cd hve-core

```

Immediately add the original `microsoft/hve-core` repository as an upstream remote to enable future synchronization. This configuration is documented in [`docs/customization/forking.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/forking.md).

```bash
git remote add upstream https://github.com/microsoft/hve-core.git
git fetch upstream

```

Install the project dependencies to enable build validation:

```bash
npm install

```

## Step 2: Customize Core Metadata and Branding

Update identity files to distinguish your fork from the upstream source. According to the forking guide in [`docs/customization/forking.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/forking.md), modify these files immediately after creation:

- **[`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json)** – Update the `name`, `description`, and `repository` fields to point to your organization
- **[`README.md`](https://github.com/microsoft/hve-core/blob/main/README.md)** – Replace Microsoft branding with your organization’s documentation
- **[`CONTRIBUTING.md`](https://github.com/microsoft/hve-core/blob/main/CONTRIBUTING.md)** and **[`SECURITY.md`](https://github.com/microsoft/hve-core/blob/main/SECURITY.md)** – Adjust contribution guidelines and vulnerability reporting contacts

## Step 3: Extend Agents, Prompts, and Build Configuration

HVE Core separates extensibility into seven high-value areas. Select the customization layers relevant to your organization:

- **VS Code Extension** – Edit files in `extension/templates/` to modify the marketplace manifest and README templates
- **Copilot Paths** – Reorganize `.github/agents/`, `.github/prompts/`, and `.github/instructions/` to define custom AI behaviors
- **MCP Servers** – Configure [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json) to adjust Model Context Protocol server settings
- **npm Scripts** – Add organization-specific automation to [`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json)
- **Markdownlint Rules** – Customize [`.markdownlint.json`](https://github.com/microsoft/hve-core/blob/main/.markdownlint.json) to enforce your documentation standards
- **Release Configuration** – Modify [`release-please-config.json`](https://github.com/microsoft/hve-core/blob/main/release-please-config.json) to control versioning cadence
- **Workflow Permissions** – Update [`.github/workflows/release-stable.yml`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/release-stable.yml) and related files to match internal CI policies

## Step 4: Validate Your Customizations

Run the validation suite to ensure your metadata changes and file extensions comply with HVE Core’s schema requirements:

```bash
npm run lint:all
npm run plugin:generate

```

These commands verify that your customized agents and prompts maintain the correct front-matter structure required by the Copilot integration.

## Step 5: Configure a Multi-Root Workspace (Recommended)

For enterprise development, create a `.code-workspace` file that keeps your fork alongside project code. This setup ensures portable path resolution across local VS Code, DevContainers, and GitHub Codespaces.

Create `hve-core.code-workspace` with this structure:

```jsonc
{
  "folders": [
    { "name": "My Project", "path": ".." },
    { "name": "HVE-Core Fork", "path": "/workspaces/hve-core" }
  ],
  "settings": {
    "chat.agentFilesLocations": {
      "HVE-Core Fork/.github/agents/ado": true,
      "My Project/.github/agents": true
    },
    "chat.promptFilesLocations": {
      "HVE-Core Fork/.github/prompts/ado": true,
      "My Project/.github/prompts": true
    },
    "chat.instructionsFilesLocations": {
      "HVE-Core Fork/.github/instructions/ado": true,
      "My Project/.github/instructions": true
    },
    "chat.agentSkillsLocations": {
      "HVE-Core Fork/.github/skills": true,
      "My Project/.github/skills": true
    }
  },
  "extensions": {
    "recommendations": [
      "github.copilot",
      "github.copilot-chat"
    ]
  }
}

```

For DevContainer integration, add an `onCreateCommand` to automatically clone or update the fork when the container starts:

```jsonc
{
  "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 6: Implement the Upstream Synchronization Workflow

Maintaining upstream synchronization requires a disciplined git workflow. The process documented in [`docs/customization/forking.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/forking.md) follows this sequence:

1. **Fetch upstream changes:**

   ```bash
   git fetch upstream
   ```

2. **Inspect the delta** (optional but recommended):

   ```bash
   git log --oneline HEAD..upstream/main
   ```

3. **Merge upstream into your main branch:**

   ```bash
   git checkout main
   git merge upstream/main
   ```

4. **Resolve conflicts** in these common hotspots:
   - [`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json) (script customizations and dependency versions)
   - [`.markdownlint.json`](https://github.com/microsoft/hve-core/blob/main/.markdownlint.json) (rule adjustments)
   - Collection YAML files (added or removed artifacts)
   - Workflow definitions in `.github/workflows/`

   For each conflict, decide whether to keep your change, accept upstream, or merge both versions.

5. **Re-validate and push:**

   ```bash
   npm run lint:all
   npm run plugin:generate
   git push origin main
   ```

### Automating Synchronization

Add an npm script to [`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json) for repeatable updates:

```jsonc
{
  "scripts": {
    "upstream:sync": "git fetch upstream && git merge --no-ff upstream/main && npm run lint:all && npm run plugin:generate"
  }
}

```

Execute with `npm run upstream:sync`. You can also embed this in a DevContainer’s `postStartCommand` to keep the fork synchronized automatically.

## Summary

- **Fork creation** – Use `gh repo fork microsoft/hve-core` to establish your copy, then add the upstream remote with `git remote add upstream https://github.com/microsoft/hve-core.git`
- **Customization scope** – Focus on the seven extension areas: VS Code templates, Copilot paths in `.github/`, MCP servers, npm scripts, Markdownlint rules, release configuration, and workflow permissions
- **Workspace organization** – Implement a multi-root workspace configuration to isolate fork paths while maintaining project context
- **Sync workflow** – Run `git fetch upstream` followed by `git merge upstream/main`, resolve conflicts in [`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json) and workflow files, then validate with `npm run lint:all`
- **Automation** – Create npm scripts or DevContainer hooks to streamline recurring synchronization tasks

## Frequently Asked Questions

### How often should I synchronize my fork with upstream?

Synchronize your fork at least once per Microsoft release cycle, or whenever critical security patches appear in `microsoft/hve-core`. Frequent synchronization reduces merge complexity and prevents drift in dependency versions defined in [`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json).

### Which files typically cause merge conflicts during upstream synchronization?

The most common conflict sources are [`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json) (due to custom npm scripts), [`.markdownlint.json`](https://github.com/microsoft/hve-core/blob/main/.markdownlint.json) (organization-specific linting rules), collection YAML files (when artifacts are added or removed), and workflow definitions in `.github/workflows/` (CI policy modifications). The forking guide recommends tracking these files carefully during merge resolution.

### Can I automate the upstream synchronization process?

Yes. Create an npm script in your fork’s [`package.json`](https://github.com/microsoft/hve-core/blob/main/package.json) that chains `git fetch upstream`, `git merge upstream/main`, and validation commands like `npm run lint:all`. For containerized development, embed this logic in a DevContainer `postStartCommand` to automatically refresh the fork when starting a new workspace.

### How do I organize custom agents without breaking upstream updates?

Place organization-specific agents in subdirectories within `.github/agents/` (for example, `.github/agents/ado/` for Azure DevOps agents) rather than modifying root-level files. This namespace approach minimizes collision with upstream changes while allowing your multi-root workspace configuration to reference both upstream and custom agent paths simultaneously.