fix(plugins): add missing plugin.json to .github directory (microsoft#2689)

## Description

This PR fixed Copilot CLI installation from the HVE Core marketplace by
adding the shared manifest resolved from the canonical `.github` Git
source. Marketplace entries continued to own package-specific component
membership, while repository validation, fixtures, tests, and
documentation now use the same shared-source contract.

* Added `.github/plugin.json` with the `hve-core` source identity and
explicit empty component defaults.
* Replaced optional generated `plugins/<name>/plugin.json` validation
with a required shared-manifest check.
* Updated fixture repositories and focused tests for accepted and absent
shared manifests.
* Documented complete source-tree copying, entry-selected component
loading, unchanged channel refs, and the separate role of generated
release ZIPs.

## Related Issue(s)

None.

## Type of Change

Select all that apply:

**Code & Documentation:**

* [x] Bug fix (non-breaking change fixing an issue)
* [x] New feature (non-breaking change adding functionality)
* [ ] Breaking change (fix or feature causing existing functionality to
change)
* [x] Documentation update

**Infrastructure & Configuration:**

* [ ] GitHub Actions workflow
* [ ] Linting configuration (markdown, PowerShell, etc.)
* [ ] Security configuration
* [ ] DevContainer configuration
* [ ] Dependency update

**AI Artifacts:**

* [ ] Reviewed contribution with `hve-builder` and addressed all
actionable findings
* [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
* [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
* [ ] Copilot agent (`.github/agents/*.agent.md`)
* [ ] Copilot skill (`.github/skills/*/SKILL.md`)
* [ ] Copilot hook (`.github/hooks/*/*.json`)
* [ ] Eval spec added/updated for changed AI artifacts (`evals/`)

> Note for AI Artifact Contributors:
>
> * Agents: Research, indexing/referencing other project (using standard
VS Code GitHub Copilot/MCP tools), planning, and general implementation
agents likely already exist. Review `.github/agents/` before creating
new ones.
> * Skills: Must include both bash and PowerShell scripts. See
[Skills](../docs/contributing/skills.md).
> * Model Versions: Contributions **MUST** target models listed in the
model catalog (`scripts/linting/model-catalog.json`) whose provider
appears in `providerAllowlist` and whose status is `ga` or `preview`.
Run `npm run lint:models` to validate references.
> * See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

* [x] Script/automation (`.ps1`, `.sh`, `.py`)
* [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

<!-- If you checked any boxes under "AI Artifacts" above, provide a
sample prompt showing how to use your contribution -->
<!-- Delete this section if not applicable -->

**User Request:**
<!-- What natural language request would trigger this
agent/prompt/instruction? -->

**Execution Flow:**
<!-- Step-by-step: what happens when invoked? Include tool usage,
decision points -->

**Output Artifacts:**
<!-- What files/content are created? Show first 10-20 lines as preview
-->

**Success Indicators:**
<!-- How does user know it worked correctly? What validation should they
perform? -->

For detailed contribution requirements, see:

* Common Standards:
[docs/contributing/ai-artifacts-common.md](../docs/contributing/ai-artifacts-common.md)
- Shared standards for XML blocks, markdown quality, RFC 2119,
validation, and testing
* Agents:
[docs/contributing/custom-agents.md](../docs/contributing/custom-agents.md)
- Agent configurations with tools and behavior patterns
* Prompts:
[docs/contributing/prompts.md](../docs/contributing/prompts.md) -
Workflow-specific guidance with template variables
* Instructions:
[docs/contributing/instructions.md](../docs/contributing/instructions.md)
- Technology-specific standards with glob patterns
* Skills: [docs/contributing/skills.md](../docs/contributing/skills.md)
- Task execution utilities with cross-platform scripts

## Testing

Fast validation was run against the changed surfaces after merging
current `origin/main`:

* `npm run test:ps -- -TestPath
"scripts/tests/plugins/Validate-Marketplace.Tests.ps1"` - passed, 71
tests
* `npm run lint:marketplace` - passed, 10 plugins
* `npm run lint:plugin-output` - passed, no tracked plugin output or
symbolic links
* `npm exec -- markdownlint-cli2 "scripts/plugins/README.md"
"docs/getting-started/methods/cli-plugins.md"` - passed, 0 issues
* `git diff --check origin/main...HEAD` - passed

Security analysis found no sensitive data, dependency changes,
permission changes, or privilege expansion. Manual testing was not
performed.

## Checklist

### Required Checks

* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [ ] Changes are backwards compatible (if applicable)
* [x] Tests added for new functionality (if applicable)

### AI Artifact Contributions
<!-- If contributing an agent, prompt, instruction, or skill, complete
these checks -->
* [ ] Used `hve-builder` review mode to review contribution
* [ ] Addressed all actionable findings from the `hve-builder` review
* [ ] Verified contribution follows common standards and type-specific
requirements

### Required Local Checks

The following local-safe validation commands must pass before merging:

* [ ] Local validation aggregate: `npm run validate:local` (skipped by
caller direction; changed-surface checks passed)
* [ ] Documentation validation (if docs changed): `npm run
validate:docs` (skipped by caller direction; targeted Markdown lint
passed)
* [ ] Spell checking: `npm run spell-check` (skipped by caller
direction)
* [ ] Link validation: `npm run lint:md-links` (skipped by caller
direction)

## Security Considerations

* [x] This PR does not contain any sensitive or NDA information
* [ ] Any new dependencies have been reviewed for security issues (N/A -
no dependency changes)
* [ ] Security-related scripts follow the principle of least privilege
(N/A - no security-related script changes)

## Additional Notes

The branch was merged with current `origin/main` before PR generation.
The broad template validation commands were intentionally not run;
validation was limited to fast checks that own the changed files and
behavior.

Author: agreaves-ms

.github/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "hve-core",
+  "agents": [],
+  "commands": [],
+  "skills": []
+}

docs/getting-started/methods/cli-plugins.md

@@ -3,7 +3,7 @@ title: Copilot CLI Plugin
 description: Register an HVE Core catalog ref and install the complete hve-core plugin
 sidebar_position: 2
 author: Microsoft
-ms.date: 2026-08-08
+ms.date: 2026-08-12
 ms.topic: how-to
 ---
 
@@ -87,10 +87,17 @@ Each plugin includes:
 | Skills       | Yes           | Self-contained skill packages                      |
 | Instructions | No            | Included for `#file:` references, not auto-applied |
 
-Each plugin is a self-contained tree of regular files and real directories.
-Artifacts are copied from the source repository during generation, so a plugin
-installs the same way on every operating system and needs no symbolic link
-support.
+All marketplace entries install from the shared `.github` source tree, whose
+manifest is `.github/plugin.json`. During Git-source installation, the CLI
+copies that complete source tree for each installed entry. The declarations on
+the selected marketplace entry determine which recognized agents, commands,
+skills, and hooks the CLI loads for that package; they do not filter the copied
+files. Distinct packages can therefore share the same source tree and manifest
+while loading different component sets.
+
+Generated per-package ZIPs are release assets. They are separate from the
+Git-source tree used by `copilot plugin install` and do not determine the
+contents copied during installation.
 
 ## Limitations
 

scripts/plugins/README.md

@@ -67,8 +67,9 @@ selected temporary staging location. Ordinary validation uses
 ## Marketplace Validation
 
 `Validate-Marketplace.ps1` validates `.github/plugin/marketplace.json` against
-its JSON schema and checks version alignment with the root `package.json` plus
-the source locator of every entry.
+its JSON schema, requires the shared `.github/plugin.json` manifest, and checks
+version alignment with the root `package.json` plus the source locator of every
+entry.
 
 ```bash
 npm run lint:marketplace
@@ -97,6 +98,25 @@ Every entry uses the canonical `.github` source root:
 }
 ```
 
+Git-source installation resolves `.github/plugin.json` as the manifest for
+that shared source root:
+
+```json
+{
+  "name": "hve-core",
+  "agents": [],
+  "commands": [],
+  "skills": []
+}
+```
+
+The shared manifest provides the source identity and explicit empty component
+defaults. Each entry in `.github/plugin/marketplace.json` owns its package
+membership declarations. Those entry declarations select the recognized
+components that the CLI loads for that package; they do not filter which files
+the CLI copies from the source root. `Validate-Marketplace.ps1` owns validation
+of the shared manifest and the entry source contract.
+
 The `repo` and `path` fields are required, and `path` must be `.github`.
 Main catalog entries omit `ref`. Prerelease catalog entries use the exact
 `prerelease-v<version>` ref, and release catalog entries use the exact
@@ -117,8 +137,11 @@ Component membership is relative to the `.github` source root:
 * `skills/*` directories
 * `hooks/*.json`
 
-Generated ZIP paths are host-specific package layout, not catalog membership
-vocabulary.
+For Git-source installation, the CLI copies the complete shared `.github`
+source tree for each installed entry. Generated per-package ZIPs are separate
+release assets materialized in external staging; the CLI does not use them for
+Git-source installation. Their host-specific paths are package layout, not
+catalog membership vocabulary.
 
 ## Deterministic Release Evidence
 

scripts/plugins/Validate-Marketplace.ps1

@@ -251,6 +251,16 @@ function Test-MarketplaceRepositoryContract {
         $contractErrors += "package documentation root 'docs/plugins' is missing under $RepoRoot"
     }
 
+    # Every entry installs from the shared '.github' source root, so this single
+    # manifest is what GitHub-object installation resolves for the whole catalog.
+    $sharedManifestPath = Join-Path $RepoRoot '.github/plugin.json'
+    $sharedManifest = if (Test-Path -LiteralPath $sharedManifestPath -PathType Leaf) {
+        Get-Content -LiteralPath $sharedManifestPath -Raw -Encoding utf8 | ConvertFrom-Json -AsHashtable
+    }
+    if ($sharedManifest -isnot [System.Collections.IDictionary]) {
+        $contractErrors += "shared plugin manifest '.github/plugin.json' must exist under $RepoRoot and contain a JSON object"
+    }
+
     $entries = @($Manifest['plugins'])
 
     # The active package set is derived from the package documents on disk, so
@@ -321,17 +331,6 @@ function Test-MarketplaceRepositoryContract {
         if ($channelProjections['Stable'] -ne $channelProjections['PreRelease']) {
             $contractErrors += "package '$name' must resolve identical components and maturity on Stable and PreRelease"
         }
-
-        $pluginRoot = Join-Path $RepoRoot "plugins/$name/plugin.json"
-        if (Test-Path -LiteralPath $pluginRoot -PathType Leaf) {
-            $pluginManifest = Get-Content -LiteralPath $pluginRoot -Raw -Encoding utf8 | ConvertFrom-Json -AsHashtable
-            if ([string]$pluginManifest['name'] -ne $name -or [string]$pluginManifest['version'] -ne [string]$entry['version']) {
-                $contractErrors += "package '$name' root plugin.json identity does not mirror the catalog"
-            }
-            if ($pluginManifest.Contains('x-hve')) {
-                $contractErrors += "package '$name' root plugin.json must not contain x-hve"
-            }
-        }
     }
     if ($tombstoneCount -eq 0) {
         $contractErrors += 'repository marketplace must declare at least one removed component tombstone'

scripts/tests/plugins/Assert-NoTrackedPluginOutput.Tests.ps1

@@ -21,7 +21,7 @@ Describe 'Assert-NoTrackedPluginOutput' -Tag 'Unit' {
         }
 
         It 'Inspects every staged entry' {
-            $script:cleanResult.EntryCount | Should -Be 3
+            $script:cleanResult.EntryCount | Should -Be 4
         }
 
         It 'Reports no violation' {

scripts/tests/plugins/PluginHelpers.Materialization.Tests.ps1

@@ -64,6 +64,7 @@ Describe 'Get-PluginTrackedPathIndex' -Tag 'Unit' {
         It 'Returns exactly the staged paths' {
             @($script:trackedIndex.Paths | Sort-Object) | Should -Be @(
                 @(
+                    '.github/plugin.json',
                     '.github/skills/rpi/rpi-plan/SKILL.md',
                     '.github/skills/rpi/rpi-plan/references/checklist.md',
                     'package.json'

scripts/tests/plugins/PluginTestFixtures.psm1

@@ -46,9 +46,10 @@ function New-PluginFixtureRepository {
     Creates an isolated git working tree that mimics the repository layout.
 
     .DESCRIPTION
-    Initializes a standalone git repository containing package.json and the
-    canonical roots the plugin pipeline reads. Nothing is committed, because
-    every production reader consults the index rather than history.
+    Initializes a standalone git repository containing package.json, the shared
+    .github/plugin.json manifest, and the canonical roots the plugin pipeline
+    reads. Nothing is committed, because every production reader consults the
+    index rather than history.
 
     .PARAMETER Path
     Directory to initialize.
@@ -105,6 +106,14 @@ function New-PluginFixtureRepository {
     } | ConvertTo-Json -Depth 5
     Add-PluginFixtureFile -RepoRoot $Path -RelativePath 'package.json' -Content $packageJson | Out-Null
 
+    $sharedManifest = [ordered]@{
+        name     = 'contoso-hve'
+        agents   = @()
+        commands = @()
+        skills   = @()
+    } | ConvertTo-Json -Depth 5
+    Add-PluginFixtureFile -RepoRoot $Path -RelativePath '.github/plugin.json' -Content $sharedManifest | Out-Null
+
     if (-not $SkipAgentRoot) {
         New-Item -ItemType Directory -Path (Join-Path $Path '.github/agents') -Force | Out-Null
     }

scripts/tests/plugins/Validate-Marketplace.Tests.ps1

@@ -514,25 +514,24 @@ Describe 'Test-MarketplaceRepositoryContract' -Tag 'Unit' {
         }
     }
 
-    Context 'when a generated plugin manifest is present' {
-        It 'Reports a manifest that does not mirror catalog identity' {
+    Context 'when the shared source manifest defines the catalog root' {
+        It 'Accepts a repository that owns .github/plugin.json' {
             New-ValidatorFixture -Root $script:contractRepo | Out-Null
-            Add-PluginFixtureFile -RepoRoot $script:contractRepo -RelativePath 'plugins/rpi/plugin.json' `
-                -Content '{"name":"rpi","version":"1.0.0"}' -Untracked | Out-Null
+            Join-Path $script:contractRepo '.github/plugin.json' | Should -Exist
 
             $run = Get-ValidationReport -Root $script:contractRepo
-            (Get-ReportError -Report $run.Report) -join ' ' |
-                Should -Match "repository contract: package 'rpi' root plugin\.json identity does not mirror the catalog"
+            $run.Outcome.Success | Should -BeTrue
+            $run.Outcome.ErrorCount | Should -Be 0
         }
 
-        It 'Reports a manifest that carries the catalog overlay' {
+        It 'Reports an absent shared source manifest' {
             New-ValidatorFixture -Root $script:contractRepo | Out-Null
-            Add-PluginFixtureFile -RepoRoot $script:contractRepo -RelativePath 'plugins/rpi/plugin.json' `
-                -Content '{"name":"rpi","version":"9.9.9","x-hve":{"displayName":"Contoso - rpi"}}' -Untracked | Out-Null
+            Remove-Item -LiteralPath (Join-Path $script:contractRepo '.github/plugin.json') -Force
 
             $run = Get-ValidationReport -Root $script:contractRepo
+            $run.Outcome.Success | Should -BeFalse
             (Get-ReportError -Report $run.Report) -join ' ' |
-                Should -Match "repository contract: package 'rpi' root plugin\.json must not contain x-hve"
+                Should -Match "repository contract: shared plugin manifest '\.github/plugin\.json' must exist"
         }
     }