From e857809333c12e79e32af2a86808c4f524cc0da9 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Thu, 4 Jun 2026 00:02:21 +0200 Subject: [PATCH 1/7] feat(cursor): automated plugin install via tarball download Replace the manual Team Marketplace URL instructions with automated tarball-based installation, matching the opencode plugin install pattern. `archgate plugin install --editor cursor` now downloads the Cursor direct-install tarball from GET /api/cursor and extracts it into ~/.cursor/{skills,agents,rules}/, making archgate skills, agents, and governance rules available globally for `cursor agent` sessions. `archgate init --editor cursor` now writes project-level governance files (.cursor/rules/archgate-governance.mdc + .cursor/hooks.json) for cloud agent compatibility, and auto-installs the user-level components when credentials are available. Changes: - Add installCursorPlugin() to plugin-install.ts (download + extract) - Add mergeCursorHooks() for safe hooks.json merging - Add cursorUserDir() path helper - Update configureCursorSettings() to write project-level governance - Update installForEditor/printManualInstructions for cursor - Update tryInstallPlugin in init-project.ts for auto-install - Update all cursor-related tests Signed-off-by: Rhuan Barreto --- src/commands/init.ts | 29 ++++--- src/commands/plugin/install.ts | 23 ++---- src/helpers/cursor-settings.ts | 95 ++++++++++++++++++++--- src/helpers/init-project.ts | 17 ++++- src/helpers/paths.ts | 13 ++++ src/helpers/plugin-install.ts | 106 +++++++++++++++++++++++++- tests/commands/plugin/install.test.ts | 12 ++- tests/helpers/cursor-settings.test.ts | 43 ++++++++++- tests/helpers/init-project.test.ts | 22 +++--- tests/integration/init.test.ts | 9 ++- 10 files changed, 297 insertions(+), 72 deletions(-) diff --git a/src/commands/init.ts b/src/commands/init.ts index 47090df7..0f40844d 100644 --- a/src/commands/init.ts +++ b/src/commands/init.ts @@ -31,9 +31,9 @@ import { isTlsError, tlsHintMessage } from "../helpers/tls"; const EDITOR_DIRS: Record = { claude: ".claude/", - // Cursor plugin is embedded in the VSIX extension — no project-level - // files are written. Shown as a label in the init summary. - cursor: "(VSIX)", + // Cursor governance rule + hooks are written to .cursor/ in the project. + // Skills and agents are installed to ~/.cursor/ (user-scope). + cursor: ".cursor/", vscode: ".vscode/", copilot: ".github/copilot/", // Opencode agents install to a user-scope directory, not the project tree. @@ -350,19 +350,16 @@ function printManualInstructions(editor: EditorTarget, detail?: string): void { } break; case "cursor": - if (detail && !detail.startsWith("download")) { - // detail is the VSIX path or the error message from installCursorPlugin - logWarn("Cursor CLI not found. The VSIX has been downloaded:"); - console.log(` ${styleText("bold", detail)}`); - console.log( - ` Open Cursor → Ctrl+Shift+P → ${styleText("bold", "Extensions: Install from VSIX...")} → select the file above` - ); - } else { - logWarn( - "Could not download the VSIX. Retry with:", - ` ${styleText("bold", "archgate plugin install --editor cursor")}` - ); - } + logWarn( + "Failed to install Cursor components.", + detail ?? "Check your credentials and retry." + ); + console.log( + ` Retry with: ${styleText("bold", "archgate plugin install --editor cursor")}` + ); + console.log( + ` If the token has expired: ${styleText("bold", "archgate login refresh")}` + ); break; default: // vscode auto-install — should not reach here diff --git a/src/commands/plugin/install.ts b/src/commands/plugin/install.ts index 10f9fc8f..af2cfd13 100644 --- a/src/commands/plugin/install.ts +++ b/src/commands/plugin/install.ts @@ -16,7 +16,6 @@ import type { EditorTarget } from "../../helpers/init-project"; import { logError, logInfo, logWarn } from "../../helpers/log"; import { findProjectRoot } from "../../helpers/paths"; import { - buildCursorMarketplaceUrl, buildMarketplaceUrl, buildVscodeMarketplaceUrl, installClaudePlugin, @@ -83,16 +82,12 @@ export async function installForEditor( break; } case "cursor": { - // Cursor supports plugins via Team Private Marketplaces — not VSIX. - // See https://cursor.com/docs/plugins#team-marketplaces - const url = buildCursorMarketplaceUrl(); - logInfo( - `To install the Archgate plugin for ${label}, add the team marketplace URL in Cursor Settings:` - ); - console.log(` ${styleText("bold", url)}`); - console.log( - ` Cursor Settings → Extensions → Team Private Plugin Marketplaces → Add URL` - ); + // Install directly into ~/.cursor/{skills,agents,rules}/ — Cursor's + // plugin subsystem is unreliable in CLI mode and absent in cloud. + const { installCursorPlugin } = + await import("../../helpers/plugin-install"); + await installCursorPlugin(token); + logInfo(`Archgate plugin installed for ${label}.`); break; } case "opencode": { @@ -166,11 +161,9 @@ export function printManualInstructions(editor: EditorTarget): void { break; } case "cursor": { - const url = buildCursorMarketplaceUrl(); - logInfo("Add the team marketplace URL in Cursor Settings:"); - console.log(` ${styleText("bold", url)}`); + logInfo("To install the plugin manually, run:"); console.log( - ` Cursor Settings → Extensions → Team Private Plugin Marketplaces → Add URL` + ` ${styleText("bold", "archgate plugin install --editor cursor")}` ); break; } diff --git a/src/helpers/cursor-settings.ts b/src/helpers/cursor-settings.ts index a5b18693..8568aad9 100644 --- a/src/helpers/cursor-settings.ts +++ b/src/helpers/cursor-settings.ts @@ -3,27 +3,98 @@ /** * Cursor editor integration. * - * The archgate Cursor plugin (skills, agents, governance rules) is now - * embedded inside the VS Code extension (.vsix). When the extension - * activates in Cursor it calls `vscode.cursor.plugins.registerPath()` - * to expose the plugin — no project-level files are needed. + * Cursor has evolved from an IDE to an agent platform — users primarily + * use `cursor agent` (CLI) and cloud agents. Archgate components (skills, + * agents, rules, hooks) are installed directly into Cursor's discovery + * directories (`~/.cursor/{skills,agents,rules}/`) via an authenticated + * tarball download, bypassing Cursor's plugin subsystem which is + * unreliable in CLI mode and absent in cloud environments. * - * `configureCursorSettings` is kept as a no-op for call-site - * compatibility (init-project.ts, etc.) and returns the `.cursor/` - * directory path for the init summary output. + * `configureCursorSettings` writes project-level governance files + * (`.cursor/rules/` and `.cursor/hooks.json`) for cloud agent + * compatibility — cloud VMs have no `~/.cursor/` user config. */ +import { existsSync, mkdirSync, writeFileSync } from "node:fs"; import { join } from "node:path"; +import { logDebug } from "./log"; + /** - * Configure Cursor settings for archgate integration. + * Configure project-level Cursor settings for archgate integration. * - * No-op — the archgate VSIX extension embeds the Cursor plugin and - * registers it via `vscode.cursor.plugins.registerPath()` at runtime. - * No project-level files are written. + * Writes governance files that cloud agents and local `cursor agent` can + * discover from the project: + * - `.cursor/rules/archgate-governance.mdc` — always-on governance rule + * - `.cursor/hooks.json` — afterFileEdit hook for archgate check * * @returns Path to the `.cursor/` directory (for init summary display). */ export function configureCursorSettings(projectRoot: string): string { - return join(projectRoot, ".cursor"); + const cursorDir = join(projectRoot, ".cursor"); + const rulesDir = join(cursorDir, "rules"); + mkdirSync(rulesDir, { recursive: true }); + + // Write governance rule (.mdc) + const rulePath = join(rulesDir, "archgate-governance.mdc"); + if (!existsSync(rulePath)) { + writeFileSync(rulePath, GOVERNANCE_RULE, "utf-8"); + logDebug("Wrote Cursor governance rule:", rulePath); + } + + // Write hooks.json + const hooksPath = join(cursorDir, "hooks.json"); + if (!existsSync(hooksPath)) { + writeFileSync( + hooksPath, + JSON.stringify(HOOKS_JSON, null, 2) + "\n", + "utf-8" + ); + logDebug("Wrote Cursor hooks:", hooksPath); + } + + return cursorDir; } + +const GOVERNANCE_RULE = `--- +description: Archgate ADR governance — enforces architecture decision records +globs: +alwaysApply: true +--- + +# Archgate Governance + +This project uses Archgate to enforce Architecture Decision Records (ADRs). ADRs encode the team's architectural decisions so every contributor — human or AI — builds consistently. + +## Key principle + +Architectural decisions are enforced, not suggested. ADR violations are **hard blockers**. + +## Before writing code + +- Run \`archgate review-context\` to get applicable ADR briefings for changed files +- Review the Decision and Do's/Don'ts sections of each applicable ADR + +## After writing code + +- Run \`archgate check --staged\` to validate compliance with all ADR rules +- Fix any violations before considering work complete + +## ADR commands + +- \`archgate adr list\` — List all active ADRs with metadata +- \`archgate check --staged\` — Run automated compliance checks +- \`archgate review-context\` — Get changed files grouped by domain with ADR briefings + +## CLI installation + +If \`archgate\` is not installed: \`curl -fsSL https://cli.archgate.dev/install-unix | sh\` +`; + +const HOOKS_JSON = [ + { + event: "afterFileEdit", + type: "command", + command: "archgate check ${filePath} --json 2>/dev/null || true", + }, +]; diff --git a/src/helpers/init-project.ts b/src/helpers/init-project.ts index 19a77c77..2ab370b1 100644 --- a/src/helpers/init-project.ts +++ b/src/helpers/init-project.ts @@ -264,10 +264,19 @@ async function tryInstallPlugin(editor: EditorTarget): Promise { } if (editor === "cursor") { - // Cursor uses Team Private Plugin Marketplaces — not VSIX or CLI install. - // The user must add the marketplace URL manually in Cursor Settings. - const { buildCursorMarketplaceUrl } = await import("./plugin-install"); - return { installed: true, detail: buildCursorMarketplaceUrl() }; + // Install directly into ~/.cursor/{skills,agents,rules}/ — Cursor's + // plugin subsystem is unreliable in CLI mode and absent in cloud. + const { installCursorPlugin } = await import("./plugin-install"); + try { + await installCursorPlugin(credentials.token); + return { installed: true, autoInstalled: true }; + } catch (error) { + logDebug("Failed to install Cursor components:", error); + return { + installed: true, + detail: error instanceof Error ? error.message : String(error), + }; + } } if (editor === "vscode") { diff --git a/src/helpers/paths.ts b/src/helpers/paths.ts index 1427cf8f..78bcbfae 100644 --- a/src/helpers/paths.ts +++ b/src/helpers/paths.ts @@ -94,6 +94,19 @@ export function opencodeDbPath(): string { return join(base, "opencode", "opencode.db"); } +/** + * Resolve the Cursor user-scope config directory (`~/.cursor/`). + * + * Cursor discovers skills, agents, and rules from `~/.cursor/{skills,agents,rules}/`. + * These are user-level (global) — they apply to all projects when using + * `cursor agent` locally. Cloud VMs do NOT have this directory. + * + * Resolved at call time (not cached) so tests can override HOME. + */ +export function cursorUserDir(): string { + return join(archgateHomeDir(), ".cursor"); +} + export const paths = { cacheFolder: internalPath("cache") } as const; export function projectPath(projectRoot: string, ...path: string[]) { diff --git a/src/helpers/plugin-install.ts b/src/helpers/plugin-install.ts index 251bf990..4c0928dc 100644 --- a/src/helpers/plugin-install.ts +++ b/src/helpers/plugin-install.ts @@ -2,10 +2,11 @@ // Copyright 2026 Archgate /** Download and install the archgate plugin for supported editors. */ -import { mkdirSync, unlinkSync } from "node:fs"; +import { existsSync, mkdirSync, unlinkSync } from "node:fs"; +import { join } from "node:path"; import { logDebug } from "./log"; -import { internalPath, opencodeAgentsDir } from "./paths"; +import { cursorUserDir, internalPath, opencodeAgentsDir } from "./paths"; import { resolveCommand } from "./platform"; const PLUGINS_API = "https://plugins.archgate.dev"; @@ -120,6 +121,107 @@ export async function installClaudePlugin(): Promise { } } +// --------------------------------------------------------------------------- +// Cursor — download and extract into user-scope discovery dirs +// --------------------------------------------------------------------------- + +/** + * Install the archgate Cursor components into user-scope discovery dirs. + * + * Cursor discovers skills, agents, and rules from `~/.cursor/{skills,agents,rules}/`. + * The tarball from /api/cursor contains these at its root: + * - skills/archgate-{name}/SKILL.md — skill definitions + * - agents/archgate-{name}.md — agent definitions + * - rules/archgate-governance.mdc — governance rule + * - hooks.json — afterFileEdit hook for archgate check + * + * Extraction uses `tar` via `Bun.spawn` — `tar` is available on macOS, + * Linux, and modern Windows (bsdtar ships with Windows 10+). + * + * After extraction, `hooks.json` is merged into `~/.cursor/hooks.json` + * (rather than extracted as-is) to avoid overwriting existing user hooks. + * + * Throws on download or extraction failure so callers can surface a manual + * retry hint. + */ +export async function installCursorPlugin(token: string): Promise { + const tarballPath = internalPath("archgate-cursor.tar.gz"); + const cursorDir = cursorUserDir(); + + const buffer = await downloadPluginAsset("/api/cursor", token); + logDebug( + `Downloaded Cursor install bundle (${Math.round(buffer.byteLength / 1024)} KB)` + ); + await Bun.write(tarballPath, buffer); + + try { + // Ensure target dirs exist — tar will write files, but it won't create + // the enclosing `~/.cursor/{skills,agents,rules}/` paths. + mkdirSync(join(cursorDir, "skills"), { recursive: true }); + mkdirSync(join(cursorDir, "agents"), { recursive: true }); + mkdirSync(join(cursorDir, "rules"), { recursive: true }); + + logDebug(`Extracting Cursor components into ${cursorDir}`); + const result = await run(["tar", "-xzf", tarballPath, "-C", cursorDir]); + if (result.exitCode !== 0) { + throw new Error( + `tar -xzf failed (exit ${result.exitCode}) while extracting Cursor components` + ); + } + + // Merge hooks.json into ~/.cursor/hooks.json instead of leaving the + // extracted copy (which would be at ~/.cursor/hooks.json and would + // overwrite existing user hooks). The tarball extracts it, so we + // merge the archgate hooks into any existing hooks file. + await mergeCursorHooks(cursorDir); + } finally { + try { + unlinkSync(tarballPath); + } catch { + // Ignore cleanup errors + } + } +} + +/** + * Merge archgate hooks into `~/.cursor/hooks.json`. + * + * If the file already exists, reads it, removes any previous archgate hooks + * (identified by the archgate check command), appends the new ones, and + * writes back. If it doesn't exist, uses the extracted file as-is. + */ +async function mergeCursorHooks(cursorDir: string): Promise { + const hooksPath = join(cursorDir, "hooks.json"); + if (!existsSync(hooksPath)) return; + + try { + const existing: { event: string; command?: string }[] = JSON.parse( + await Bun.file(hooksPath).text() + ); + + // Remove any previous archgate hooks + const filtered = existing.filter( + (h) => !h.command?.includes("archgate check") + ); + + // Add our hooks + const archgateHooks = [ + { + event: "afterFileEdit", + type: "command", + command: "archgate check ${filePath} --json 2>/dev/null || true", + }, + ]; + + const merged = [...filtered, ...archgateHooks]; + await Bun.write(hooksPath, JSON.stringify(merged, null, 2) + "\n"); + logDebug("Merged archgate hooks into", hooksPath); + } catch { + // If existing hooks.json is malformed, leave it alone + logDebug("Could not merge hooks.json — leaving existing file"); + } +} + // --------------------------------------------------------------------------- // Shared — authenticated asset download // --------------------------------------------------------------------------- diff --git a/tests/commands/plugin/install.test.ts b/tests/commands/plugin/install.test.ts index e612d8f5..b9c693bb 100644 --- a/tests/commands/plugin/install.test.ts +++ b/tests/commands/plugin/install.test.ts @@ -23,6 +23,7 @@ const mockInstallClaudePlugin = mock(() => Promise.resolve()); const mockInstallCopilotPlugin = mock(() => Promise.resolve()); const mockInstallVscodeExtension = mock((_token: string) => Promise.resolve()); const mockInstallOpencodePlugin = mock((_token: string) => Promise.resolve()); +const mockInstallCursorPlugin = mock((_token: string) => Promise.resolve()); const mockIsClaudeCliAvailable = mock(() => Promise.resolve(false)); const mockIsCopilotCliAvailable = mock(() => Promise.resolve(false)); const mockIsVscodeCliAvailable = mock(() => Promise.resolve(false)); @@ -37,6 +38,7 @@ mock.module("../../../src/helpers/plugin-install", () => ({ installCopilotPlugin: mockInstallCopilotPlugin, installVscodeExtension: mockInstallVscodeExtension, installOpencodePlugin: mockInstallOpencodePlugin, + installCursorPlugin: mockInstallCursorPlugin, isClaudeCliAvailable: mockIsClaudeCliAvailable, isCopilotCliAvailable: mockIsCopilotCliAvailable, isVscodeCliAvailable: mockIsVscodeCliAvailable, @@ -229,19 +231,15 @@ describe("plugin install action", () => { expect(warnSpy).toHaveBeenCalled(); }); - test("prints cursor marketplace URL for --editor cursor", async () => { + test("installs cursor plugin for --editor cursor", async () => { mockLoadCredentials.mockImplementation(() => Promise.resolve({ token: "tok", github_user: "user" }) ); await runInstall(["--editor", "cursor"]); - // Cursor case prints URL, never calls an install function - expect(logSpy).toHaveBeenCalled(); - const allLogOutput = logSpy.mock.calls - .map((c: unknown[]) => String(c[0])) - .join("\n"); - expect(allLogOutput).toContain("Cursor Settings"); + // Cursor case calls installCursorPlugin with the token + expect(mockInstallCursorPlugin).toHaveBeenCalledWith("tok"); }); test("installs copilot plugin when CLI is available", async () => { diff --git a/tests/helpers/cursor-settings.test.ts b/tests/helpers/cursor-settings.test.ts index 04738412..3d5e7823 100644 --- a/tests/helpers/cursor-settings.test.ts +++ b/tests/helpers/cursor-settings.test.ts @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // Copyright 2026 Archgate import { describe, expect, test, beforeEach, afterEach } from "bun:test"; -import { mkdtempSync, rmSync, existsSync } from "node:fs"; +import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -18,13 +18,48 @@ describe("configureCursorSettings", () => { rmSync(tempDir, { recursive: true, force: true }); }); - test("returns .cursor/ directory path (no files written)", () => { + test("returns .cursor/ directory path", () => { const result = configureCursorSettings(tempDir); expect(result).toBe(join(tempDir, ".cursor")); }); - test("does not create .cursor/ directory", () => { + test("creates .cursor/rules/ directory and governance rule", () => { configureCursorSettings(tempDir); - expect(existsSync(join(tempDir, ".cursor"))).toBe(false); + expect(existsSync(join(tempDir, ".cursor", "rules"))).toBe(true); + const rulePath = join( + tempDir, + ".cursor", + "rules", + "archgate-governance.mdc" + ); + expect(existsSync(rulePath)).toBe(true); + const content = readFileSync(rulePath, "utf-8"); + expect(content).toContain("alwaysApply: true"); + expect(content).toContain("archgate check"); + }); + + test("creates .cursor/hooks.json", () => { + configureCursorSettings(tempDir); + const hooksPath = join(tempDir, ".cursor", "hooks.json"); + expect(existsSync(hooksPath)).toBe(true); + const hooks = JSON.parse(readFileSync(hooksPath, "utf-8")); + expect(hooks).toBeArrayOfSize(1); + expect(hooks[0].event).toBe("afterFileEdit"); + expect(hooks[0].command).toContain("archgate check"); + }); + + test("does not overwrite existing governance rule", async () => { + configureCursorSettings(tempDir); + // Write a custom rule + const rulePath = join( + tempDir, + ".cursor", + "rules", + "archgate-governance.mdc" + ); + await Bun.write(rulePath, "custom rule"); + // Re-run — should not overwrite + configureCursorSettings(tempDir); + expect(readFileSync(rulePath, "utf-8")).toBe("custom rule"); }); }); diff --git a/tests/helpers/init-project.test.ts b/tests/helpers/init-project.test.ts index 7d2762a9..47c492f6 100644 --- a/tests/helpers/init-project.test.ts +++ b/tests/helpers/init-project.test.ts @@ -72,11 +72,14 @@ describe("initProject", () => { ); }); - test("configures Cursor settings when editor is cursor (no project files)", async () => { + test("configures Cursor settings when editor is cursor (writes project files)", async () => { const result = await initProject(tempDir, { editor: "cursor" }); - // Cursor plugin is embedded in the VSIX — no project-level files written - expect(existsSync(join(tempDir, ".cursor"))).toBe(false); + // Cursor governance rule and hooks are written to .cursor/ + expect( + existsSync(join(tempDir, ".cursor", "rules", "archgate-governance.mdc")) + ).toBe(true); + expect(existsSync(join(tempDir, ".cursor", "hooks.json"))).toBe(true); // Claude settings should NOT exist expect(existsSync(join(tempDir, ".claude", "settings.local.json"))).toBe( @@ -267,21 +270,22 @@ describe("tryInstallPlugin via initProject", () => { expect(result.plugin!.detail).toContain("No stored credentials"); }); - test("cursor returns marketplace URL", async () => { + test("cursor installs via tarball download", async () => { credSpy.mockResolvedValue({ token: "tok", github_user: "user" }); - const urlSpy = spyOn( + const installSpy = spyOn( pluginInstall, - "buildCursorMarketplaceUrl" - ).mockReturnValue("https://cursor.example"); + "installCursorPlugin" + ).mockResolvedValue(); try { const result = await initProject(tempDir, { installPlugin: true, editor: "cursor", }); expect(result.plugin!.installed).toBe(true); - expect(result.plugin!.detail).toBe("https://cursor.example"); + expect(result.plugin!.autoInstalled).toBe(true); + expect(installSpy).toHaveBeenCalledWith("tok"); } finally { - urlSpy.mockRestore(); + installSpy.mockRestore(); } }); diff --git a/tests/integration/init.test.ts b/tests/integration/init.test.ts index 68ee1b42..4f70d4a4 100644 --- a/tests/integration/init.test.ts +++ b/tests/integration/init.test.ts @@ -55,7 +55,7 @@ describe("init integration", () => { ); }); - test("init with --editor cursor does not create project-level files", async () => { + test("init with --editor cursor creates project-level governance files", async () => { const result = await runCli( ["init", "--editor", "cursor"], tempDir, @@ -64,8 +64,11 @@ describe("init integration", () => { expect(result.exitCode).toBe(0); - // Cursor plugin is embedded in the VSIX — no .cursor/ files written - expect(existsSync(join(tempDir, ".cursor"))).toBe(false); + // Cursor governance rule and hooks are written to .cursor/ + expect( + existsSync(join(tempDir, ".cursor", "rules", "archgate-governance.mdc")) + ).toBe(true); + expect(existsSync(join(tempDir, ".cursor", "hooks.json"))).toBe(true); }); test("init with --editor copilot creates copilot directory", async () => { From e296e23c46fa10a7e3aa4757b5fa381d60cf00e6 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Fri, 5 Jun 2026 13:58:14 +0200 Subject: [PATCH 2/7] chore: remove governance rule from project-level Cursor init MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cursor doesn't support user-level rule files — user rules are configured only via the Settings UI. The governance rule as a prompt-level hint can't enforce agent delegation, making it noise. Keep only .cursor/hooks.json (afterFileEdit → archgate check) which provides mechanical enforcement regardless of which agent is active. Signed-off-by: Rhuan Barreto --- src/helpers/cursor-settings.ts | 60 ++++----------------------- tests/helpers/cursor-settings.test.ts | 37 +++++------------ tests/helpers/init-project.test.ts | 8 ++-- tests/integration/init.test.ts | 6 +-- 4 files changed, 25 insertions(+), 86 deletions(-) diff --git a/src/helpers/cursor-settings.ts b/src/helpers/cursor-settings.ts index 8568aad9..c0034ef8 100644 --- a/src/helpers/cursor-settings.ts +++ b/src/helpers/cursor-settings.ts @@ -5,14 +5,14 @@ * * Cursor has evolved from an IDE to an agent platform — users primarily * use `cursor agent` (CLI) and cloud agents. Archgate components (skills, - * agents, rules, hooks) are installed directly into Cursor's discovery - * directories (`~/.cursor/{skills,agents,rules}/`) via an authenticated + * agents, hooks) are installed directly into Cursor's discovery + * directories (`~/.cursor/{skills,agents}/`) via an authenticated * tarball download, bypassing Cursor's plugin subsystem which is * unreliable in CLI mode and absent in cloud environments. * - * `configureCursorSettings` writes project-level governance files - * (`.cursor/rules/` and `.cursor/hooks.json`) for cloud agent - * compatibility — cloud VMs have no `~/.cursor/` user config. + * `configureCursorSettings` writes a project-level hooks file + * (`.cursor/hooks.json`) for cloud agent compatibility — cloud VMs + * have no `~/.cursor/` user config. */ import { existsSync, mkdirSync, writeFileSync } from "node:fs"; @@ -23,24 +23,15 @@ import { logDebug } from "./log"; /** * Configure project-level Cursor settings for archgate integration. * - * Writes governance files that cloud agents and local `cursor agent` can - * discover from the project: - * - `.cursor/rules/archgate-governance.mdc` — always-on governance rule + * Writes hooks that cloud agents and local `cursor agent` can discover + * from the project: * - `.cursor/hooks.json` — afterFileEdit hook for archgate check * * @returns Path to the `.cursor/` directory (for init summary display). */ export function configureCursorSettings(projectRoot: string): string { const cursorDir = join(projectRoot, ".cursor"); - const rulesDir = join(cursorDir, "rules"); - mkdirSync(rulesDir, { recursive: true }); - - // Write governance rule (.mdc) - const rulePath = join(rulesDir, "archgate-governance.mdc"); - if (!existsSync(rulePath)) { - writeFileSync(rulePath, GOVERNANCE_RULE, "utf-8"); - logDebug("Wrote Cursor governance rule:", rulePath); - } + mkdirSync(cursorDir, { recursive: true }); // Write hooks.json const hooksPath = join(cursorDir, "hooks.json"); @@ -56,41 +47,6 @@ export function configureCursorSettings(projectRoot: string): string { return cursorDir; } -const GOVERNANCE_RULE = `--- -description: Archgate ADR governance — enforces architecture decision records -globs: -alwaysApply: true ---- - -# Archgate Governance - -This project uses Archgate to enforce Architecture Decision Records (ADRs). ADRs encode the team's architectural decisions so every contributor — human or AI — builds consistently. - -## Key principle - -Architectural decisions are enforced, not suggested. ADR violations are **hard blockers**. - -## Before writing code - -- Run \`archgate review-context\` to get applicable ADR briefings for changed files -- Review the Decision and Do's/Don'ts sections of each applicable ADR - -## After writing code - -- Run \`archgate check --staged\` to validate compliance with all ADR rules -- Fix any violations before considering work complete - -## ADR commands - -- \`archgate adr list\` — List all active ADRs with metadata -- \`archgate check --staged\` — Run automated compliance checks -- \`archgate review-context\` — Get changed files grouped by domain with ADR briefings - -## CLI installation - -If \`archgate\` is not installed: \`curl -fsSL https://cli.archgate.dev/install-unix | sh\` -`; - const HOOKS_JSON = [ { event: "afterFileEdit", diff --git a/tests/helpers/cursor-settings.test.ts b/tests/helpers/cursor-settings.test.ts index 3d5e7823..b39b3b6b 100644 --- a/tests/helpers/cursor-settings.test.ts +++ b/tests/helpers/cursor-settings.test.ts @@ -23,23 +23,9 @@ describe("configureCursorSettings", () => { expect(result).toBe(join(tempDir, ".cursor")); }); - test("creates .cursor/rules/ directory and governance rule", () => { - configureCursorSettings(tempDir); - expect(existsSync(join(tempDir, ".cursor", "rules"))).toBe(true); - const rulePath = join( - tempDir, - ".cursor", - "rules", - "archgate-governance.mdc" - ); - expect(existsSync(rulePath)).toBe(true); - const content = readFileSync(rulePath, "utf-8"); - expect(content).toContain("alwaysApply: true"); - expect(content).toContain("archgate check"); - }); - - test("creates .cursor/hooks.json", () => { + test("creates .cursor/ directory with hooks.json", () => { configureCursorSettings(tempDir); + expect(existsSync(join(tempDir, ".cursor"))).toBe(true); const hooksPath = join(tempDir, ".cursor", "hooks.json"); expect(existsSync(hooksPath)).toBe(true); const hooks = JSON.parse(readFileSync(hooksPath, "utf-8")); @@ -48,18 +34,17 @@ describe("configureCursorSettings", () => { expect(hooks[0].command).toContain("archgate check"); }); - test("does not overwrite existing governance rule", async () => { + test("does not create rules directory", () => { configureCursorSettings(tempDir); - // Write a custom rule - const rulePath = join( - tempDir, - ".cursor", - "rules", - "archgate-governance.mdc" - ); - await Bun.write(rulePath, "custom rule"); + expect(existsSync(join(tempDir, ".cursor", "rules"))).toBe(false); + }); + + test("does not overwrite existing hooks.json", async () => { + configureCursorSettings(tempDir); + const hooksPath = join(tempDir, ".cursor", "hooks.json"); + await Bun.write(hooksPath, "custom hooks"); // Re-run — should not overwrite configureCursorSettings(tempDir); - expect(readFileSync(rulePath, "utf-8")).toBe("custom rule"); + expect(readFileSync(hooksPath, "utf-8")).toBe("custom hooks"); }); }); diff --git a/tests/helpers/init-project.test.ts b/tests/helpers/init-project.test.ts index 47c492f6..53d41b87 100644 --- a/tests/helpers/init-project.test.ts +++ b/tests/helpers/init-project.test.ts @@ -75,11 +75,11 @@ describe("initProject", () => { test("configures Cursor settings when editor is cursor (writes project files)", async () => { const result = await initProject(tempDir, { editor: "cursor" }); - // Cursor governance rule and hooks are written to .cursor/ - expect( - existsSync(join(tempDir, ".cursor", "rules", "archgate-governance.mdc")) - ).toBe(true); + // Cursor hooks are written to .cursor/ (no governance rule — Cursor + // doesn't support user-level rules as files, and the rule alone can't + // enforce agent delegation) expect(existsSync(join(tempDir, ".cursor", "hooks.json"))).toBe(true); + expect(existsSync(join(tempDir, ".cursor", "rules"))).toBe(false); // Claude settings should NOT exist expect(existsSync(join(tempDir, ".claude", "settings.local.json"))).toBe( diff --git a/tests/integration/init.test.ts b/tests/integration/init.test.ts index 4f70d4a4..256df75f 100644 --- a/tests/integration/init.test.ts +++ b/tests/integration/init.test.ts @@ -64,11 +64,9 @@ describe("init integration", () => { expect(result.exitCode).toBe(0); - // Cursor governance rule and hooks are written to .cursor/ - expect( - existsSync(join(tempDir, ".cursor", "rules", "archgate-governance.mdc")) - ).toBe(true); + // Cursor hooks are written to .cursor/ (no governance rule) expect(existsSync(join(tempDir, ".cursor", "hooks.json"))).toBe(true); + expect(existsSync(join(tempDir, ".cursor", "rules"))).toBe(false); }); test("init with --editor copilot creates copilot directory", async () => { From 87301218e9737fb258f40ac4c7a02dd2c9b124da Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Fri, 5 Jun 2026 16:44:38 +0200 Subject: [PATCH 3/7] fix: remove stale rules references from Cursor install The plugins PR dropped the governance rule from the tarball, but the CLI still referenced ~/.cursor/rules/ in comments, JSDoc, and created the directory during install. Align with the merged plugins output: tarball contains only skills/, agents/, and hooks.json. Signed-off-by: Rhuan Barreto --- src/commands/plugin/install.ts | 2 +- src/helpers/init-project.ts | 2 +- src/helpers/paths.ts | 2 +- src/helpers/plugin-install.ts | 6 ++---- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/src/commands/plugin/install.ts b/src/commands/plugin/install.ts index af2cfd13..ebb18b64 100644 --- a/src/commands/plugin/install.ts +++ b/src/commands/plugin/install.ts @@ -82,7 +82,7 @@ export async function installForEditor( break; } case "cursor": { - // Install directly into ~/.cursor/{skills,agents,rules}/ — Cursor's + // Install directly into ~/.cursor/{skills,agents}/ — Cursor's // plugin subsystem is unreliable in CLI mode and absent in cloud. const { installCursorPlugin } = await import("../../helpers/plugin-install"); diff --git a/src/helpers/init-project.ts b/src/helpers/init-project.ts index 2ab370b1..850df571 100644 --- a/src/helpers/init-project.ts +++ b/src/helpers/init-project.ts @@ -264,7 +264,7 @@ async function tryInstallPlugin(editor: EditorTarget): Promise { } if (editor === "cursor") { - // Install directly into ~/.cursor/{skills,agents,rules}/ — Cursor's + // Install directly into ~/.cursor/{skills,agents}/ — Cursor's // plugin subsystem is unreliable in CLI mode and absent in cloud. const { installCursorPlugin } = await import("./plugin-install"); try { diff --git a/src/helpers/paths.ts b/src/helpers/paths.ts index 78bcbfae..261569e4 100644 --- a/src/helpers/paths.ts +++ b/src/helpers/paths.ts @@ -97,7 +97,7 @@ export function opencodeDbPath(): string { /** * Resolve the Cursor user-scope config directory (`~/.cursor/`). * - * Cursor discovers skills, agents, and rules from `~/.cursor/{skills,agents,rules}/`. + * Cursor discovers skills and agents from `~/.cursor/{skills,agents}/`. * These are user-level (global) — they apply to all projects when using * `cursor agent` locally. Cloud VMs do NOT have this directory. * diff --git a/src/helpers/plugin-install.ts b/src/helpers/plugin-install.ts index 4c0928dc..d9856d9a 100644 --- a/src/helpers/plugin-install.ts +++ b/src/helpers/plugin-install.ts @@ -128,11 +128,10 @@ export async function installClaudePlugin(): Promise { /** * Install the archgate Cursor components into user-scope discovery dirs. * - * Cursor discovers skills, agents, and rules from `~/.cursor/{skills,agents,rules}/`. + * Cursor discovers skills and agents from `~/.cursor/{skills,agents}/`. * The tarball from /api/cursor contains these at its root: * - skills/archgate-{name}/SKILL.md — skill definitions * - agents/archgate-{name}.md — agent definitions - * - rules/archgate-governance.mdc — governance rule * - hooks.json — afterFileEdit hook for archgate check * * Extraction uses `tar` via `Bun.spawn` — `tar` is available on macOS, @@ -156,10 +155,9 @@ export async function installCursorPlugin(token: string): Promise { try { // Ensure target dirs exist — tar will write files, but it won't create - // the enclosing `~/.cursor/{skills,agents,rules}/` paths. + // the enclosing `~/.cursor/{skills,agents}/` paths. mkdirSync(join(cursorDir, "skills"), { recursive: true }); mkdirSync(join(cursorDir, "agents"), { recursive: true }); - mkdirSync(join(cursorDir, "rules"), { recursive: true }); logDebug(`Extracting Cursor components into ${cursorDir}`); const result = await run(["tar", "-xzf", tarballPath, "-C", cursorDir]); From 6dec9c6465207d1f31d8b05291e9d3c3003d0832 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Fri, 5 Jun 2026 17:01:10 +0200 Subject: [PATCH 4/7] test: add installCursorPlugin coverage Adds 4 tests for installCursorPlugin matching the installOpencodePlugin pattern: success path, tar failure, 401 auth, and generic HTTP error. Fixes coverage dropping below the 90% threshold. Signed-off-by: Rhuan Barreto --- tests/helpers/plugin-install.test.ts | 45 ++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/tests/helpers/plugin-install.test.ts b/tests/helpers/plugin-install.test.ts index 731b86be..2c791119 100644 --- a/tests/helpers/plugin-install.test.ts +++ b/tests/helpers/plugin-install.test.ts @@ -32,6 +32,7 @@ import { buildVscodeMarketplaceUrl, installClaudePlugin, installCopilotPlugin, + installCursorPlugin, installOpencodePlugin, installVscodeExtension, isClaudeCliAvailable, @@ -447,4 +448,48 @@ describe("plugin-install", () => { ); }); }); + + // ----------------------------------------------------------------------- + // installCursorPlugin + // ----------------------------------------------------------------------- + + describe("installCursorPlugin", () => { + test("downloads tarball and extracts via tar on success", async () => { + const tarContent = new ArrayBuffer(256); + mockFetch(200, tarContent); + spawnSpy.mockImplementation(() => fakeSpawnResult(0)); + + await installCursorPlugin("test-token"); + + // One spawn call for tar extraction + expect(spawnSpy).toHaveBeenCalledTimes(1); + const callArgs = spawnSpy.mock.calls[0][0] as string[]; + expect(callArgs[0]).toBe("tar"); + }); + + test("throws when tar extraction fails", async () => { + mockFetch(200, new ArrayBuffer(64)); + spawnSpy.mockImplementation(() => fakeSpawnResult(2)); + + await expect(installCursorPlugin("test-token")).rejects.toThrow( + "tar -xzf failed" + ); + }); + + test("throws re-login message on 401 download", async () => { + mockFetch(401); + + await expect(installCursorPlugin("expired-token")).rejects.toThrow( + "expired" + ); + }); + + test("throws generic error on non-401 HTTP failure", async () => { + mockFetch(503); + + await expect(installCursorPlugin("test-token")).rejects.toThrow( + "Download failed (HTTP 503)" + ); + }); + }); }); From c33cdbc886484d76939cda08e1bb742004dcd9ca Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Fri, 5 Jun 2026 17:04:04 +0200 Subject: [PATCH 5/7] refactor: extract shared downloadAndExtractTarball helper DRY the tarball download+extract pattern shared by installCursorPlugin and installOpencodePlugin into a single downloadAndExtractTarball() function. Both callers now pass an options object (apiPath, token, targetDir, label, tempFile) and handle only their editor-specific post-extract logic (hooks merge for Cursor, settings config for opencode). Signed-off-by: Rhuan Barreto --- src/helpers/plugin-install.ts | 134 +++++++++++++++++----------------- 1 file changed, 68 insertions(+), 66 deletions(-) diff --git a/src/helpers/plugin-install.ts b/src/helpers/plugin-install.ts index d9856d9a..3c3737ac 100644 --- a/src/helpers/plugin-install.ts +++ b/src/helpers/plugin-install.ts @@ -134,9 +134,6 @@ export async function installClaudePlugin(): Promise { * - agents/archgate-{name}.md — agent definitions * - hooks.json — afterFileEdit hook for archgate check * - * Extraction uses `tar` via `Bun.spawn` — `tar` is available on macOS, - * Linux, and modern Windows (bsdtar ships with Windows 10+). - * * After extraction, `hooks.json` is merged into `~/.cursor/hooks.json` * (rather than extracted as-is) to avoid overwriting existing user hooks. * @@ -144,41 +141,19 @@ export async function installClaudePlugin(): Promise { * retry hint. */ export async function installCursorPlugin(token: string): Promise { - const tarballPath = internalPath("archgate-cursor.tar.gz"); const cursorDir = cursorUserDir(); + mkdirSync(join(cursorDir, "skills"), { recursive: true }); + mkdirSync(join(cursorDir, "agents"), { recursive: true }); + + await downloadAndExtractTarball({ + apiPath: "/api/cursor", + token, + targetDir: cursorDir, + label: "Cursor", + tempFile: "archgate-cursor.tar.gz", + }); - const buffer = await downloadPluginAsset("/api/cursor", token); - logDebug( - `Downloaded Cursor install bundle (${Math.round(buffer.byteLength / 1024)} KB)` - ); - await Bun.write(tarballPath, buffer); - - try { - // Ensure target dirs exist — tar will write files, but it won't create - // the enclosing `~/.cursor/{skills,agents}/` paths. - mkdirSync(join(cursorDir, "skills"), { recursive: true }); - mkdirSync(join(cursorDir, "agents"), { recursive: true }); - - logDebug(`Extracting Cursor components into ${cursorDir}`); - const result = await run(["tar", "-xzf", tarballPath, "-C", cursorDir]); - if (result.exitCode !== 0) { - throw new Error( - `tar -xzf failed (exit ${result.exitCode}) while extracting Cursor components` - ); - } - - // Merge hooks.json into ~/.cursor/hooks.json instead of leaving the - // extracted copy (which would be at ~/.cursor/hooks.json and would - // overwrite existing user hooks). The tarball extracts it, so we - // merge the archgate hooks into any existing hooks file. - await mergeCursorHooks(cursorDir); - } finally { - try { - unlinkSync(tarballPath); - } catch { - // Ignore cleanup errors - } - } + await mergeCursorHooks(cursorDir); } /** @@ -249,6 +224,54 @@ async function downloadPluginAsset( return response.arrayBuffer(); } +/** + * Download and extract a tarball from the plugins API into a target directory. + * + * Shared by `installCursorPlugin` and `installOpencodePlugin` — both follow + * the same pattern: authenticated download → write to temp → tar extract → + * cleanup temp file. + * + * Uses `tar` via `Bun.spawn` (ARCH-007) — `tar` is available on macOS, + * Linux, and modern Windows (bsdtar ships with Windows 10+). + */ +async function downloadAndExtractTarball(opts: { + apiPath: string; + token: string; + targetDir: string; + label: string; + tempFile: string; +}): Promise { + const tarballPath = internalPath(opts.tempFile); + + const buffer = await downloadPluginAsset(opts.apiPath, opts.token); + logDebug( + `Downloaded ${opts.label} bundle (${Math.round(buffer.byteLength / 1024)} KB)` + ); + await Bun.write(tarballPath, buffer); + + try { + logDebug(`Extracting ${opts.label} components into ${opts.targetDir}`); + const result = await run([ + "tar", + "-xzf", + tarballPath, + "-C", + opts.targetDir, + ]); + if (result.exitCode !== 0) { + throw new Error( + `tar -xzf failed (exit ${result.exitCode}) while extracting ${opts.label} components` + ); + } + } finally { + try { + unlinkSync(tarballPath); + } catch { + // Ignore cleanup errors + } + } +} + // --------------------------------------------------------------------------- // opencode — download agent bundle into user-scope agents dir // --------------------------------------------------------------------------- @@ -270,41 +293,20 @@ export async function isOpencodeCliAvailable(): Promise { * tarball contains `archgate-*.md` files at its root which extract directly * into the resolved `opencodeAgentsDir()`. * - * The extraction uses `tar` via `Bun.spawn` (ARCH-007) — `tar` is available - * on macOS, Linux, and modern Windows (bsdtar ships with Windows 10+). - * * Throws on download or extraction failure so callers can surface a manual * retry hint. */ export async function installOpencodePlugin(token: string): Promise { - const tarballPath = internalPath("archgate-opencode.tar.gz"); const agentsDir = opencodeAgentsDir(); - - const buffer = await downloadPluginAsset("/api/opencode", token); - logDebug( - `Downloaded opencode agent bundle (${Math.round(buffer.byteLength / 1024)} KB)` - ); - await Bun.write(tarballPath, buffer); - - try { - // Ensure target dir exists — tar will write files, but it won't create - // the enclosing `/opencode/agents/` path. - mkdirSync(agentsDir, { recursive: true }); - - logDebug(`Extracting opencode agents into ${agentsDir}`); - const result = await run(["tar", "-xzf", tarballPath, "-C", agentsDir]); - if (result.exitCode !== 0) { - throw new Error( - `tar -xzf failed (exit ${result.exitCode}) while extracting opencode agents` - ); - } - } finally { - try { - unlinkSync(tarballPath); - } catch { - // Ignore cleanup errors - } - } + mkdirSync(agentsDir, { recursive: true }); + + await downloadAndExtractTarball({ + apiPath: "/api/opencode", + token, + targetDir: agentsDir, + label: "opencode", + tempFile: "archgate-opencode.tar.gz", + }); // Configure opencode.json with default_agent (idempotent — only sets if absent) const { configureOpencodeSettings } = await import("./opencode-settings"); From 0e94135d2373aac4b301e20bf67b309ff5d92806 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sat, 6 Jun 2026 16:30:36 +0200 Subject: [PATCH 6/7] docs: update Cursor integration for tarball-based distribution MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites the Cursor integration guide and updates plugin/init reference pages to reflect the new distribution model: tarball download to ~/.cursor/{skills,agents}/ instead of Team Marketplace URL + VSIX. Key changes across all locales (en, pt-br, nb): - Distribution: Team Marketplace + VSIX → authenticated tarball - Generated files: .cursor/rules/archgate-governance.mdc → .cursor/hooks.json - Skill names: architect/quality-manager → archgate-reviewer/archgate-lessons-learned - New agents section: archgate-developer + archgate-planner - New cloud agent support section - Updated llms-full.txt with new Cursor content Signed-off-by: Rhuan Barreto --- docs/public/llms-full.txt | 142 +++++++++--------- .../docs/guides/cursor-integration.mdx | 132 ++++++++-------- .../docs/nb/guides/cursor-integration.mdx | 136 +++++++++-------- .../content/docs/nb/reference/cli/init.mdx | 4 +- .../content/docs/nb/reference/cli/plugin.mdx | 2 +- .../docs/pt-br/guides/cursor-integration.mdx | 141 +++++++++-------- .../content/docs/pt-br/reference/cli/init.mdx | 4 +- .../docs/pt-br/reference/cli/plugin.mdx | 4 +- docs/src/content/docs/reference/cli/init.mdx | 4 +- .../src/content/docs/reference/cli/plugin.mdx | 2 +- 10 files changed, 295 insertions(+), 276 deletions(-) diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 2447fbff..7ccffb38 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -29,7 +29,7 @@ Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercont - [Guide — Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a governance workflow that reads ADRs, validates code, and captures patterns. - [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code. - [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI. -- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills. +- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor with Archgate agents, skills, and hooks. - [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit. - [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more. - [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting. @@ -100,7 +100,7 @@ The Archgate CLI works standalone, but **editor plugins** unlock a full AI gover read-validate-capture loop on every task. - The Cursor plugin provides pre-built agent rules and skills that give + The Cursor plugin provides agents, skills, and hooks that give Cursor's AI agent the same governance workflow as Claude Code. @@ -1549,16 +1549,11 @@ Run `archgate init` with the `--editor cursor` flag to configure Cursor integrat archgate init --editor cursor ``` -### With plugin (beta) - 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: +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 governance workflow. -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. +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: @@ -1567,51 +1562,66 @@ 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: ```bash archgate plugin install --editor cursor ``` -### Without plugin (free) +### Generated files -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. +**User scope** (`~/.cursor/`): -### Generated files +| 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 governance workflow | +| `~/.cursor/agents/archgate-planner.md` | Planning agent for scoping and breaking down work | + +**Project scope**: -| File | Purpose | -| --------------------------------------- | -------------------------------------------------------------- | -| `.cursor/rules/archgate-governance.mdc` | Always-on Cursor rule that instructs the agent to consult ADRs | +| File | Purpose | +| --------------------- | --------------------------------------------------------------------- | +| `.cursor/hooks.json` | `afterFileEdit` hook that runs `archgate check` after every file edit | ## 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. +The plugin adds agents and skills to Cursor, installed at the user scope so they are available across all your projects. -### Agent +### Agents -| Name | Purpose | -| ----------- | --------------------------------------------------------------------------- | -| `developer` | General development agent that reads ADRs before coding and validates after | +| 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 | -The `developer` agent orchestrates the skills below automatically as part of its workflow. +Users invoke agents explicitly via `/archgate-developer` or `/archgate-planner` in the Cursor chat. ### 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 | +| 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. -These are the same agent and skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's plugin system. +### Hooks + +| Hook | Trigger | Action | +| --------------- | --------------- | ---------------------------------------------------------- | +| `afterFileEdit` | Every file edit | Runs `archgate check` to catch ADR violations in real time | ## Initial setup with onboard -After installing the plugin, run the `onboard` skill in your project once. This skill: +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 @@ -1622,31 +1632,17 @@ The onboard skill is designed to run once per project. After onboarding, the oth ## How it works in practice -### With the plugin - -The `developer` agent follows a structured workflow for every coding task: +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 --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. +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. -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. +4. **Review changes** -- The agent invokes the `archgate-reviewer` skill to validate structural ADR compliance beyond what automated rules catch. -### 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 ` (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. +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 @@ -1662,19 +1658,20 @@ This behavior is consistent regardless of how the developer phrases the request. ## 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` | +| 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 `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. +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. -## Governance rule +## Cloud agent support -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. +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. ## Session transcript access @@ -1687,12 +1684,13 @@ The command accepts two optional flags: ## 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. +- **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. --- @@ -2689,7 +2687,7 @@ The `--id` and `--body` flags are required. All other frontmatter fields (`--tit 7. **Use domain prefixes to organize.** The domain field determines the ID prefix and helps filter ADRs by area. Prefer the five built-ins (`backend`, `frontend`, `data`, `architecture`, `general`); register a [custom domain](/concepts/domains/#custom-domains) only when none of them is a genuine fit. -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include an ADR Author skill that creates and updates ADRs following your project's conventions. The Quality Manager skill also proposes new ADRs when it detects recurring patterns. [Sign up for beta access](https://plugins.archgate.dev). +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include an ADR authoring skill that creates and updates ADRs following your project's conventions. The lessons-learned skill also proposes new ADRs when it detects recurring patterns. [Sign up for beta access](https://plugins.archgate.dev). --- @@ -3951,7 +3949,7 @@ archgate doctor [options] - **Archgate** -- CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status - **Project** -- Whether an `.archgate/` project exists, ADR count, domains - **Editor CLIs** -- Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH -- **Project Integrations** -- Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) +- **Project Integrations** -- Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/hooks.json`, `.vscode/settings.json`, `.github/copilot/instructions.md`) ## Example @@ -3986,7 +3984,7 @@ Editor CLIs Project Integrations Claude: OK (.claude/settings.local.json) - Cursor: MISSING (.cursor/rules/archgate-governance.mdc) + Cursor: MISSING (.cursor/hooks.json) VS Code: OK (.vscode/settings.json) Copilot: MISSING (.github/copilot/instructions.md) ``` @@ -4053,7 +4051,7 @@ When `--install-plugin` is passed, the CLI installs the Archgate plugin for the **Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead. -**Cursor:** If the `cursor` CLI is on your PATH, the VS Code extension is installed automatically via `cursor --install-extension`. The team marketplace URL is printed for manual plugin discovery. +**Cursor:** Downloads an authenticated tarball of skills, agents, and hooks into `~/.cursor/`. Also writes `.cursor/hooks.json` to the project for cloud agent compatibility. No CLI detection needed. **opencode:** Requires the `opencode` CLI to be on your PATH — if it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows — opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details. @@ -4068,7 +4066,7 @@ Initialized Archgate governance in /path/to/project Archgate plugin installed for Claude Code. ``` -When `--editor cursor` is used, the output shows `.cursor/` instead of `.claude/`. +When `--editor cursor` is used, the output shows `.cursor/` for project-level files and notes that user-scope components were installed to `~/.cursor/`. ## Base branch detection @@ -4270,7 +4268,7 @@ Installation behavior varies by editor: - **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. - **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. -- **Cursor:** Prints the [Team Private Plugin Marketplace](https://cursor.com/docs/plugins#team-marketplaces) URL with instructions to add it in Cursor Settings. Cursor does not support VSIX installation from the CLI. +- **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed — files are written directly to the Cursor user directory. - **VS Code:** Installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. - **opencode:** Requires the `opencode` CLI to be on PATH — skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" — opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details. @@ -5405,7 +5403,7 @@ Browse complete, copy-pasteable rule examples organized by category. Each rule p | [openapi-routes](/examples/openapi-routes/) | Ensure backend routes use OpenAPI-typed definitions | | [clean-architecture-layers](/examples/clean-architecture-layers/) | Enforce dependency direction in layered architectures | -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include a Quality Manager skill that identifies recurring patterns in your codebase and proposes new rules to enforce them. [Sign up for beta access](https://plugins.archgate.dev). +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include a lessons-learned skill that identifies recurring patterns in your codebase and proposes new rules to enforce them. [Sign up for beta access](https://plugins.archgate.dev). --- diff --git a/docs/src/content/docs/guides/cursor-integration.mdx b/docs/src/content/docs/guides/cursor-integration.mdx index e44ccf6f..02dc4489 100644 --- a/docs/src/content/docs/guides/cursor-integration.mdx +++ b/docs/src/content/docs/guides/cursor-integration.mdx @@ -1,6 +1,6 @@ --- title: Cursor Integration -description: Integrate Archgate with Cursor IDE for AI-assisted development with architecture governance. Configure agent rules and skills for ADR compliance. +description: Integrate Archgate with Cursor for AI-assisted development with architecture governance. Configure agents, skills, and hooks for ADR compliance. --- Archgate integrates with [Cursor](https://cursor.com) 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](/guides/claude-code-plugin/). @@ -13,18 +13,13 @@ Run `archgate init` with the `--editor cursor` flag to configure Cursor integrat archgate init --editor cursor ``` -### With plugin (beta) - :::note[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: +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 governance workflow. -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. +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: @@ -33,51 +28,70 @@ 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: ```bash archgate plugin install --editor cursor ``` -### Without plugin (free) +### Generated files -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. +**User scope** (`~/.cursor/`): -### Generated files +| 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 governance workflow | +| `~/.cursor/agents/archgate-planner.md` | Planning agent for scoping and breaking down work | -| File | Purpose | -| --------------------------------------- | -------------------------------------------------------------- | -| `.cursor/rules/archgate-governance.mdc` | Always-on Cursor rule that instructs the agent to consult ADRs | +**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 an agent and role-based skills to Cursor. Cursor's plugin system handles namespacing, so skills use their direct names without a prefix. +The plugin adds agents and skills to Cursor, installed at the user scope so they are available across all your projects. -### Agent +### Agents -| Name | Purpose | -| ----------- | --------------------------------------------------------------------------- | -| `developer` | General development agent that reads ADRs before coding and validates after | +| 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 | -The `developer` agent orchestrates the skills below automatically as part of its workflow. +Users invoke agents explicitly via `/archgate-developer` or `/archgate-planner` in the Cursor chat. ### 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 | +| 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 -These are the same agent and skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's plugin system. +| 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, run the `onboard` skill in your project once. This skill: +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 @@ -88,31 +102,17 @@ The onboard skill is designed to run once per project. After onboarding, the oth ## How it works in practice -### With the plugin - -The `developer` agent follows a structured workflow for every coding task: +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 --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 +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. -The agent uses the governance rule and CLI commands to follow four manual steps: +4. **Review changes** -- The agent invokes the `archgate-reviewer` skill to validate structural ADR compliance beyond what automated rules catch. -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 ` (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. +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 @@ -128,19 +128,22 @@ This behavior is consistent regardless of how the developer phrases the request. ## 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` | +| 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. -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. +## Cloud agent support -## Governance rule +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. -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. +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 @@ -153,9 +156,10 @@ The command accepts two optional flags: ## 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. +- **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. diff --git a/docs/src/content/docs/nb/guides/cursor-integration.mdx b/docs/src/content/docs/nb/guides/cursor-integration.mdx index 47bc3825..775415ad 100644 --- a/docs/src/content/docs/nb/guides/cursor-integration.mdx +++ b/docs/src/content/docs/nb/guides/cursor-integration.mdx @@ -1,6 +1,6 @@ --- title: Cursor-integrasjon -description: Integrer Archgate med Cursor IDE for AI-assistert utvikling med arkitekturstyring. Konfigurer agentregler og ferdigheter for ADR-samsvar. +description: Integrer Archgate med Cursor for AI-assistert utvikling med arkitekturstyring. Konfigurer agenter, skills og hooks for ADR-samsvar. --- Archgate integreres med [Cursor](https://cursor.com) for å gi AI-agenter en strukturert styringsarbeidsflyt. Agenten leser ADR-ene dine før den skriver kode, validerer etterpå, og fanger opp nye mønstre for teamet -- den samme arbeidsflyten som er tilgjengelig i [Claude Code-pluginet](/guides/claude-code-plugin/). @@ -13,18 +13,13 @@ Kjør `archgate init` med `--editor cursor`-flagget for å konfigurere Cursor-in archgate init --editor cursor ``` -### Med plugin (beta) - :::note[Betatilgang kreves] Cursor-pluginet er for øyeblikket i beta. Kjør `archgate login` for å registrere deg og autentisere. ::: -Hvis du har logget inn via `archgate login`, installerer init-kommandoen også Archgate-pluginet for Cursor. Pluginet tilbyr ferdigbygde agentregler og ferdigheter som gir Cursor sin AI-agent en komplett styringsarbeidsflyt. - -Pluginet distribueres på to måter: +Hvis du har logget inn via `archgate login`, installerer init-kommandoen også Archgate-pluginet for Cursor. Pluginet tilbyr ferdigbygde agenter, skills og hooks som gir Cursors AI-agent en komplett styringsarbeidsflyt. -1. **Cursor Team Marketplace** -- Pluginet publiseres til et git-basert team-markedsplass-repositorium. Etter installasjon oppdager Cursor det fra team-markedsplassens URL som skrives ut av CLI-en. -2. **VS Code Extension (VSIX)** -- En `.vsix`-utvidelse installeres i Cursor via `cursor --install-extension`-kommandoen. +Pluginet distribueres som en autentisert tarball. CLI-en laster det ned og pakker ut skills, agenter og hooks i `~/.cursor/`. Ingen CLI-deteksjon er nødvendig -- filene skrives direkte til Cursor-brukerkatalogen. For å eksplisitt installere pluginet: @@ -33,51 +28,70 @@ archgate login # engangsoppsett archgate init --editor cursor --install-plugin ``` -Kommandoen `archgate plugin install --editor cursor` installerer VS Code-utvidelsen via `cursor`-CLI-en hvis tilgjengelig og skriver ut team-markedsplassens URL; ellers skrives manuelle instruksjoner ut. - For å installere eller reinstallere pluginet på et allerede initialisert prosjekt: ```bash archgate plugin install --editor cursor ``` -### Uten plugin (gratis) +### Genererte filer -Uten pluginet konfigurerer `archgate init --editor cursor` fortsatt en grunnleggende styringsregel. AI-agenten kan konsultere ADR-er og kjøre sjekker via CLI-kommandoer, men får ikke de rollebaserte ferdighetene beskrevet nedenfor. +**Brukerscope** (`~/.cursor/`): -### Genererte filer +| Fil | Formål | +| ---------------------------------------------- | ----------------------------------------------------------------------- | +| `~/.cursor/skills/archgate-reviewer.md` | Validerer kodeendringer mot alle prosjektets ADR-er | +| `~/.cursor/skills/archgate-lessons-learned.md` | Fanger opp læringer og foreslår nye ADR-er når mønstre dukker opp | +| `~/.cursor/skills/archgate-adr-author.md` | Oppretter og redigerer ADR-er i henhold til prosjektets konvensjoner | +| `~/.cursor/skills/archgate-onboard.md` | Engangsoppsett: utforsker kodebasen, intervjuer deg og oppretter ADR-er | +| `~/.cursor/skills/archgate-cli-reference.md` | Intern referanse for AI-agenter med Archgate CLI-guiden | +| `~/.cursor/agents/archgate-developer.md` | Primær utviklingsagent med den komplette ADR-styringsarbeidsflyten | +| `~/.cursor/agents/archgate-planner.md` | Planleggingsagent for scoping og oppdeling av arbeid | -| Fil | Formål | -| --------------------------------------- | -------------------------------------------------------------------- | -| `.cursor/rules/archgate-governance.mdc` | Alltid-på Cursor-regel som instruerer agenten om å konsultere ADR-er | +**Prosjektscope**: + +| Fil | Formål | +| -------------------- | ------------------------------------------------------------------------- | +| `.cursor/hooks.json` | `afterFileEdit`-hook som kjører `archgate check` etter hver filredigering | + +Filen `.cursor/hooks.json` er den eneste filen som skrives til prosjekttreet ditt. Den sørger for at `archgate check` kjøres automatisk etter hver filredigering, og fanger opp ADR-brudd i sanntid. ## Hva pluginet tilbyr -Pluginet legger til en agent og rollebaserte ferdigheter i Cursor. Cursors plugin-system håndterer navnerom, så ferdigheter bruker sine direkte navn uten prefiks. +Pluginet legger til agenter og skills i Cursor, installert i brukerscope slik at de er tilgjengelige på tvers av alle prosjektene dine. + +### Agenter + +| Navn | Formål | +| -------------------- | ---------------------------------------------------------------------------- | +| `archgate-developer` | Generell utviklingsagent som leser ADR-er før koding og validerer etterpå | +| `archgate-planner` | Planleggingsagent for scoping av arbeid og oppdeling i ADR-samsvarende trinn | -### Agent +Brukere aktiverer agenter eksplisitt via `/archgate-developer` eller `/archgate-planner` i Cursor-chatten. -| Navn | Formål | -| ----------- | ------------------------------------------------------------------------- | -| `developer` | Generell utviklingsagent som leser ADR-er før koding og validerer etterpå | +### Skills -`developer`-agenten orkestrerer ferdighetene nedenfor automatisk som en del av arbeidsflyten. +| Navn | Formål | +| -------------------------- | ---------------------------------------------------------------------------------- | +| `archgate-reviewer` | Validerer kodeendringer mot alle prosjektets ADR-er for strukturelt samsvar | +| `archgate-lessons-learned` | Gjennomgår regeldekning og foreslår nye ADR-er når mønstre dukker opp | +| `archgate-adr-author` | Oppretter og redigerer ADR-er i henhold til prosjektets konvensjoner | +| `archgate-onboard` | Engangsoppsett: utforsker kodebasen, intervjuer deg og oppretter innledende ADR-er | +| `archgate-cli-reference` | Intern referanse for AI-agenter med den komplette Archgate CLI-kommandoguiden | -### Ferdigheter +Disse er de samme rollene som er tilgjengelige i Claude Code-pluginet (`archgate:reviewer`, `archgate:lessons-learned`, osv.), tilpasset Cursors skill- og agentsystem. -| Navn | Formål | -| ----------------- | --------------------------------------------------------------------------------------- | -| `architect` | Validerer kodeendringer mot alle prosjektets ADR-er for strukturell samsvar | -| `quality-manager` | Gjennomgår regeldekning og foreslår nye ADR-er når mønstre dukker opp | -| `adr-author` | Oppretter og redigerer ADR-er i henhold til prosjektets konvensjoner | -| `onboard` | Engangsoppsett: utforsker kodebasen, intervjuer utvikleren, oppretter innledende ADR-er | -| `cli-reference` | Intern referanse for AI-agenter med den komplette Archgate CLI-kommandoguiden | +### Hooks -Disse er den samme agenten og ferdighetene som er tilgjengelige i Claude Code-pluginet (`archgate:developer`, `archgate:architect`, osv.), tilpasset Cursors plugin-system. +| Hook | Utløser | Handling | +| --------------- | ------------------ | ----------------------------------------------------------- | +| `afterFileEdit` | Hver filredigering | Kjører `archgate check` for å fange opp ADR-brudd i sanntid | + +Hooken er definert i `.cursor/hooks.json` på prosjektnivå, slik at den fungerer både lokalt og i skybaserte agentmiljøer. ## Første oppsett med onboard -Etter å ha installert pluginet, kjør `onboard`-ferdigheten i prosjektet ditt en gang. Denne ferdigheten: +Etter å ha installert pluginet, aktiver `/archgate-developer` og be den kjøre onboard-ferdigheten i prosjektet ditt. Denne ferdigheten: 1. Utforsker kodebasestrukturen din (mapper, nøkkelfiler, pakkekonfigurasjon) 2. Intervjuer deg om teamets konvensjoner, begrensninger og arkitekturbeslutninger @@ -88,31 +102,17 @@ Onboard-ferdigheten er designet for å kjøres en gang per prosjekt. Etter onboa ## Hvordan det fungerer i praksis -### Med pluginet - -`developer`-agenten følger en strukturert arbeidsflyt for hver kodeoppgave: +Aktiver `/archgate-developer` i Cursors chat når du starter en kodeoppgave. Agenten følger en strukturert arbeidsflyt for hver endring: 1. **Les gjeldende ADR-er** -- Agenten kjører `archgate review-context` for å se hvilke ADR-er som gjelder for filene som endres. Den skriver ikke kode før den har lest de gjeldende ADR-ene. 2. **Skriv kode i henhold til ADR-begrensninger** -- Agenten implementerer endringer i henhold til Do's and Don'ts fra de gjeldende ADR-ene. -3. **Kjør samsvarssjekker** -- Agenten kjører `archgate check --staged` for å utføre automatiserte regler. Eventuelle brudd utbedres før man går videre. - -4. **Arkitektgjennomgang** -- Agenten aktiverer `architect`-ferdigheten for å validere strukturelt ADR-samsvar utover det automatiserte regler fanger opp. - -5. **Fang opp læringer** -- Agenten aktiverer `quality-manager`-ferdigheten for å gjennomgå arbeidet og identifisere mønstre som er verdt å fange opp som nye ADR-er eller oppdateringer til eksisterende. - -### Uten pluginet +3. **Kjør samsvarssjekker** -- Agenten kjører `archgate check` for å utføre automatiserte regler. `afterFileEdit`-hooken fanger også opp brudd i sanntid. Eventuelle brudd utbedres før man går videre. -Agenten bruker styringsregelen og CLI-kommandoer for å følge fire manuelle trinn: +4. **Gjennomgå endringer** -- Agenten aktiverer `archgate-reviewer`-ferdigheten for å validere strukturelt ADR-samsvar utover det automatiserte regler fanger opp. -1. **Gjennomgå kontekst** -- Kjør `archgate review-context` for å se hvilke ADR-er som gjelder for filene som endres. - -2. **Les individuelle ADR-er** -- For full kontekst om en spesifikk beslutning, kjør `archgate adr show ` (for eksempel `archgate adr show ARCH-001`). - -3. **Skriv kode** -- Implementer endringer i henhold til begrensningene fra de gjeldende ADR-ene. - -4. **Kjør samsvarssjekker** -- Kjør `archgate check --staged` for å validere at koden samsvarer med alle ADR-regler. +5. **Fang opp læringer** -- Agenten aktiverer `archgate-lessons-learned`-ferdigheten for å gjennomgå arbeidet og identifisere mønstre som er verdt å fange opp som nye ADR-er eller oppdateringer til eksisterende. ## ADR-drevet avvisning @@ -128,19 +128,22 @@ Denne oppførselen er konsistent uavhengig av hvordan utvikleren formulerer fore ## Når du skal bruke hver agent eller ferdighet -| Scenario | Ferdighet | -| ------------------------------------------------- | ----------------- | -| Starte et nytt prosjekt med Archgate | `onboard` | -| Daglige kodeoppgaver | `developer` | -| Gjennomgå en PR for ADR-samsvar | `architect` | -| Oppdage et gjentagende mønster verdt å kodifisere | `quality-manager` | -| Opprette eller redigere en ADR | `adr-author` | +| Scenario | Agent / Ferdighet | +| ------------------------------------------------- | ------------------------------------------------- | +| Starte et nytt prosjekt med Archgate | `/archgate-developer` (be den om å gjøre onboard) | +| Daglige kodeoppgaver | `/archgate-developer` | +| Planlegging og scoping av arbeid | `/archgate-planner` | +| Gjennomgå en endring for ADR-samsvar | `archgate-reviewer` | +| Oppdage et gjentagende mønster verdt å kodifisere | `archgate-lessons-learned` | +| Opprette eller redigere en ADR | `archgate-adr-author` | + +`archgate-developer`-agenten orkestrerer ferdighetene automatisk -- den aktiverer `archgate-reviewer` og `archgate-lessons-learned` som en del av arbeidsflyten. Mesteparten av tiden trenger du bare å aktivere `/archgate-developer` og la den kjøre. -`developer`-agenten orkestrerer ferdighetene automatisk -- den aktiverer `architect` og `quality-manager` som en del av arbeidsflyten. Mesteparten av tiden trenger du bare å bruke `developer` direkte. +## Støtte for skyagenter -## Styringsregel +Cursor støtter skyagenter som kjører på fjernstyrte VM-er. Disse miljøene har ikke tilgang til `~/.cursor/`, så skills og agenter i brukerscope er ikke tilgjengelige. Imidlertid er filen `.cursor/hooks.json` en del av prosjekttreet ditt og fungerer i sky-VM-er. Dette betyr at `archgate check` fortsatt kjøres automatisk etter hver filredigering, selv i skyagentøkter. -Styringsregelen i `.cursor/rules/archgate-governance.mdc` bruker `alwaysApply: true`, noe som betyr at Cursor-agenten alltid har styringstilgang tilgjengelig uten manuell aktivering. Den instruerer agenten om å kjøre `archgate review-context` før koding og `archgate check --staged` etterpå. +For full styring i skymiljøer, sørg for at `archgate` er tilgjengelig på VM-ens PATH (f.eks. via installasjonsscriptet i prosjektets oppsett). ## Tilgang til sesjonsutskrifter @@ -153,9 +156,10 @@ Kommandoen aksepterer to valgfrie flagg: ## Tips for effektiv bruk -- **Bruk `developer`-ferdigheten for kodeoppgaver.** Den orkestrerer hele les-valider-fang-opp-arbeidsflyten automatisk. -- **Kjør `onboard` en gang per prosjekt.** Den setter opp de innledende ADR-ene basert på den faktiske kodebasen og konvensjonene dine. -- **Bruk `architect` for PR-gjennomganger.** Den validerer strukturelt samsvar utover det automatiserte regler fanger opp. -- **Bruk `quality-manager` etter å ha løst vanskelige problemer.** Den fanger opp læringer slik at de samme feilene ikke gjentas. -- **Commit `.cursor/`-mappen.** Dette sikrer at alle teammedlemmer får den samme styringskonfigurasjonen når de kloner repositoriet. -- **Hold ADR-regelfiler oppdatert.** Agenten håndterer det reglene sjekker for -- hvis en regel mangler, vil bruddet ikke bli fanget opp. +- **Aktiver `/archgate-developer` for kodeoppgaver.** Den orkestrerer hele les-valider-fang-opp-arbeidsflyten automatisk. +- **Kjør onboard en gang per prosjekt.** Den setter opp de innledende ADR-ene basert på den faktiske kodebasen og konvensjonene dine. +- **Bruk `archgate-reviewer` for gjennomganger.** Den validerer strukturelt samsvar utover det automatiserte regler fanger opp. +- **Bruk `archgate-lessons-learned` etter å ha løst vanskelige problemer.** Den fanger opp læringer slik at de samme feilene ikke gjentas. +- **Commit `.cursor/`-mappen.** Filen `hooks.json` sørger for at hvert teammedlem får `archgate check` på filredigeringer når de kloner repositoriet. +- **Hold ADR-regelfiler oppdatert.** Agenten håndhever det reglene sjekker for -- hvis en regel mangler, vil bruddet ikke bli fanget opp. +- **Kjør `archgate plugin install --editor cursor` for å oppgradere.** Tjenesten returnerer den nyeste plugin-pakken ved hver autentisert nedlasting. diff --git a/docs/src/content/docs/nb/reference/cli/init.mdx b/docs/src/content/docs/nb/reference/cli/init.mdx index 693dc991..cc18248d 100644 --- a/docs/src/content/docs/nb/reference/cli/init.mdx +++ b/docs/src/content/docs/nb/reference/cli/init.mdx @@ -24,7 +24,7 @@ Når `--install-plugin` sendes med, installerer CLI-en Archgate-pluginen for den **Claude Code:** Hvis `claude`-CLI-en er på din PATH, installeres pluginen automatisk via `claude plugin marketplace add` og `claude plugin install`. Hvis `claude`-CLI-en ikke finnes, skriver kommandoen ut de manuelle installasjonskommandoene i stedet. -**Cursor:** Hvis `cursor`-CLI-en er på din PATH, installeres VS Code-utvidelsen automatisk via `cursor --install-extension`. Team-markedsplassen-URL-en skrives ut for manuell plugin-oppdagelse. +**Cursor:** Laster ned en autentisert tarball med skills, agenter og hooks i `~/.cursor/`. Skriver også `.cursor/hooks.json` til prosjektet for kompatibilitet med skyagenter. Ingen CLI-deteksjon nødvendig. **opencode:** Krever at `opencode`-CLI-en er på din PATH -- hvis den ikke er det, hoppes installasjonen over og en melding ber deg installere opencode først. Når den er til stede, laster CLI-en ned en autentisert tarball med agentfiler fra Archgate plugins-tjenesten og pakker den ut i opencode-agentkatalogen for brukerskoopet (`$XDG_CONFIG_HOME/opencode/agents/`, faller tilbake til `$HOME/.config/opencode/agents/` på alle plattformer inkludert Windows -- opencode bruker XDG-stier via `xdg-basedir` og leser ikke `%APPDATA%`). Ingen filer skrives til prosjekttreet. Se [opencode-integrasjonsguiden](/guides/opencode-integration/) for detaljer. @@ -39,7 +39,7 @@ Initialized Archgate governance in /path/to/project Archgate plugin installed for Claude Code. ``` -Når `--editor cursor` brukes, viser utdataene `.cursor/` i stedet for `.claude/`. +Når `--editor cursor` brukes, viser utdataene `.cursor/` for filer på prosjektnivå og noterer at brukerscope-komponenter ble installert til `~/.cursor/`. ## Deteksjon av hovedgren diff --git a/docs/src/content/docs/nb/reference/cli/plugin.mdx b/docs/src/content/docs/nb/reference/cli/plugin.mdx index 4d49732f..104994bf 100644 --- a/docs/src/content/docs/nb/reference/cli/plugin.mdx +++ b/docs/src/content/docs/nb/reference/cli/plugin.mdx @@ -54,7 +54,7 @@ Installasjonsoppførselen varierer etter editor: - **Claude Code:** Autoinstallerer via `claude`-CLI-en hvis tilgjengelig; skriver ut manuelle kommandoer ellers. - **Copilot CLI:** Autoinstallerer via `copilot`-CLI-en hvis tilgjengelig; skriver ut manuelle kommandoer ellers. -- **Cursor:** Skriver ut [Team Private Plugin Marketplace](https://cursor.com/docs/plugins#team-marketplaces)-URL-en med instruksjoner for å legge den til i Cursor-innstillingene. Cursor støtter ikke VSIX-installasjon fra CLI-en. +- **Cursor:** Laster ned en autentisert tarball og pakker ut skills, agenter og hooks i `~/.cursor/`. Ingen CLI-deteksjon nødvendig -- filene skrives direkte til Cursor-brukerkatalogen. - **VS Code:** Installerer VS Code-utvidelsen (`.vsix`) via `code`-CLI-en hvis tilgjengelig; skriver ut manuelle instruksjoner ellers. - **opencode:** Krever at `opencode`-CLI-en er på PATH -- hopper over installasjonen med en tydelig melding ellers. Når den er til stede, laster den ned en autentisert tarball med agentfiler og pakker den ut i opencode-agentkatalogen for brukerskoopet. `archgate plugin url --editor opencode` skriver ut "N/A" -- opencode har ingen markedsplassURL. Se [opencode-integrasjonsguiden](/guides/opencode-integration/) for detaljer. diff --git a/docs/src/content/docs/pt-br/guides/cursor-integration.mdx b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx index a617d1dc..d2903430 100644 --- a/docs/src/content/docs/pt-br/guides/cursor-integration.mdx +++ b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx @@ -1,6 +1,6 @@ --- title: Integração com Cursor -description: Integre o Archgate com o Cursor IDE para desenvolvimento assistido por IA com governança arquitetural. Configure regras e skills de agente para conformidade ADR. +description: Integre o Archgate com o Cursor para desenvolvimento assistido por IA com governança arquitetural. Configure agentes, skills e hooks para conformidade com ADRs. --- O Archgate se integra com o [Cursor](https://cursor.com) para oferecer aos agentes de IA um fluxo de governança estruturado. O agente lê seus ADRs antes de escrever código, valida depois e captura novos padrões para a equipe -- o mesmo fluxo disponível no [plugin para Claude Code](/guides/claude-code-plugin/). @@ -13,18 +13,13 @@ Execute `archgate init` com a flag `--editor cursor` para configurar a integraç archgate init --editor cursor ``` -### Com plugin (beta) - :::note[Acesso beta necessário] O plugin para Cursor está atualmente em beta. Execute `archgate login` para se cadastrar e autenticar. ::: -Se você fez login via `archgate login`, o comando init também instala o plugin Archgate para o Cursor. O plugin fornece regras de agente pré-configuradas e skills que dão ao agente de IA do Cursor um fluxo de governança completo. - -O plugin é distribuído de duas formas: +Se você fez login via `archgate login`, o comando init também instala o plugin Archgate para o Cursor. O plugin fornece agentes, skills e hooks pré-configurados que dão ao agente de IA do Cursor um fluxo de governança completo. -1. **Cursor Team Marketplace** -- O plugin é publicado em um repositório team marketplace baseado em git. Após a instalação, o Cursor o descobre a partir da URL do team marketplace impressa pela CLI. -2. **Extensão VS Code (VSIX)** -- Uma extensão `.vsix` é instalada no Cursor via o comando `cursor --install-extension`. +O plugin é distribuído como um tarball autenticado. A CLI faz o download e extrai skills, agentes e hooks em `~/.cursor/`. Nenhuma detecção de CLI é necessária -- os arquivos são gravados diretamente no diretório de usuário do Cursor. Para instalar o plugin explicitamente: @@ -33,51 +28,70 @@ archgate login # configuração única archgate init --editor cursor --install-plugin ``` -O comando `archgate plugin install --editor cursor` instala a extensão VS Code via CLI `cursor` se disponível e exibe a URL do team marketplace; exibe instruções manuais caso contrário. - Para instalar ou reinstalar o plugin em um projeto já inicializado: ```bash archgate plugin install --editor cursor ``` -### Sem plugin (gratuito) +### Arquivos gerados -Sem o plugin, `archgate init --editor cursor` ainda configura uma regra de governança básica. O agente de IA pode consultar ADRs e executar verificações via comandos CLI, mas não recebe as skills baseadas em papéis descritas abaixo. +**Escopo de usuário** (`~/.cursor/`): -### Arquivos gerados +| Arquivo | Propósito | +| ---------------------------------------------- | ---------------------------------------------------------------------- | +| `~/.cursor/skills/archgate-reviewer.md` | Valida alterações de código contra todos os ADRs do projeto | +| `~/.cursor/skills/archgate-lessons-learned.md` | Captura aprendizados e propõe novos ADRs quando padrões emergem | +| `~/.cursor/skills/archgate-adr-author.md` | Cria e edita ADRs seguindo as convenções do projeto | +| `~/.cursor/skills/archgate-onboard.md` | Configuração única: explora o codebase, entrevista você e cria ADRs | +| `~/.cursor/skills/archgate-cli-reference.md` | Referência interna para agentes de IA com o guia CLI do Archgate | +| `~/.cursor/agents/archgate-developer.md` | Agente principal de desenvolvimento com o fluxo completo de governança | +| `~/.cursor/agents/archgate-planner.md` | Agente de planejamento para escopo e divisão de trabalho | + +**Escopo do projeto**: -| Arquivo | Propósito | -| --------------------------------------- | --------------------------------------------------------------------- | -| `.cursor/rules/archgate-governance.mdc` | Regra sempre ativa do Cursor que instrui o agente a consultar os ADRs | +| Arquivo | Propósito | +| -------------------- | ----------------------------------------------------------------------------- | +| `.cursor/hooks.json` | Hook `afterFileEdit` que executa `archgate check` após cada edição de arquivo | + +O arquivo `.cursor/hooks.json` é o único arquivo gravado na árvore do seu projeto. Ele garante que `archgate check` seja executado automaticamente após cada edição de arquivo, detectando violações de ADR em tempo real. ## O que o plugin oferece -O plugin adiciona um agente e skills baseadas em papéis ao Cursor. O sistema de plugins do Cursor gerencia o namespacing, então as skills usam seus nomes diretos sem prefixo. +O plugin adiciona agentes e skills ao Cursor, instalados no escopo de usuário para que estejam disponíveis em todos os seus projetos. -### Agente +### Agentes -| Nome | Propósito | -| ----------- | ------------------------------------------------------------------------------ | -| `developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | +| Nome | Propósito | +| -------------------- | --------------------------------------------------------------------------------- | +| `archgate-developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | +| `archgate-planner` | Agente de planejamento para escopo de trabalho e divisão de tarefas conforme ADRs | -O agente `developer` orquestra as skills abaixo automaticamente como parte do seu fluxo. +Os usuários invocam agentes explicitamente via `/archgate-developer` ou `/archgate-planner` no chat do Cursor. ### Skills -| Nome | Propósito | -| ----------------- | ------------------------------------------------------------------------------------------ | -| `architect` | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | -| `quality-manager` | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem | -| `adr-author` | Cria e edita ADRs seguindo as convenções do projeto | -| `onboard` | Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | -| `cli-reference` | Referência interna para agentes de IA com o guia completo de comandos CLI do Archgate | +| Nome | Propósito | +| -------------------------- | ---------------------------------------------------------------------------------------- | +| `archgate-reviewer` | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | +| `archgate-lessons-learned` | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem | +| `archgate-adr-author` | Cria e edita ADRs seguindo as convenções do projeto | +| `archgate-onboard` | Configuração única: explora o codebase, entrevista você e cria os ADRs iniciais | +| `archgate-cli-reference` | Referência interna para agentes de IA com o guia completo de comandos CLI do Archgate | + +Esses são os mesmos papéis disponíveis no plugin para Claude Code (`archgate:reviewer`, `archgate:lessons-learned`, etc.), adaptados para o sistema de skills e agentes do Cursor. + +### Hooks -Esses são o mesmo agente e skills disponíveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptados para o sistema de plugins do Cursor. +| Hook | Gatilho | Ação | +| --------------- | ---------------------- | --------------------------------------------------------------------- | +| `afterFileEdit` | Cada edição de arquivo | Executa `archgate check` para detectar violações de ADR em tempo real | + +O hook é definido em `.cursor/hooks.json` no nível do projeto, então funciona tanto localmente quanto em ambientes de agentes na nuvem. ## Configuração inicial com onboard -Após instalar o plugin, execute a skill `onboard` no seu projeto uma vez. Essa skill: +Após instalar o plugin, invoque `/archgate-developer` e peça para ele executar a skill de onboard no seu projeto. Essa skill: 1. Explora a estrutura do seu codebase (diretórios, arquivos-chave, configuração de pacotes) 2. Entrevista você sobre as convenções, restrições e decisões arquiteturais da sua equipe @@ -88,31 +102,17 @@ A skill de onboard foi projetada para ser executada uma vez por projeto. Após o ## Como funciona na prática -### Com o plugin - -O agente `developer` segue um fluxo estruturado para cada tarefa de codificação: +Invoque `/archgate-developer` no chat do Cursor ao iniciar uma tarefa de codificação. O agente segue um fluxo estruturado para cada alteração: 1. **Ler os ADRs aplicáveis** -- O agente executa `archgate review-context` para ver quais ADRs se aplicam aos arquivos sendo alterados. Ele não escreve código até ter lido os ADRs aplicáveis. 2. **Escrever código seguindo as restrições dos ADRs** -- O agente implementa as alterações seguindo as seções Do's and Don'ts dos ADRs aplicáveis. -3. **Executar verificações de conformidade** -- O agente executa `archgate check --staged` para rodar as regras automatizadas. Qualquer violação é corrigida antes de prosseguir. +3. **Executar verificações de conformidade** -- O agente executa `archgate check` para rodar as regras automatizadas. O hook `afterFileEdit` também detecta violações em tempo real. Qualquer violação é corrigida antes de prosseguir. -4. **Revisão do arquiteto** -- O agente invoca a skill `architect` para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam. +4. **Revisar alterações** -- O agente invoca a skill `archgate-reviewer` para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam. -5. **Capturar aprendizados** -- O agente invoca a skill `quality-manager` para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs ou atualizações em existentes. - -### Sem o plugin - -O agente usa a regra de governança e comandos CLI para seguir quatro passos manuais: - -1. **Revisar contexto** -- Executar `archgate review-context` para ver quais ADRs se aplicam aos arquivos sendo alterados. - -2. **Ler ADRs individuais** -- Para contexto completo sobre uma decisão específica, executar `archgate adr show ` (por exemplo, `archgate adr show ARCH-001`). - -3. **Escrever código** -- Implementar as alterações seguindo as restrições dos ADRs aplicáveis. - -4. **Executar verificações de conformidade** -- Executar `archgate check --staged` para validar que o código está em conformidade com todas as regras dos ADRs. +5. **Capturar aprendizados** -- O agente invoca a skill `archgate-lessons-learned` para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs ou atualizações em existentes. ## Recusa orientada por ADRs @@ -128,25 +128,38 @@ Esse comportamento é consistente independentemente de como o desenvolvedor form ## Quando usar cada agente ou skill -| Cenário | Skill | -| ------------------------------------------------------- | ----------------- | -| Iniciando um novo projeto com Archgate | `onboard` | -| Tarefas de codificação do dia a dia | `developer` | -| Revisando um PR para conformidade com ADRs | `architect` | -| Percebendo um padrão recorrente que vale ser codificado | `quality-manager` | -| Criando ou editando um ADR | `adr-author` | +| Cenário | Agente / Skill | +| ------------------------------------------------------- | --------------------------------------------------- | +| Iniciando um novo projeto com Archgate | `/archgate-developer` (e peça para fazer o onboard) | +| Tarefas de codificação do dia a dia | `/archgate-developer` | +| Planejamento e escopo de trabalho | `/archgate-planner` | +| Revisando uma alteração para conformidade com ADRs | `archgate-reviewer` | +| Percebendo um padrão recorrente que vale ser codificado | `archgate-lessons-learned` | +| Criando ou editando um ADR | `archgate-adr-author` | + +O agente `archgate-developer` orquestra as skills automaticamente -- ele invoca `archgate-reviewer` e `archgate-lessons-learned` como parte do seu fluxo. Na maioria das vezes, você só precisa invocar `/archgate-developer` e deixá-lo executar. + +## Suporte a agentes na nuvem + +O Cursor suporta agentes na nuvem que executam em VMs remotas. Esses ambientes não têm acesso a `~/.cursor/`, então skills e agentes no escopo de usuário não estão disponíveis. No entanto, o arquivo `.cursor/hooks.json` faz parte da árvore do seu projeto e funciona em VMs na nuvem. Isso significa que `archgate check` ainda é executado automaticamente após cada edição de arquivo, mesmo em sessões de agentes na nuvem. + +Para governança completa em ambientes na nuvem, garanta que `archgate` esteja disponível no PATH da VM (ex: via o script de instalação no setup do seu projeto). + +## Acesso à transcrição da sessão -O agente `developer` orquestra as skills automaticamente -- ele invoca `architect` e `quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa usar `developer` diretamente. +O comando `archgate session-context cursor` lê transcrições de sessão do agente Cursor do disco. Isso permite que skills acessem o histórico da conversa atual, o que é útil para recuperar contexto que pode ter sido compactado ou truncado. -## Regra de governança +O comando aceita dois flags opcionais: -A regra de governança em `.cursor/rules/archgate-governance.mdc` usa `alwaysApply: true`, o que significa que o agente do Cursor sempre tem o contexto de governança disponível sem ativação manual. Ela instrui o agente a executar `archgate review-context` antes de codificar e `archgate check --staged` depois. +- `--max-entries ` -- Número máximo de entradas a retornar (padrão: 200, entradas mais recentes). +- `--session-id ` -- Um UUID de sessão específico para ler. Se omitido, a sessão mais recente é usada. ## Dicas para uso eficaz -- **Use a skill `developer` para tarefas de codificação.** Ela orquestra todo o fluxo de leitura-validação-captura automaticamente. -- **Execute `onboard` uma vez por projeto.** Ela configura seus ADRs iniciais com base no seu codebase e convenções reais. -- **Use `architect` para revisões de PR.** Ela valida a conformidade estrutural além do que as regras automatizadas capturam. -- **Use `quality-manager` após resolver problemas complexos.** Ela captura aprendizados para que os mesmos erros não se repitam. -- **Faça commit do diretório `.cursor/`.** Isso garante que cada membro da equipe receba a mesma configuração de governança ao clonar o repositório. +- **Invoque `/archgate-developer` para tarefas de codificação.** Ele orquestra todo o fluxo de leitura-validação-captura automaticamente. +- **Execute onboard uma vez por projeto.** Ele configura seus ADRs iniciais com base no seu codebase e convenções reais. +- **Use `archgate-reviewer` para revisões.** Ele valida a conformidade estrutural além do que as regras automatizadas capturam. +- **Use `archgate-lessons-learned` após resolver problemas complexos.** Ele captura aprendizados para que os mesmos erros não se repitam. +- **Faça commit do diretório `.cursor/`.** O arquivo `hooks.json` garante que cada membro da equipe receba `archgate check` em edições de arquivo ao clonar o repositório. - **Mantenha os arquivos de regras dos ADRs atualizados.** O agente aplica o que as regras verificam -- se uma regra estiver faltando, a violação não será detectada. +- **Execute `archgate plugin install --editor cursor` para atualizar.** O serviço retorna o bundle de plugin mais recente em cada download autenticado. diff --git a/docs/src/content/docs/pt-br/reference/cli/init.mdx b/docs/src/content/docs/pt-br/reference/cli/init.mdx index c655659e..baa82c58 100644 --- a/docs/src/content/docs/pt-br/reference/cli/init.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/init.mdx @@ -24,7 +24,7 @@ Quando `--install-plugin` é passado, a CLI instala o plugin do Archgate para o **Claude Code:** Se a CLI `claude` estiver no seu PATH, o plugin é instalado automaticamente via `claude plugin marketplace add` e `claude plugin install`. Se a CLI `claude` não for encontrada, o comando exibe os comandos de instalação manual. -**Cursor:** Se a CLI `cursor` estiver no seu PATH, a extensão VS Code é instalada automaticamente via `cursor --install-extension`. A URL do team marketplace é impressa para descoberta manual do plugin. +**Cursor:** Faz o download de um tarball autenticado de skills, agentes e hooks em `~/.cursor/`. Também grava `.cursor/hooks.json` no projeto para compatibilidade com agentes na nuvem. Nenhuma detecção de CLI é necessária. **opencode:** Requer que a CLI `opencode` esteja no seu PATH -- se não estiver, a instalação é pulada e uma mensagem pede que você instale o opencode primeiro. Quando presente, a CLI baixa um tarball autenticado de arquivos de agente do serviço de plugins do Archgate e o extrai no diretório de agentes opencode do escopo do usuário (`$XDG_CONFIG_HOME/opencode/agents/`, com fallback para `$HOME/.config/opencode/agents/` em qualquer plataforma, inclusive Windows -- o opencode usa paths XDG via `xdg-basedir` e não lê `%APPDATA%`). Nenhum arquivo é gravado na árvore do projeto. Veja o [guia de integração com opencode](/guides/opencode-integration/) para detalhes. @@ -39,7 +39,7 @@ Initialized Archgate governance in /path/to/project Archgate plugin installed for Claude Code. ``` -Quando `--editor cursor` é usado, a saída mostra `.cursor/` em vez de `.claude/`. +Quando `--editor cursor` é usado, a saída mostra `.cursor/` para arquivos no nível do projeto e indica que os componentes no escopo de usuário foram instalados em `~/.cursor/`. ## Detecção de branch base diff --git a/docs/src/content/docs/pt-br/reference/cli/plugin.mdx b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx index bd959eef..05ee8903 100644 --- a/docs/src/content/docs/pt-br/reference/cli/plugin.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx @@ -6,7 +6,7 @@ description: "Gerencia os plugins de editor do Archgate independentemente do arc Gerencia os plugins de editor do Archgate independentemente do `archgate init`. ```bash -archgate plugin [options] +archgate plugin [options] ``` Use `archgate plugin` para instalar plugins ou obter a URL autenticada do repositório em projetos que já foram inicializados. @@ -54,7 +54,7 @@ O comportamento de instalação varia por editor: - **Claude Code:** Instala automaticamente via CLI `claude` se disponível; exibe comandos manuais caso contrário. - **Copilot CLI:** Instala automaticamente via CLI `copilot` se disponível; exibe comandos manuais caso contrário. -- **Cursor:** Exibe a URL do [Team Private Plugin Marketplace](https://cursor.com/docs/plugins#team-marketplaces) com instruções para adicioná-la nas Configurações do Cursor. O Cursor não suporta instalação de VSIX via CLI. +- **Cursor:** Faz o download de um tarball autenticado e extrai skills, agentes e hooks em `~/.cursor/`. Nenhuma detecção de CLI é necessária -- os arquivos são gravados diretamente no diretório de usuário do Cursor. - **VS Code:** Instala a extensão VS Code (`.vsix`) via CLI `code` se disponível; exibe instruções manuais caso contrário. - **opencode:** Requer que a CLI `opencode` esteja no PATH -- pula a instalação com uma mensagem clara caso contrário. Quando presente, baixa um tarball autenticado de arquivos de agente e o extrai no diretório de agentes opencode do escopo do usuário. `archgate plugin url --editor opencode` exibe "N/A" -- opencode não tem URL de marketplace. Veja o [guia de integração com opencode](/guides/opencode-integration/) para detalhes. diff --git a/docs/src/content/docs/reference/cli/init.mdx b/docs/src/content/docs/reference/cli/init.mdx index ab94a249..df0969a1 100644 --- a/docs/src/content/docs/reference/cli/init.mdx +++ b/docs/src/content/docs/reference/cli/init.mdx @@ -24,7 +24,7 @@ When `--install-plugin` is passed, the CLI installs the Archgate plugin for the **Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead. -**Cursor:** If the `cursor` CLI is on your PATH, the VS Code extension is installed automatically via `cursor --install-extension`. The team marketplace URL is printed for manual plugin discovery. +**Cursor:** Downloads an authenticated tarball of skills, agents, and hooks into `~/.cursor/`. Also writes `.cursor/hooks.json` to the project for cloud agent compatibility. No CLI detection needed. **opencode:** Requires the `opencode` CLI to be on your PATH — if it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows — opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details. @@ -39,7 +39,7 @@ Initialized Archgate governance in /path/to/project Archgate plugin installed for Claude Code. ``` -When `--editor cursor` is used, the output shows `.cursor/` instead of `.claude/`. +When `--editor cursor` is used, the output shows `.cursor/` for project-level files and notes that user-scope components were installed to `~/.cursor/`. ## Base branch detection diff --git a/docs/src/content/docs/reference/cli/plugin.mdx b/docs/src/content/docs/reference/cli/plugin.mdx index 571a91a0..1d490615 100644 --- a/docs/src/content/docs/reference/cli/plugin.mdx +++ b/docs/src/content/docs/reference/cli/plugin.mdx @@ -54,7 +54,7 @@ Installation behavior varies by editor: - **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. - **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. -- **Cursor:** Prints the [Team Private Plugin Marketplace](https://cursor.com/docs/plugins#team-marketplaces) URL with instructions to add it in Cursor Settings. Cursor does not support VSIX installation from the CLI. +- **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed — files are written directly to the Cursor user directory. - **VS Code:** Installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. - **opencode:** Requires the `opencode` CLI to be on PATH — skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" — opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details. From 4b8a3c03e72c27ca2c9dc8c204924cfe989e9ff4 Mon Sep 17 00:00:00 2001 From: rhuanbarreto <283004+rhuanbarreto@users.noreply.github.com> Date: Sat, 6 Jun 2026 14:31:01 +0000 Subject: [PATCH 7/7] docs: regenerate llms-full.txt Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/public/llms-full.txt | 56 ++++++++++++++++++++++----------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 7ccffb38..9db1a34c 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -29,7 +29,7 @@ Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercont - [Guide — Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a governance workflow that reads ADRs, validates code, and captures patterns. - [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code. - [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI. -- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor with Archgate agents, skills, and hooks. +- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills. - [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit. - [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more. - [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting. @@ -100,7 +100,7 @@ The Archgate CLI works standalone, but **editor plugins** unlock a full AI gover read-validate-capture loop on every task. - The Cursor plugin provides agents, skills, and hooks that give + The Cursor plugin provides pre-built agent rules and skills that give Cursor's AI agent the same governance workflow as Claude Code. @@ -1572,21 +1572,23 @@ archgate plugin install --editor cursor **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 governance workflow | -| `~/.cursor/agents/archgate-planner.md` | Planning agent for scoping and breaking down work | +| 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 governance 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 | +| 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 @@ -1619,6 +1621,8 @@ These are the same roles available in the Claude Code plugin (`archgate:reviewer | --------------- | --------------- | ---------------------------------------------------------- | | `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: @@ -1658,14 +1662,14 @@ This behavior is consistent regardless of how the developer phrases the request. ## When to use each agent or skill -| Scenario | Agent / 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` | +| 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. @@ -1673,6 +1677,8 @@ The `archgate-developer` agent orchestrates the skills automatically -- it invok 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. @@ -2687,7 +2693,7 @@ The `--id` and `--body` flags are required. All other frontmatter fields (`--tit 7. **Use domain prefixes to organize.** The domain field determines the ID prefix and helps filter ADRs by area. Prefer the five built-ins (`backend`, `frontend`, `data`, `architecture`, `general`); register a [custom domain](/concepts/domains/#custom-domains) only when none of them is a genuine fit. -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include an ADR authoring skill that creates and updates ADRs following your project's conventions. The lessons-learned skill also proposes new ADRs when it detects recurring patterns. [Sign up for beta access](https://plugins.archgate.dev). +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include an ADR Author skill that creates and updates ADRs following your project's conventions. The Quality Manager skill also proposes new ADRs when it detects recurring patterns. [Sign up for beta access](https://plugins.archgate.dev). --- @@ -3949,7 +3955,7 @@ archgate doctor [options] - **Archgate** -- CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status - **Project** -- Whether an `.archgate/` project exists, ADR count, domains - **Editor CLIs** -- Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH -- **Project Integrations** -- Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/hooks.json`, `.vscode/settings.json`, `.github/copilot/instructions.md`) +- **Project Integrations** -- Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) ## Example @@ -3984,7 +3990,7 @@ Editor CLIs Project Integrations Claude: OK (.claude/settings.local.json) - Cursor: MISSING (.cursor/hooks.json) + Cursor: MISSING (.cursor/rules/archgate-governance.mdc) VS Code: OK (.vscode/settings.json) Copilot: MISSING (.github/copilot/instructions.md) ``` @@ -5403,7 +5409,7 @@ Browse complete, copy-pasteable rule examples organized by category. Each rule p | [openapi-routes](/examples/openapi-routes/) | Ensure backend routes use OpenAPI-typed definitions | | [clean-architecture-layers](/examples/clean-architecture-layers/) | Enforce dependency direction in layered architectures | -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include a lessons-learned skill that identifies recurring patterns in your codebase and proposes new rules to enforce them. [Sign up for beta access](https://plugins.archgate.dev). +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include a Quality Manager skill that identifies recurring patterns in your codebase and proposes new rules to enforce them. [Sign up for beta access](https://plugins.archgate.dev). ---