GitHub Copilot Plugin

The Archgate GitHub Copilot plugin gives AI agents working in GitHub Copilot built-in guardrails. Agents read your ADRs before writing code, validate after, and capture new patterns for the team — the same workflow available in the Claude Code plugin.

Both Copilot distributions are supported: the Copilot CLI (copilot on your PATH) and the Copilot desktop app. They share the same configuration directory (~/.copilot/ by default), so one install covers both.

How it works

Copilot supports plugin marketplaces backed by git repositories. The Archgate plugin is served from plugins.archgate.dev/archgate/vscode.git — the same marketplace used by the VS Code extension, in the .github/plugin/ manifest format Copilot recognizes natively.

Installation is declarative: the CLI writes the marketplace and plugin declaration into ~/.copilot/settings.json (extraKnownMarketplaces + enabledPlugins). Copilot reads this file on startup and installs any declared plugin automatically. When the copilot CLI is on your PATH, the CLI also runs copilot plugin install so the plugin is available immediately without a restart.

Installation

Beta access required

The GitHub Copilot plugin is currently in beta. Run archgate login to sign up and authenticate before following the steps below.

1. Log in with GitHub

Authenticate with your GitHub account to obtain a plugin token:

archgate login

This starts a GitHub Device Flow. The CLI displays a one-time code and URL — open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via git credential approve.

2. Initialize your project with the plugin

Run archgate init with the --editor copilot flag:

archgate init --editor copilot

If you are logged in and Copilot is installed (CLI or desktop app), the plugin is installed automatically:

• Copilot CLI on PATH: the plugin is installed immediately via copilot plugin install.
• Desktop app only: the plugin is declared in ~/.copilot/settings.json; restart the Copilot app and it installs automatically on launch.

To explicitly request plugin installation:

archgate init --editor copilot --install-plugin

To install or reinstall the plugin on an already-initialized project:

archgate plugin install --editor copilot

Generated files

The command creates the .github/copilot/ directory for project-level configuration and updates the user-level ~/.copilot/settings.json with the Archgate marketplace and plugin declaration. An entry pointing at an outdated marketplace URL is corrected in place.

Manual installation

To install the plugin manually with the copilot CLI:

copilot plugin marketplace add "$(archgate plugin url --editor copilot)"
copilot plugin install archgate@archgate

Credentials are provided automatically by your git credential manager (stored during archgate login).

What the plugin provides

The plugin adds agents and role-based skills to Copilot. The agent orchestrates the guardrails workflow, invoking skills as needed.

Agents

Agent	Purpose
archgate:developer	General development agent that reads ADRs before coding and validates after
archgate:planner	Read-only planning agent that designs ADR-compliant implementation plans

The archgate:developer agent is set as the default agent via the plugin settings. It orchestrates the skills below automatically as part of its workflow.

Skills

Skill	Purpose
archgate:reviewer	Validates code changes against all project ADRs for structural compliance
archgate:lessons-learned	Reviews rule coverage and proposes new ADRs when patterns emerge
archgate:adr-author	Creates and edits ADRs following project conventions
archgate:cli-reference	Provides the CLI command reference and rules authoring guide to agents
archgate:onboard	One-time setup: explores the codebase, interviews the developer, creates initial ADRs

Initial setup with onboard

After installation, run the archgate:onboard skill in your project once. This skill:

1. Explores your codebase structure (directories, key files, package configuration)
2. Interviews you about your team’s conventions, constraints, and architectural decisions
3. Creates an initial set of ADRs based on your responses
4. Sets up the .archgate/ directory with your first rules

The onboard skill is designed to run once per project. After onboarding, the other skills handle day-to-day development.

How it works in practice

The plugin follows a structured workflow for every coding task:

1. Read applicable ADRs

When the developer gives a coding task, the agent runs archgate review-context to read all ADRs that apply to the files being changed. This provides a condensed briefing with the Decision and Do’s and Don’ts sections from each relevant ADR.

2. Write code following ADR constraints

The agent writes code that complies with the constraints from the ADRs. The Do’s and Don’ts sections serve as concrete guardrails.

3. Validate changes

After writing code, the agent runs archgate check to execute automated rules against the changes. Any violations are fixed before proceeding.

4. Reviewer validation

The agent invokes archgate:reviewer to validate structural ADR compliance beyond what automated rules catch.

5. Capture learnings

The agent invokes archgate:lessons-learned to review the work and identify patterns worth capturing as new ADRs.

Tips

• Run onboard once per project to generate your initial ADRs from your actual codebase.
• Keep ADR rule files up to date — the agent enforces what the rules check for.
• Desktop app users: after the first install, restart the Copilot app so it picks up the declared plugin.