# Agent Plugins 1.0 — Enterprise Deploy Guard demo

A small but non-trivial **Agent Plugins 1.0** example built around an enterprise deployment-governance use case.

The portable plugin contains exactly the two component types standardized by Agent Plugins 1.0:

- an **Agent Skill** under `skills/`;
- an **MCP server configuration** in root `mcp.json`.

The MCP server itself is implemented in **C# / .NET 10** using the official Model Context Protocol C# SDK.

The full write-up that this repository accompanies is included here as [`ARTICLE.md`](ARTICLE.md), with the diagrams under `docs/images/`.

## Repository layout

```text
.
├── ARTICLE.md
├── .github/
│   ├── plugin/marketplace.json
│   └── workflows/build-and-attest.yml
├── docs/
│   ├── images/                    # article diagrams
│   ├── managed-settings.example.json
│   └── mcp.remote.example.json
├── plugins/
│   └── enterprise-deploy-guard/
│       ├── plugin.json
│       ├── mcp.json
│       ├── provenance.json        # generated by the provenance script
│       ├── bin/                   # generated by dotnet publish
│       └── skills/
│           └── validate-deployment/
│               ├── SKILL.md
│               └── references/controls.md
├── scripts/
│   ├── build.sh
│   ├── build.ps1
│   ├── generate_provenance.py
│   └── verify_provenance.py
└── src/DeploymentGovernance.Mcp/
    ├── DeploymentGovernance.Mcp.csproj
    └── Program.cs
```

## Prerequisites

- .NET 10 SDK
- Python 3.10+
- GitHub Copilot CLI with plugin support

The demo pins:

- `ModelContextProtocol` 2.2.0
- `Microsoft.Extensions.Hosting` 10.0.11

## 1. Build

Linux/macOS:

```bash
./scripts/build.sh
```

PowerShell:

```powershell
./scripts/build.ps1
```

The build publishes the stdio MCP server into the plugin's `bin/` directory, generates `provenance.json`, and verifies the hashes.

## 2. Install locally in Copilot CLI

```bash
copilot plugin install ./plugins/enterprise-deploy-guard
copilot plugin list
```

Note: as of the current GitHub Copilot CLI, direct local installs still work for this demo, but the CLI emits a deprecation warning: direct plugin installs from repos/URLs/local paths are deprecated and the future path is marketplace-based installs. The demo still validates the local-install flow for lab scenarios, but production distribution should prefer the marketplace flow shown below.

Example verified output in this environment:

```text
No plugins installed.
Plugin "enterprise-deploy-guard" installed successfully. Installed 1 skill.
Warning: Direct plugin installs (repos, URLs, local paths) are deprecated. Only plugin@marketplace installs will be supported in a future release.
```

Because Copilot CLI caches plugin components, reinstall the local plugin after modifying it.

## 3. Try it

Start a new Copilot CLI session and ask:

```text
Validate whether payments-api is ready for production deployment. Show the control evidence, the required approval, and the plugin provenance used for the assessment.
```

Expected semantic result:

- architecture/observability/security/rollback controls pass for `payments-api`;
- production still requires a human approval (`GOV-001`);
- `get_plugin_provenance` returns the generated content hashes.

Then try:

```text
Validate whether legacy-orders is ready for production deployment.
```

This should fail multiple mandatory controls.

## 4. Use the repository as a local plugin marketplace

GitHub Copilot CLI recognizes `.github/plugin/marketplace.json`.

From the repository root:

```bash
copilot plugin marketplace add .
copilot plugin marketplace list
copilot plugin marketplace browse enterprise-agent-platform
copilot plugin install enterprise-deploy-guard@enterprise-agent-platform
```

If you publish the repository to GitHub, replace the local marketplace path with `OWNER/REPO`.

## 5. Enterprise policy example

`docs/managed-settings.example.json` demonstrates:

- an approved plugin;
- an approved marketplace;
- a strict marketplace set;
- managed OpenTelemetry settings;
- disabled permission bypass;
- a stable URL-based MCP allowlist;
- sandbox policy.

The installable lab plugin uses a local `stdio` MCP server. For a production-style topology, `docs/mcp.remote.example.json` shows the same logical server as `streamable-http`, which is easier to govern with a stable `serverUrl`. GitHub matches local `stdio` allowlists by the exact command **and every argument**, so a dynamically cached plugin path is a poor enterprise identity boundary unless the installation path is made deterministic.

**Important:** adapt `YOUR-ORG/...`, telemetry endpoints, URLs, and platform policy to your environment. These files are architecture examples, not production-ready policy templates.

## 6. Provenance and drift

`provenance.json` is deliberately **outside** the Agent Plugins 1.0 standard. It demonstrates an enterprise attestation layer on top of the portable package.

Generate it:

```bash
python scripts/generate_provenance.py
```

Verify it:

```bash
python scripts/verify_provenance.py
```

Now edit `SKILL.md` without regenerating provenance and run the verifier again. It will report deterministic drift:

```text
DRIFT skills/validate-deployment/SKILL.md
```

That is the core distinction in the accompanying article:

**observability tells us what ran; provenance helps prove exactly what definition ran.**

## Notes on Agent Plugins 1.0

This demo intentionally follows the portable Agent Plugins 1.0 specification:

- root `plugin.json` with the Agent Plugins 1.0 `$schema`;
- Skills discovered from `skills/*/SKILL.md`;
- MCP configuration in root `mcp.json`;
- no inline `skills` or `mcpServers` paths in the portable manifest.

GitHub also continues to support its earlier Copilot-specific plugin format. Do not confuse that legacy layout with the portable Agent Plugins 1.0 contract.

## Official references

- Agent Plugins 1.0 specification: https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.0.0.md
- GitHub announcement: https://github.blog/changelog/2026-08-12-agent-plugins-1-0-in-vs-code-copilot-cli-and-the-copilot-app/
- MCP allowlists: https://github.blog/changelog/2026-08-06-mcp-allowlists-in-enterprise-managed-settings/
- Copilot CLI plugin install docs: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing
- Marketplace docs: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace
- MCP C# SDK: https://github.com/modelcontextprotocol/csharp-sdk

## Limitation of this packaged demo

The source and JSON schemas have been checked in this environment, but the archive is **not precompiled** because a .NET SDK is not installed in the artifact-building environment. Run `scripts/build.sh` / `scripts/build.ps1` locally or use the included GitHub Action to produce the installable `bin/` contents.

## License

MIT — use the demo as a starting point, not as production security policy.