diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 2447fbff..9db1a34c 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -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,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 | + +**Project scope**: + +| File | Purpose | +| -------------------- | --------------------------------------------------------------------- | +| `.cursor/hooks.json` | `afterFileEdit` hook that runs `archgate check` after every file edit | -| File | Purpose | -| --------------------------------------- | -------------------------------------------------------------- | -| `.cursor/rules/archgate-governance.mdc` | Always-on Cursor rule that instructs the agent to consult ADRs | +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 @@ -1622,31 +1636,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 +1662,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 @@ -1687,12 +1690,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. --- @@ -4053,7 +4057,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 +4072,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 +4274,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. 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. 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..ebb18b64 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}/ — 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..c0034ef8 100644 --- a/src/helpers/cursor-settings.ts +++ b/src/helpers/cursor-settings.ts @@ -3,27 +3,54 @@ /** * 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, 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` 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 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"; 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 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 { - return join(projectRoot, ".cursor"); + const cursorDir = join(projectRoot, ".cursor"); + mkdirSync(cursorDir, { recursive: true }); + + // 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 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..850df571 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}/ — 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..261569e4 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 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. + * + * 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..3c3737ac 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,80 @@ 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 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 + * - hooks.json — afterFileEdit hook for archgate check + * + * 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 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", + }); + + await mergeCursorHooks(cursorDir); +} + +/** + * 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 // --------------------------------------------------------------------------- @@ -149,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 // --------------------------------------------------------------------------- @@ -170,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"); 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..b39b3b6b 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,33 @@ 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/ directory with hooks.json", () => { configureCursorSettings(tempDir); - expect(existsSync(join(tempDir, ".cursor"))).toBe(false); + 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")); + expect(hooks).toBeArrayOfSize(1); + expect(hooks[0].event).toBe("afterFileEdit"); + expect(hooks[0].command).toContain("archgate check"); + }); + + test("does not create rules directory", () => { + configureCursorSettings(tempDir); + 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(hooksPath, "utf-8")).toBe("custom hooks"); }); }); diff --git a/tests/helpers/init-project.test.ts b/tests/helpers/init-project.test.ts index 7d2762a9..53d41b87 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 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( @@ -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/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)" + ); + }); + }); }); diff --git a/tests/integration/init.test.ts b/tests/integration/init.test.ts index 68ee1b42..256df75f 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,9 @@ 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 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 () => {