Cursor Integration

Archgate integrates with Cursor to give AI agents built-in guardrails. 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

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 agents, skills, and hooks that give Cursor’s AI agent a full guardrails workflow.

The plugin is distributed as an authenticated tarball. The CLI downloads it and extracts skills, agents, and hooks into ~/.cursor/. No CLI detection is needed — files are written directly to the Cursor user directory.

To explicitly install the plugin:

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

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

archgate plugin install --editor cursor

Generated files

User scope (~/.cursor/):

File	Purpose
~/.cursor/skills/archgate-reviewer.md	Validates code changes against all project ADRs
~/.cursor/skills/archgate-lessons-learned.md	Captures learnings and proposes new ADRs when patterns emerge
~/.cursor/skills/archgate-adr-author.md	Creates and edits ADRs following project conventions
~/.cursor/skills/archgate-onboard.md	One-time setup: explores the codebase, interviews you, creates ADRs
~/.cursor/skills/archgate-cli-reference.md	Internal reference for AI agents with the Archgate CLI guide
~/.cursor/agents/archgate-developer.md	Primary development agent with the full ADR guardrails workflow
~/.cursor/agents/archgate-planner.md	Planning agent for scoping and breaking down work

Project scope:

File	Purpose
.cursor/hooks.json	afterFileEdit hook that runs archgate check after every file edit

The .cursor/hooks.json file is the only file written to your project tree. It ensures archgate check runs automatically after every file edit, catching ADR violations in real time.

What the plugin provides

The plugin adds agents and skills to Cursor, installed at the user scope so they are available across all your projects.

Agents

Name	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

Users invoke agents explicitly via /archgate-developer or /archgate-planner in the Cursor chat.

Skills

Name	Purpose
archgate-reviewer	Validates code changes against all project ADRs for structural compliance
archgate-lessons-learned	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 you, creates initial ADRs
archgate-cli-reference	Internal reference for AI agents with the complete Archgate CLI command guide

These are the same roles available in the Claude Code plugin (archgate:reviewer, archgate:lessons-learned, etc.), adapted for Cursor’s skill and agent system.

Hooks

Hook	Trigger	Action
afterFileEdit	Every file edit	Runs archgate check to catch ADR violations in real time

The hook is defined in .cursor/hooks.json at the project level, so it works both locally and in cloud agent environments.

Initial setup with onboard

After installing the plugin, invoke /archgate-developer and ask it to run the onboard skill in your project. 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

Invoke /archgate-developer in Cursor’s chat when starting a coding task. The agent follows a structured workflow for every change:

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 to execute automated rules. The afterFileEdit hook also catches violations in real time. Any violations are fixed before proceeding.

4. Review changes — The agent invokes the archgate-reviewer skill to validate structural ADR compliance beyond what automated rules catch.

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

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	Agent / Skill
Starting a new project with Archgate	/archgate-developer (then ask it to onboard)
Day-to-day coding tasks	/archgate-developer
Planning and scoping work	/archgate-planner
Reviewing a change 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 invoke /archgate-developer and let it run.

Cloud agent support

Cursor supports cloud agents that run on remote VMs. These environments do not have access to ~/.cursor/, so user-scoped skills and agents are not available. However, the .cursor/hooks.json file is part of your project tree and works in cloud VMs. This means archgate check still runs automatically after every file edit, even in cloud agent sessions.

For full governance in cloud environments, ensure archgate is available on the VM’s PATH (e.g., via the install script in your project’s setup).

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

• Invoke /archgate-developer 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 archgate-reviewer for reviews. It validates structural compliance beyond what automated rules catch.
• Use archgate-lessons-learned after resolving tricky issues. It captures learnings so the same mistakes are not repeated.
• Commit the .cursor/ directory. The hooks.json file ensures every team member gets archgate check on file edits 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.
• Re-run archgate plugin install --editor cursor to upgrade. The service returns the latest plugin bundle on every authenticated download.