microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/customization/forking.md
261lines · modecode
| 1 | --- |
| 2 | title: Forking and Extending HVE Core |
| 3 | description: Fork HVE Core to create a fully customized prompt engineering framework with upstream sync and Copilot-assisted adaptation |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-02-24 |
| 6 | ms.topic: tutorial |
| 7 | keywords: |
| 8 | - forking |
| 9 | - extending |
| 10 | - upstream sync |
| 11 | - customization |
| 12 | estimated_reading_time: 10 |
| 13 | --- |
| 14 | |
| 15 | ## When to Fork |
| 16 | |
| 17 | Forking creates an independent copy of HVE Core that you fully control. Consider forking |
| 18 | when in-place customization (adding instructions, creating collections, extending |
| 19 | validation) is insufficient for your needs. |
| 20 | |
| 21 | ### Fork when you need to |
| 22 | |
| 23 | * Replace core workflow agents with organization-specific versions |
| 24 | * Modify the plugin generation pipeline or build system |
| 25 | * Enforce custom governance policies that require structural changes |
| 26 | * Maintain a private distribution channel with proprietary artifacts |
| 27 | * Integrate with internal systems that require changes to core scripts |
| 28 | |
| 29 | ### Stay with in-place customization when you |
| 30 | |
| 31 | * Add new agents, prompts, or instructions without modifying existing ones |
| 32 | * Create organization-specific collections alongside existing collections |
| 33 | * Extend validation with custom linting scripts |
| 34 | * Configure existing tools through their settings files |
| 35 | |
| 36 | > [!IMPORTANT] |
| 37 | > Forking introduces ongoing maintenance cost. Every upstream release requires evaluation, |
| 38 | > merge, and potential conflict resolution. Choose forking only when in-place customization |
| 39 | > cannot achieve your goals. |
| 40 | |
| 41 | ## Fork Setup |
| 42 | |
| 43 | ### Step 1: Create the fork |
| 44 | |
| 45 | Fork the repository through GitHub's fork mechanism. Choose whether to fork into a personal |
| 46 | account or an organization. |
| 47 | |
| 48 | ```bash |
| 49 | gh repo fork microsoft/hve-core --org your-org --clone |
| 50 | cd hve-core |
| 51 | ``` |
| 52 | |
| 53 | ### Step 2: Configure the upstream remote |
| 54 | |
| 55 | ```bash |
| 56 | git remote add upstream https://github.com/microsoft/hve-core.git |
| 57 | git fetch upstream |
| 58 | ``` |
| 59 | |
| 60 | ### Step 3: Install dependencies |
| 61 | |
| 62 | ```bash |
| 63 | npm install |
| 64 | ``` |
| 65 | |
| 66 | ### Step 4: Make initial configuration changes |
| 67 | |
| 68 | Update these files to reflect your organization: |
| 69 | |
| 70 | * `package.json`: Change the `name`, `description`, and `repository` fields |
| 71 | * `README.md`: Update branding, installation instructions, and support links |
| 72 | * `CONTRIBUTING.md`: Adjust contribution guidelines for your team |
| 73 | * `SECURITY.md`: Point to your organization's security reporting process |
| 74 | |
| 75 | ### Step 5: Verify the build |
| 76 | |
| 77 | ```bash |
| 78 | npm run lint:all |
| 79 | npm run plugin:generate |
| 80 | ``` |
| 81 | |
| 82 | ## Seven Customization Areas |
| 83 | |
| 84 | After forking, these areas provide the highest-value customization opportunities. |
| 85 | |
| 86 | ### 1. VS Code Extensions |
| 87 | |
| 88 | The `extension/` directory contains packaging configuration for distributing collections |
| 89 | as a VS Code extension. Modify `extension/templates/` to customize the extension manifest, |
| 90 | README, and marketplace presentation. See the |
| 91 | [VS Code Extension API](https://code.visualstudio.com/api) for extension packaging details. |
| 92 | |
| 93 | ### 2. Copilot Paths |
| 94 | |
| 95 | Agent and prompt files live under `.github/agents/` and `.github/prompts/`. Restructure |
| 96 | these directories to match your organization's team topology or domain boundaries. Update |
| 97 | collection manifests to reflect new paths. |
| 98 | |
| 99 | ### 3. MCP Servers |
| 100 | |
| 101 | If your workflows depend on MCP (Model Context Protocol) servers, configure server |
| 102 | definitions in `.vscode/mcp.json` or workspace settings. Fork-level changes let you |
| 103 | add organization-specific MCP servers that all collections can reference. |
| 104 | |
| 105 | ### 4. npm Scripts |
| 106 | |
| 107 | Add, modify, or remove npm scripts in `package.json` to match your build and validation |
| 108 | needs. Common additions include organization-specific linting rules, custom deployment |
| 109 | scripts, and integration test runners. |
| 110 | |
| 111 | ### 5. Markdownlint Rules |
| 112 | |
| 113 | Customize `.markdownlint.json` to enforce your organization's documentation standards. |
| 114 | Add custom rules or adjust limits (such as line length) to match existing style guides. |
| 115 | |
| 116 | ### 6. Release Configuration |
| 117 | |
| 118 | Modify `release-please-config.json` to align with your release cadence and changelog |
| 119 | format. Adjust version bumping strategy and changelog sections for your workflow. |
| 120 | |
| 121 | ### 7. Workflow Permissions |
| 122 | |
| 123 | GitHub Actions workflows in `.github/workflows/` define CI/CD behavior. Adjust workflow |
| 124 | permissions, add organization-specific validation jobs, or integrate with internal CI |
| 125 | systems. |
| 126 | |
| 127 | ## Upstream Sync Workflow |
| 128 | |
| 129 | Periodically pull upstream changes to receive new features, bug fixes, and security |
| 130 | patches. |
| 131 | |
| 132 | ### Fetch and review upstream changes |
| 133 | |
| 134 | ```bash |
| 135 | git fetch upstream |
| 136 | git log --oneline upstream/main..HEAD |
| 137 | git log --oneline HEAD..upstream/main |
| 138 | ``` |
| 139 | |
| 140 | ### Merge upstream changes |
| 141 | |
| 142 | ```bash |
| 143 | git checkout main |
| 144 | git merge upstream/main |
| 145 | ``` |
| 146 | |
| 147 | ### Resolve conflicts |
| 148 | |
| 149 | Conflicts typically occur in files you have customized. Common conflict points: |
| 150 | |
| 151 | * `package.json` (script modifications) |
| 152 | * `.markdownlint.json` (rule adjustments) |
| 153 | * Collection YAML files (added or removed artifacts) |
| 154 | * Workflow files (permission or job changes) |
| 155 | |
| 156 | For each conflict, evaluate whether to keep your change, accept the upstream change, or |
| 157 | combine both. Validate after resolution: |
| 158 | |
| 159 | ```bash |
| 160 | npm run lint:all |
| 161 | npm run plugin:generate |
| 162 | ``` |
| 163 | |
| 164 | ### Files to sync vs. skip |
| 165 | |
| 166 | | Sync (accept upstream) | Skip (keep your version) | |
| 167 | |--------------------------------------------|---------------------------------------| |
| 168 | | Core scripts in `scripts/` | `package.json` (your custom fields) | |
| 169 | | Schema files in `scripts/linting/schemas/` | `README.md` (your branding) | |
| 170 | | Agent and prompt templates | `.github/workflows/` (your CI config) | |
| 171 | | Shared instructions | `CONTRIBUTING.md` (your guidelines) | |
| 172 | | Documentation in `docs/` | Custom collection manifests | |
| 173 | |
| 174 | ## Copilot-Assisted Adaptation |
| 175 | |
| 176 | Use Copilot to accelerate upstream integration and fork maintenance. These prompts help |
| 177 | you analyze and adapt changes efficiently. |
| 178 | |
| 179 | ### Analyze upstream diff |
| 180 | |
| 181 | ```text |
| 182 | Analyze the upstream changes between our fork and upstream/main. |
| 183 | Summarize what changed, identify which files conflict with our |
| 184 | customizations, and recommend a merge strategy for each conflict. |
| 185 | ``` |
| 186 | |
| 187 | ### Adapt new instructions to organization context |
| 188 | |
| 189 | ```text |
| 190 | Review the new instruction files added in the upstream merge. |
| 191 | Adapt them to use our organization's terminology, coding standards, |
| 192 | and tool chain. Preserve the original intent while aligning with |
| 193 | our conventions in .github/instructions/. |
| 194 | ``` |
| 195 | |
| 196 | ### Validate fork health |
| 197 | |
| 198 | ```text |
| 199 | Compare our fork against upstream/main. Identify files that have |
| 200 | diverged significantly, check for deprecated patterns we still use, |
| 201 | and list any new upstream features we have not adopted. Produce a |
| 202 | prioritized maintenance backlog. |
| 203 | ``` |
| 204 | |
| 205 | ## Maintaining Your Fork |
| 206 | |
| 207 | Establish a regular maintenance cadence to keep your fork healthy. |
| 208 | |
| 209 | ### Sync frequency |
| 210 | |
| 211 | Sync with upstream at least once per release cycle. More frequent syncs (weekly or |
| 212 | biweekly) reduce the size of each merge and lower conflict risk. |
| 213 | |
| 214 | ### Versioning strategy |
| 215 | |
| 216 | Maintain your own version scheme in `package.json` that reflects your release cadence. |
| 217 | Track the upstream version you last synced from in a comment or separate tracking file |
| 218 | so you can identify the delta on each sync. |
| 219 | |
| 220 | ### Deprecation handling |
| 221 | |
| 222 | When upstream deprecates an artifact, evaluate whether to: |
| 223 | |
| 224 | * Remove it from your fork immediately |
| 225 | * Keep it with a `maturity: deprecated` tag for a transition period |
| 226 | * Replace it with an organization-specific alternative |
| 227 | |
| 228 | ### Health checks |
| 229 | |
| 230 | Run the full validation suite after every sync: |
| 231 | |
| 232 | ```bash |
| 233 | npm run lint:all |
| 234 | npm run plugin:generate |
| 235 | npm run plugin:validate |
| 236 | ``` |
| 237 | |
| 238 | ## Role Scenarios |
| 239 | |
| 240 | **Fabrikam's platform team** forks HVE Core to establish org-wide Copilot governance. |
| 241 | They replace the default RPI workflow agents with versions that enforce Fabrikam's code |
| 242 | review policies, add custom MCP server configurations for internal APIs, and distribute |
| 243 | the fork as a private VS Code extension to all engineering teams. A biweekly upstream sync |
| 244 | ensures they receive new skills and security patches without disrupting their customizations. |
| 245 | |
| 246 | **Woodgrove Bank's compliance team** forks HVE Core to add financial regulation |
| 247 | instructions and audit trail requirements. They customize the build system to include |
| 248 | compliance validation scripts that check every agent and prompt for required disclaimer |
| 249 | sections. The compliance team maintains a strict monthly sync cadence, reviewing each |
| 250 | upstream change against regulatory requirements before merging. |
| 251 | |
| 252 | ## Further Reading |
| 253 | |
| 254 | * [VS Code Extension API](https://code.visualstudio.com/api) for extension packaging and |
| 255 | distribution |
| 256 | * [docs/contributing/](../contributing/) for artifact syntax and contribution guidelines |
| 257 | |
| 258 | <!-- markdownlint-disable MD036 --> |
| 259 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 260 | then carefully refined by our team of discerning human reviewers.* |
| 261 | <!-- markdownlint-enable MD036 --> |
| 262 | |