Claude Code Plugin
The Archgate Claude Code plugin gives AI agents working in Claude Code a structured governance workflow. 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
Section titled “What the plugin provides”The plugin adds an agent and role-based skills to Claude Code. The agent orchestrates the governance workflow, invoking skills as needed — read decisions before coding, validate after, and capture new patterns for the team.
| Agent | Purpose |
|---|---|
archgate:developer | General development agent that reads ADRs before coding and validates after |
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
Section titled “Skills”| Skill | Purpose |
|---|---|
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 |
Installation
Section titled “Installation”1. Log in with GitHub
Section titled “1. Log in with GitHub”Authenticate with your GitHub account to obtain a plugin token:
archgate loginThis 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
Section titled “2. Initialize your project with the plugin”Run archgate init in your project. If you are already logged in, the plugin is installed automatically:
archgate initTo explicitly request plugin installation:
archgate init --install-pluginThis 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:
claude plugin marketplace add(registers the Archgate marketplace)claude plugin install archgate@archgate(installs the plugin)
If the claude CLI is not found, the command prints the manual commands for you to run.
Installing the plugin on an existing project
Section titled “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 installTo get the authenticated repository URL for manual configuration:
archgate plugin urlInitial setup with onboard
Section titled “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
Section titled “How it works in practice”The plugin follows a structured workflow for every coding task:
1. Read applicable ADRs
Section titled “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 enforced by the archgate:developer skill.
2. Write code following ADR constraints
Section titled “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
Section titled “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
Section titled “4. Architect review”The agent invokes archgate:architect to validate structural ADR compliance beyond what automated rules catch. The architect skill reviews the full context of the changes against all applicable ADRs.
5. Capture learnings
Section titled “5. Capture learnings”The agent invokes archgate:quality-manager to review the work and identify patterns worth capturing. The quality manager may propose new ADRs or updates to existing ones when recurring conventions emerge.
ADR-driven refusal
Section titled “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:
- Refuse, citing ARCH-006 and the approved dependency list
- Suggest using
styleText()fromnode:utilinstead - 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
Section titled “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 domainarchgate check --staged— automated rule checking with violation reportingarchgate adr show <id>— full text of a specific ADRarchgate adr list— inventory of all ADRs in the project with metadataarchgate session-context claude-code— read session transcripts for context recovery
All commands run locally and read directly from your .archgate/adrs/ directory. No data leaves your machine.
When to use each agent or skill
Section titled “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 |
| Reviewing a PR for ADR compliance | archgate:architect |
| Noticing a recurring pattern worth codifying | archgate:quality-manager |
| Creating or editing an ADR | archgate:adr-author |
The archgate:developer agent orchestrates the skills automatically — it invokes archgate:architect and archgate:quality-manager as part of its workflow. Most of the time, you only need to interact with the developer agent directly.