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 downloads and 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.

To explicitly install the plugin:

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

The plugin bundle is downloaded from plugins.archgate.dev and extracted into the .cursor/ directory. It includes agent rules and skill definitions.

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. Each is invoked as a slash command with the /ag- prefix. The agent orchestrates the governance workflow, invoking skills as needed.

Agent

Slash command	Purpose
/ag-developer	General development agent that reads ADRs before coding and validates after

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

Skills

Slash command	Purpose
/ag-architect	Validates code changes against all project ADRs for structural compliance
/ag-quality-manager	Reviews rule coverage and proposes new ADRs when patterns emerge
/ag-adr-author	Creates and edits ADRs following project conventions
/ag-onboard	One-time setup: explores the codebase, interviews the developer, creates initial ADRs

These are the same agent and skills available in the Claude Code plugin (archgate:developer, archgate:architect, etc.), adapted for Cursor’s slash command interface with the ag- prefix.

Initial setup with onboard

After installing the plugin, run /ag-onboard 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 /ag-developer skill follows a structured workflow for every coding task:

1. Read applicable ADRs — The agent calls 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 to execute automated rules. Any violations are fixed before proceeding.

4. Architect review — The agent invokes /ag-architect to validate structural ADR compliance beyond what automated rules catch.

5. Capture learnings — The agent invokes /ag-quality-manager 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	Slash command
Starting a new project with Archgate	/ag-onboard
Day-to-day coding tasks	/ag-developer
Reviewing a PR for ADR compliance	/ag-architect
Noticing a recurring pattern worth codifying	/ag-quality-manager
Creating or editing an ADR	/ag-adr-author

The /ag-developer agent orchestrates the skills automatically — it invokes /ag-architect and /ag-quality-manager as part of its workflow. Most of the time, you only need to use /ag-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 /ag-developer for coding tasks. It orchestrates the full read-validate-capture workflow automatically.
• Run /ag-onboard once per project. It sets up your initial ADRs based on your actual codebase and conventions.
• Use /ag-architect for PR reviews. It validates structural compliance beyond what automated rules catch.
• Use /ag-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.