Claude Code Plugin

The Archgate Claude Code plugin gives AI agents working in Claude Code built-in guardrails. Instead of relying on prompt instructions that drift over time, agents read your ADRs directly via Archgate CLI commands and validate their own code against your rules.

What the plugin provides

The plugin adds agents and role-based skills to Claude Code. The developer agent orchestrates the guardrails workflow, invoking skills as needed — read decisions before coding, validate after, and capture new patterns for the team.

Agents

Agent	Purpose
archgate:developer	General development agent that reads ADRs before coding and validates after
archgate:planner	Planning agent for scoping work and breaking tasks into ADR-compliant steps

The archgate:developer agent is set as the default agent via .claude/settings.local.json. 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	Captures learnings 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
archgate:cli-reference	Internal reference for AI agents with the complete Archgate CLI command guide

Installation

Beta access required

The Claude Code plugin is currently in beta. Run archgate login to sign in.

1. Log in to the Archgate platform

Log in to obtain plugin access:

archgate login

This starts an OAuth 2.0 Device Authorization Grant against the Archgate platform. The CLI displays a one-time code and URL — open the URL in your browser, enter the code, and authorize. Once complete, the resulting tokens are handed to your configured git credential helper via git credential approve; an OS-backed helper keeps them encrypted, while git’s built-in store helper writes them in plain text.

2. Initialize your project with the plugin

Run archgate init with the --editor claude flag. If you are already logged in, the plugin is installed automatically:

archgate init --editor claude

Without --editor, an interactive run detects the editors installed on your machine and lets you pick one or more; a non-interactive run (an agent or CI) defaults to Claude Code.

To explicitly request plugin installation:

archgate init --editor claude --install-plugin

This creates .claude/settings.local.json with the archgate:developer agent and skill permissions pre-configured.

If the claude CLI is on your PATH, the plugin is installed automatically via:

1. claude plugin marketplace add https://plugins.archgate.dev/archgate.git (registers the Archgate marketplace)
2. claude plugin install archgate@archgate (installs the plugin)

The marketplace URL carries no credentials — git authenticates against plugins.archgate.dev using the token archgate login handed to your git credential helper.

If the claude CLI is not found, the command prints the manual commands for you to run.

Installing the plugin on an existing project

If your project is already initialized, you can install or reinstall the plugin without re-running archgate init:

archgate plugin install --editor claude

Without --editor, an interactive run prompts you to select editors and a non-interactive run defaults to Claude Code.

To print the plugin repository URL for manual configuration:

archgate plugin url --editor claude

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.

The agent does not write code until it has read the applicable ADRs. This is part of the archgate:developer agent’s workflow.

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 — the agent references them while coding.

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. Review changes

The agent invokes archgate:reviewer to validate structural ADR compliance beyond what automated rules catch. The reviewer skill reviews the full context of the changes against all applicable ADRs.

5. Capture learnings

The agent invokes archgate:lessons-learned to review the work and identify patterns worth capturing. That skill may propose new ADRs or updates to existing ones when recurring conventions emerge.

ADR-driven refusal

When the agent encounters a task that would require violating an ADR, it refuses and explains which ADR would be violated. It then suggests how to achieve the same goal while staying compliant.

For example, if a developer asks the agent to add chalk as a dependency in a project governed by ARCH-006 (dependency policy), the agent will:

1. Refuse, citing ARCH-006 and the approved dependency list
2. Suggest using styleText() from node:util instead
3. Offer to implement the task using the compliant alternative

This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions.

How the plugin accesses ADRs

The plugin uses Archgate CLI commands directly to read ADRs and run compliance checks. The key commands are:

• archgate review-context — condensed briefings of all ADRs applicable to changed files, grouped by domain
• archgate check --staged — automated rule checking with violation reporting
• archgate adr show <id> — full text of a specific ADR
• archgate adr list — inventory of all ADRs in the project with metadata
• archgate session-context — read session transcripts for context recovery

All commands run locally and read directly from your .archgate/adrs/ directory. No ADR or source content leaves your machine.

When to use each agent or skill

Scenario	Agent or skill
Starting a new project with Archgate	archgate:onboard
Day-to-day coding tasks	archgate:developer
Planning and scoping work	archgate:planner
Reviewing a PR for ADR compliance	archgate:reviewer
Noticing a recurring pattern worth codifying	archgate:lessons-learned
Creating or editing an ADR	archgate:adr-author

The archgate:developer agent orchestrates the skills automatically — it invokes archgate:reviewer and archgate:lessons-learned as part of its workflow. Most of the time, you only need to interact with the developer agent directly.