VS Code Plugin

The Archgate VS Code plugin gives AI agents working in VS Code a structured governance workflow. 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.

How it works

VS Code supports agent plugins installed from git-based marketplaces. The Archgate plugin is served from a git repository at plugins.archgate.dev/archgate-vscode.git. When you add this marketplace to your VS Code user settings, VS Code discovers and installs the plugin automatically.

The plugin is served in VS Code Copilot’s native .github/plugin/ manifest format, separate from the Claude Code .claude-plugin/ format.

Installation

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 in ~/.archgate/credentials.

2. Initialize your project with the plugin

Run archgate init with the --editor vscode flag:

archgate init --editor vscode

If you are already logged in, this command:

Creates the .archgate/ governance directory (ADRs, lint rules)
Creates .vscode/mcp.json with the Archgate MCP server configuration
Adds the authenticated marketplace URL to your VS Code user settings

The chat.plugins.marketplaces setting is application-scoped in VS Code, so it cannot be set per-workspace. The CLI automatically writes it to your user-level settings.json:

Platform	User settings path
Windows	`%APPDATA%\Code\User\settings.json`
macOS	`~/Library/Application Support/Code/User/settings.json`
Linux	`~/.config/Code/User/settings.json`

To explicitly request plugin installation:

archgate init --editor vscode --install-plugin

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

archgate plugin install --editor vscode

Generated files

The command creates or updates the following files:

File	Scope	Purpose
`.vscode/mcp.json`	Workspace	MCP server configuration so VS Code can access your ADRs
User `settings.json`	User	`chat.plugins.marketplaces` with the authenticated URL

If .vscode/mcp.json already exists, Archgate merges its configuration additively — existing server entries are preserved. The user settings file is also merged additively — existing settings are never overwritten.

The workspace MCP configuration (.vscode/mcp.json):

{
  "servers": {
    "archgate": {
      "command": "archgate",
      "args": ["mcp"]
    }
  }
}

The user-level marketplace setting (added to your settings.json):

{
  "chat.plugins.marketplaces": [
    "https://<github-user>:<token>@plugins.archgate.dev/archgate-vscode.git"
  ]
}

Manual setup

If you prefer not to let the CLI modify your user settings, you can add the marketplace URL manually. Open VS Code’s user settings JSON (Ctrl+Shift+P → “Preferences: Open User Settings (JSON)”) and add the chat.plugins.marketplaces entry shown above. You can find your authenticated URL by running archgate login and checking ~/.archgate/credentials.

What the plugin provides

The plugin adds role-based skills to VS Code’s AI agent. Each skill encapsulates a specific part of the governance workflow, so agents follow the same process every time.

Skills included

Skill	Purpose
`archgate:developer`	General development agent that reads ADRs before coding and validates after
`archgate:architect`	Validates code changes against all project ADRs for structural compliance
`archgate:quality-manager`	Reviews rule coverage and proposes new ADRs when patterns emerge
`archgate:adr-author`	Creates and edits ADRs following project conventions
`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:

Explores your codebase structure (directories, key files, package configuration)
Interviews you about your team’s conventions, constraints, and architectural decisions
Creates an initial set of ADRs based on your responses
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 reads all ADRs that apply to the files being changed. The MCP server 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. Architect review

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

5. Capture learnings

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

MCP server integration

The plugin communicates with your project’s ADRs through the Archgate MCP server. The server provides:

ADR content — full text of any ADR, accessible by ID
Review context — condensed briefings of all ADRs applicable to a set of changed files
Rule checking — execution of automated rules with violation reporting
ADR listing — inventory of all ADRs in the project with metadata

The MCP server runs locally and reads directly from your .archgate/adrs/ directory. No data leaves your machine.

Tips

Commit .vscode/mcp.json to share the MCP configuration with your team.
Each developer runs archgate init --editor vscode after archgate login to configure their user-level marketplace URL.
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.