How to Fork and Extend HVE Core While Maintaining Upstream Synchronization

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.

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.

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

Install the project dependencies to enable build validation:

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, modify these files immediately after creation:

• package.json – Update the name, description, and repository fields to point to your organization
• README.md – Replace Microsoft branding with your organization’s documentation
• CONTRIBUTING.md and 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 to adjust Model Context Protocol server settings
• npm Scripts – Add organization-specific automation to package.json
• Markdownlint Rules – Customize .markdownlint.json to enforce your documentation standards
• Release Configuration – Modify release-please-config.json to control versioning cadence
• Workflow Permissions – Update .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:

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:

{
  "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:

{
  "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 follows this sequence:

1. Fetch upstream changes:

   git fetch upstream

2. Inspect the delta (optional but recommended):

   git log --oneline HEAD..upstream/main

3. Merge upstream into your main branch:

   git checkout main
   git merge upstream/main

4. Resolve conflicts in these common hotspots:

   • package.json (script customizations and dependency versions)
   • .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:

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

Automating Synchronization

Add an npm script to package.json for repeatable updates:

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

Which files typically cause merge conflicts during upstream synchronization?

The most common conflict sources are package.json (due to custom npm scripts), .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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}