Cursor Integration

Archgate integrates with Cursor to give AI agents a structured governance workflow. The agent reads your ADRs before writing code, validates after, and captures new patterns for the team — the same workflow available in the Claude Code plugin.

Setup

Run archgate init with the --editor cursor flag to configure Cursor integration in your project:

archgate init --editor cursor

With plugin (beta)

Beta access required

The Cursor plugin is currently in beta. Run archgate login to sign up and authenticate.

If you have logged in via archgate login, the init command also installs the Archgate plugin for Cursor. The plugin provides pre-built agent rules and skills that give Cursor’s AI agent a full governance workflow.

The plugin is distributed in two ways:

1. Cursor Team Marketplace — The plugin is published to a git-based team marketplace repository. After installation, Cursor discovers it from the team marketplace URL printed by the CLI.
2. VS Code Extension (VSIX) — A .vsix extension is installed into Cursor via the cursor --install-extension command.

To explicitly install the plugin:

archgate login              # one-time setup
archgate init --editor cursor --install-plugin

The archgate plugin install --editor cursor command installs the VS Code extension via cursor CLI if available and prints the team marketplace URL; it prints manual instructions otherwise.

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

archgate plugin install --editor cursor

Without plugin (free)

Without the plugin, archgate init --editor cursor still configures a basic governance rule. The AI agent can consult ADRs and run checks via CLI commands, but does not get the role-based skills described below.

Generated files

File	Purpose
.cursor/rules/archgate-governance.mdc	Always-on Cursor rule that instructs the agent to consult ADRs

What the plugin provides

The plugin adds an agent and role-based skills to Cursor. Cursor’s plugin system handles namespacing, so skills use their direct names without a prefix.

Agent

Name	Purpose
developer	General development agent that reads ADRs before coding and validates after

The developer agent orchestrates the skills below automatically as part of its workflow.

Skills

Name	Purpose
architect	Validates code changes against all project ADRs for structural compliance
quality-manager	Reviews rule coverage and proposes new ADRs when patterns emerge
adr-author	Creates and edits ADRs following project conventions
onboard	One-time setup: explores the codebase, interviews the developer, creates initial ADRs
cli-reference	Internal reference for AI agents with the complete Archgate CLI command guide

These are the same agent and skills available in the Claude Code plugin (archgate:developer, archgate:architect, etc.), adapted for Cursor’s plugin system.

Initial setup with onboard

After installing the plugin, run the 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

With the plugin

The developer agent follows a structured workflow for every coding task:

1. Read applicable ADRs — The agent runs archgate review-context to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs.

2. Write code following ADR constraints — The agent implements changes following the Do’s and Don’ts from the applicable ADRs.

3. Run compliance checks — The agent runs archgate check --staged to execute automated rules. Any violations are fixed before proceeding.

4. Architect review — The agent invokes the architect skill to validate structural ADR compliance beyond what automated rules catch.

5. Capture learnings — The agent invokes the quality-manager skill to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.

Without the plugin

The agent uses the governance rule and CLI commands to follow four manual steps:

1. Review context — Run archgate review-context to see which ADRs apply to the files being changed.

2. Read individual ADRs — For full context on a specific decision, run archgate adr show <id> (for example, archgate adr show ARCH-001).

3. Write code — Implement changes following the constraints from the applicable ADRs.

4. Run compliance checks — Run archgate check --staged to validate that the code complies with all ADR rules.

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 a dependency policy ADR, the agent will:

1. Refuse, citing the ADR and the approved dependency list
2. Suggest using the approved alternative instead
3. Offer to implement the task using the compliant approach

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

When to use each agent or skill

Scenario	Skill
Starting a new project with Archgate	onboard
Day-to-day coding tasks	developer
Reviewing a PR for ADR compliance	architect
Noticing a recurring pattern worth codifying	quality-manager
Creating or editing an ADR	adr-author

The developer agent orchestrates the skills automatically — it invokes architect and quality-manager as part of its workflow. Most of the time, you only need to use developer directly.

Governance rule

The governance rule in .cursor/rules/archgate-governance.mdc uses alwaysApply: true, which means the Cursor agent always has governance context available without manual activation. It instructs the agent to run archgate review-context before coding and archgate check --staged after.

Session transcript access

The archgate session-context cursor command reads Cursor agent session transcripts from disk. This allows skills to access the history of the current conversation, which is useful for recovering context that may have been compacted or truncated.

The command accepts two optional flags:

• --max-entries <n> — Maximum number of entries to return (default: 200, most recent entries).
• --session-id <uuid> — A specific session UUID to read. If omitted, the most recent session is used.

Tips for effective usage

• Use the developer skill for coding tasks. It orchestrates the full read-validate-capture workflow automatically.
• Run onboard once per project. It sets up your initial ADRs based on your actual codebase and conventions.
• Use architect for PR reviews. It validates structural compliance beyond what automated rules catch.
• Use quality-manager after resolving tricky issues. It captures learnings so the same mistakes are not repeated.
• Commit the .cursor/ directory. This ensures every team member gets the same governance configuration when they clone the repository.
• Keep ADR rules files up to date. The agent enforces what the rules check for — if a rule is missing, the violation will not be caught.