From 8f3eb26d02b294e52f58c3651354ceed5988837a Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Mon, 16 Mar 2026 00:46:52 +0100 Subject: [PATCH 1/2] docs: align plugin docs with plugins repo reality MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Distinguish agent (developer) from skills (architect, quality-manager, adr-author, onboard) across all plugin guides - Remove stale MCP server integration claims from plugin docs — plugins now use CLI commands directly (archgate review-context, archgate check) - Remove non-existent generated files: .vscode/mcp.json, .cursor/mcp.json, .github/copilot/mcp.json - Update MCP server guide to clarify it's for custom integrations, not editor plugins - Apply all changes to both EN and PT-BR translations Co-Authored-By: Claude Opus 4.6 --- .../docs/guides/claude-code-plugin.mdx | 40 +++++--- .../docs/guides/copilot-cli-plugin.mdx | 48 +++------- .../docs/guides/cursor-integration.mdx | 72 ++++++--------- docs/src/content/docs/guides/mcp-server.mdx | 10 +- .../src/content/docs/guides/vscode-plugin.mdx | 49 +++------- .../docs/pt-br/guides/claude-code-plugin.mdx | 42 +++++---- .../docs/pt-br/guides/copilot-cli-plugin.mdx | 48 +++------- .../docs/pt-br/guides/cursor-integration.mdx | 91 +++++++------------ .../content/docs/pt-br/guides/mcp-server.mdx | 10 +- .../docs/pt-br/guides/vscode-plugin.mdx | 56 ++++-------- .../docs/pt-br/reference/mcp-tools.mdx | 2 +- docs/src/content/docs/reference/mcp-tools.mdx | 2 +- 12 files changed, 183 insertions(+), 287 deletions(-) diff --git a/docs/src/content/docs/guides/claude-code-plugin.mdx b/docs/src/content/docs/guides/claude-code-plugin.mdx index 2331c2fc..38c51672 100644 --- a/docs/src/content/docs/guides/claude-code-plugin.mdx +++ b/docs/src/content/docs/guides/claude-code-plugin.mdx @@ -3,17 +3,24 @@ title: Claude Code Plugin description: Set up the Archgate plugin for Claude Code. Give AI agents a governance workflow that reads ADRs, validates code, and captures architectural patterns. --- -The Archgate Claude Code plugin gives AI agents working in [Claude Code](https://claude.ai/code) a structured governance workflow. Instead of relying on prompt instructions that drift over time, agents read your ADRs directly through the MCP server and validate their own code against your rules. +The Archgate Claude Code plugin gives AI agents working in [Claude Code](https://claude.ai/code) a structured governance workflow. Instead of relying on prompt instructions that drift over time, agents read your ADRs directly via Archgate CLI commands and validate their own code against your rules. ## What the plugin provides -The plugin adds role-based skills to Claude Code. Each skill encapsulates a specific part of the governance workflow, so agents follow the same process every time -- read decisions before coding, validate after, and capture new patterns for the team. +The plugin adds an agent and role-based skills to Claude Code. The agent orchestrates the governance workflow, invoking skills as needed -- read decisions before coding, validate after, and capture new patterns for the team. -### Skills included +### Agent + +| Agent | Purpose | +| -------------------- | --------------------------------------------------------------------------- | +| `archgate:developer` | General development agent that reads ADRs before coding and validates after | + +The `archgate:developer` agent is set as the default agent via `.claude/settings.local.json`. It orchestrates the skills below automatically as part of its workflow. + +### Skills | Skill | Purpose | | -------------------------- | ------------------------------------------------------------------------------------- | -| `archgate:developer` | General development agent that reads ADRs before coding and validates after | | `archgate:architect` | Validates code changes against all project ADRs for structural compliance | | `archgate:quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge | | `archgate:adr-author` | Creates and edits ADRs following project conventions | @@ -49,6 +56,8 @@ To explicitly request plugin installation: archgate init --install-plugin ``` +This creates `.claude/settings.local.json` with the `archgate:developer` agent and skill permissions pre-configured. + If the `claude` CLI is on your PATH, the plugin is installed automatically via: 1. `claude plugin marketplace add` (registers the Archgate marketplace) @@ -73,7 +82,7 @@ The plugin follows a structured workflow for every coding task: ### 1. Read applicable ADRs -When the developer gives a coding task, the agent reads all ADRs that apply to the files being changed. The MCP server provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR. +When the developer gives a coding task, the agent runs `archgate review-context` to read all ADRs that apply to the files being changed. This provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR. The agent does not write code until it has read the applicable ADRs. This is enforced by the `archgate:developer` skill. @@ -105,20 +114,21 @@ For example, if a developer asks the agent to add `chalk` as a dependency in a p This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions. -## MCP server integration +## How the plugin accesses ADRs -The plugin communicates with your project's ADRs through the Archgate MCP server. The server provides: +The plugin uses Archgate CLI commands directly to read ADRs and run compliance checks. The key commands are: -- **ADR content** -- full text of any ADR, accessible by ID -- **Review context** -- condensed briefings of all ADRs applicable to a set of changed files -- **Rule checking** -- execution of automated rules with violation reporting -- **ADR listing** -- inventory of all ADRs in the project with metadata +- **`archgate review-context`** -- condensed briefings of all ADRs applicable to changed files, grouped by domain +- **`archgate check --staged`** -- automated rule checking with violation reporting +- **`archgate adr show `** -- full text of a specific ADR +- **`archgate adr list`** -- inventory of all ADRs in the project with metadata +- **`archgate session-context claude-code`** -- read session transcripts for context recovery -The MCP server runs locally and reads directly from your `.archgate/adrs/` directory. No data leaves your machine. +All commands run locally and read directly from your `.archgate/adrs/` directory. No data leaves your machine. -## When to use each skill +## When to use each agent or skill -| Scenario | Skill to use | +| Scenario | Agent or skill | | -------------------------------------------- | -------------------------- | | Starting a new project with Archgate | `archgate:onboard` | | Day-to-day coding tasks | `archgate:developer` | @@ -126,4 +136,4 @@ The MCP server runs locally and reads directly from your `.archgate/adrs/` direc | Noticing a recurring pattern worth codifying | `archgate:quality-manager` | | Creating or editing an ADR | `archgate:adr-author` | -The `archgate:developer` skill orchestrates the others automatically -- it invokes `archgate:architect` and `archgate:quality-manager` as part of its workflow. Most of the time, you only need to interact with the developer skill directly. +The `archgate:developer` agent orchestrates the skills automatically -- it invokes `archgate:architect` and `archgate:quality-manager` as part of its workflow. Most of the time, you only need to interact with the developer agent directly. diff --git a/docs/src/content/docs/guides/copilot-cli-plugin.mdx b/docs/src/content/docs/guides/copilot-cli-plugin.mdx index 58126e7a..2e5db840 100644 --- a/docs/src/content/docs/guides/copilot-cli-plugin.mdx +++ b/docs/src/content/docs/guides/copilot-cli-plugin.mdx @@ -49,26 +49,7 @@ archgate init --editor copilot --install-plugin ### Generated files -The command creates the following configuration: - -| File | Purpose | -| -------------------------- | ---------------------------------------------------- | -| `.github/copilot/mcp.json` | MCP server connection so Copilot CLI can access ADRs | - -If `.github/copilot/mcp.json` already exists, Archgate merges its configuration additively -- existing MCP server entries are preserved. - -The MCP configuration: - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` +The command creates the `.github/copilot/` directory for plugin configuration. Plugin installation is handled separately via the `copilot plugin install` command. ### Manual installation @@ -82,13 +63,20 @@ You can find your authenticated URL by running `archgate login` and checking `~/ ## What the plugin provides -The plugin adds role-based skills to Copilot CLI. Each skill encapsulates a specific part of the governance workflow, so agents follow the same process every time. +The plugin adds an agent and role-based skills to Copilot CLI. The agent orchestrates the governance workflow, invoking skills as needed. + +### Agent -### Skills included +| Agent | Purpose | +| -------------------- | --------------------------------------------------------------------------- | +| `archgate:developer` | General development agent that reads ADRs before coding and validates after | + +The `archgate:developer` agent is set as the default agent via the plugin settings. It orchestrates the skills below automatically as part of its workflow. + +### Skills | Skill | Purpose | | -------------------------- | ------------------------------------------------------------------------------------- | -| `archgate:developer` | General development agent that reads ADRs before coding and validates after | | `archgate:architect` | Validates code changes against all project ADRs for structural compliance | | `archgate:quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge | | `archgate:adr-author` | Creates and edits ADRs following project conventions | @@ -111,7 +99,7 @@ The plugin follows a structured workflow for every coding task: ### 1. Read applicable ADRs -When the developer gives a coding task, the agent reads all ADRs that apply to the files being changed. The MCP server provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR. +When the developer gives a coding task, the agent runs `archgate review-context` to read all ADRs that apply to the files being changed. This provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR. ### 2. Write code following ADR constraints @@ -129,19 +117,7 @@ The agent invokes `archgate:architect` to validate structural ADR compliance bey The agent invokes `archgate:quality-manager` to review the work and identify patterns worth capturing as new ADRs. -## MCP server integration - -The plugin communicates with your project's ADRs through the Archgate MCP server. The server provides: - -- **ADR content** -- full text of any ADR, accessible by ID -- **Review context** -- condensed briefings of all ADRs applicable to a set of changed files -- **Rule checking** -- execution of automated rules with violation reporting -- **ADR listing** -- inventory of all ADRs in the project with metadata - -The MCP server runs locally and reads directly from your `.archgate/adrs/` directory. No data leaves your machine. - ## Tips -- **Commit `.github/copilot/mcp.json`** to share the MCP configuration with your team. - **Run onboard once per project** to generate your initial ADRs from your actual codebase. - **Keep ADR rule files up to date** -- the agent enforces what the rules check for. diff --git a/docs/src/content/docs/guides/cursor-integration.mdx b/docs/src/content/docs/guides/cursor-integration.mdx index b35658c1..b3d9f95d 100644 --- a/docs/src/content/docs/guides/cursor-integration.mdx +++ b/docs/src/content/docs/guides/cursor-integration.mdx @@ -28,36 +28,40 @@ archgate login # one-time setup archgate init --editor cursor --install-plugin ``` -The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. It includes agent rules, skill definitions, and MCP configuration. +The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. It includes agent rules and skill definitions. ### Without plugin (free) -Without the plugin, `archgate init --editor cursor` still configures the MCP server connection and a basic governance rule. The AI agent can access your ADRs and run checks, but does not get the role-based skills described below. +Without the plugin, `archgate init --editor cursor` still configures a basic governance rule. The AI agent can consult ADRs and run checks via CLI commands, but does not get the role-based skills described below. ### Generated files | File | Purpose | | --------------------------------------- | -------------------------------------------------------------- | -| `.cursor/mcp.json` | MCP server connection so Cursor's AI agent can access ADRs | | `.cursor/rules/archgate-governance.mdc` | Always-on Cursor rule that instructs the agent to consult ADRs | -If `.cursor/mcp.json` already exists, Archgate merges its configuration additively -- existing MCP server entries are preserved. - ## What the plugin provides -The plugin adds role-based skills to Cursor. Each skill is invoked as a slash command with the `/ag-` prefix. Skills encapsulate specific parts of the governance workflow so the agent follows the same process every time. +The plugin adds an agent and role-based skills to Cursor. Each is invoked as a slash command with the `/ag-` prefix. The agent orchestrates the governance workflow, invoking skills as needed. + +### Agent + +| Slash command | Purpose | +| --------------- | --------------------------------------------------------------------------- | +| `/ag-developer` | General development agent that reads ADRs before coding and validates after | -### Skills included +The `/ag-developer` agent orchestrates the skills below automatically as part of its workflow. -| Slash command | Skill | Purpose | -| --------------------- | --------------- | ------------------------------------------------------------------------------------- | -| `/ag-developer` | Developer | General development agent that reads ADRs before coding and validates after | -| `/ag-architect` | Architect | Validates code changes against all project ADRs for structural compliance | -| `/ag-quality-manager` | Quality Manager | Reviews rule coverage and proposes new ADRs when patterns emerge | -| `/ag-adr-author` | ADR Author | Creates and edits ADRs following project conventions | -| `/ag-onboard` | Onboard | One-time setup: explores the codebase, interviews the developer, creates initial ADRs | +### Skills -These are the same skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's slash command interface. +| Slash command | Purpose | +| --------------------- | ------------------------------------------------------------------------------------- | +| `/ag-architect` | Validates code changes against all project ADRs for structural compliance | +| `/ag-quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge | +| `/ag-adr-author` | Creates and edits ADRs following project conventions | +| `/ag-onboard` | One-time setup: explores the codebase, interviews the developer, creates initial ADRs | + +These are the same agent and skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's slash command interface with the `ag-` prefix. ## Initial setup with onboard @@ -88,15 +92,15 @@ The `/ag-developer` skill follows a structured workflow for every coding task: ### Without the plugin -The agent connects to the Archgate MCP server and follows four manual steps: +The agent uses the governance rule and CLI commands to follow four manual steps: -1. **Review context** -- Call `review_context` to see which ADRs apply to the files being changed. +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, read the `adr://` resource (for example, `adr://ARCH-001`). +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** -- Call `check` (optionally with `staged: true`) to validate that the code complies with all ADR rules. +4. **Run compliance checks** -- Run `archgate check --staged` to validate that the code complies with all ADR rules. ## ADR-driven refusal @@ -110,7 +114,7 @@ For example, if a developer asks the agent to add `chalk` as a dependency in a p This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions. -## When to use each skill +## When to use each agent or skill | Scenario | Slash command | | -------------------------------------------- | --------------------- | @@ -120,33 +124,11 @@ This behavior is consistent regardless of how the developer phrases the request. | Noticing a recurring pattern worth codifying | `/ag-quality-manager` | | Creating or editing an ADR | `/ag-adr-author` | -The `/ag-developer` skill orchestrates the others automatically -- it invokes `/ag-architect` and `/ag-quality-manager` as part of its workflow. Most of the time, you only need to use `/ag-developer` directly. - -## MCP server configuration - -The generated `.cursor/mcp.json` registers the Archgate MCP server: - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` - -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. - -The MCP server provides: +The `/ag-developer` agent orchestrates the skills automatically -- it invokes `/ag-architect` and `/ag-quality-manager` as part of its workflow. Most of the time, you only need to use `/ag-developer` directly. -- **ADR content** -- full text of any ADR, accessible by ID via `adr://` resources -- **Review context** -- condensed briefings of all ADRs applicable to a set of changed files -- **Rule checking** -- execution of automated rules with violation reporting -- **ADR listing** -- inventory of all ADRs in the project with metadata +## Governance rule -The MCP server runs locally and reads directly from your `.archgate/adrs/` directory. No data leaves your machine. +The governance rule in `.cursor/rules/archgate-governance.mdc` uses `alwaysApply: true`, which means the Cursor agent always has governance context available without manual activation. It instructs the agent to run `archgate review-context` before coding and `archgate check --staged` after. ## Session transcript access diff --git a/docs/src/content/docs/guides/mcp-server.mdx b/docs/src/content/docs/guides/mcp-server.mdx index 0ee7e0a9..c5001ed0 100644 --- a/docs/src/content/docs/guides/mcp-server.mdx +++ b/docs/src/content/docs/guides/mcp-server.mdx @@ -30,11 +30,15 @@ Add the following to your project's `.mcp.json` file (create it if it does not e } ``` -Claude Code reads this file on startup and connects to the Archgate MCP server automatically. You can also run `archgate init` (which defaults to `--editor claude`) to generate this configuration along with the full `.archgate/` directory. +Claude Code reads this file on startup and connects to the Archgate MCP server automatically. + +:::note[Editor plugins use CLI commands directly] +The Archgate editor plugins (Claude Code, Cursor, VS Code, Copilot CLI) do **not** use the MCP server. They invoke Archgate CLI commands directly (e.g., `archgate review-context`, `archgate check`). The MCP server is for custom integrations or MCP-compatible clients that are not using the editor plugins. +::: ## Configuring in Cursor -Run `archgate init --editor cursor` to generate `.cursor/mcp.json` with the same server configuration. See the [Cursor Integration](/guides/cursor-integration/) guide for details. +Add the same configuration to your project's `.cursor/mcp.json` file. See the [Cursor Integration](/guides/cursor-integration/) guide for details. ## Available MCP tools @@ -119,5 +123,5 @@ A typical AI agent session using the MCP server follows this pattern: 6. **Agent iterates** until `check` reports zero violations. :::tip[Automate this entire workflow] -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) automate this flow end-to-end. The agent reads ADRs, writes compliant code, runs checks, validates with the architect skill, and captures learnings -- all without manual MCP tool calls. [Sign up for beta access](https://plugins.archgate.dev). +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) automate this flow end-to-end using CLI commands directly. The agent reads ADRs, writes compliant code, runs checks, validates with the architect skill, and captures learnings -- all without manual intervention. [Sign up for beta access](https://plugins.archgate.dev). ::: diff --git a/docs/src/content/docs/guides/vscode-plugin.mdx b/docs/src/content/docs/guides/vscode-plugin.mdx index b9c1d182..af522aad 100644 --- a/docs/src/content/docs/guides/vscode-plugin.mdx +++ b/docs/src/content/docs/guides/vscode-plugin.mdx @@ -61,27 +61,13 @@ archgate init --editor vscode --install-plugin ### Generated files -The command creates or updates the following files: +The command creates or updates the following: -| File | Scope | Purpose | -| -------------------- | --------- | -------------------------------------------------------- | -| `.vscode/mcp.json` | Workspace | MCP server configuration so VS Code can access your ADRs | -| User `settings.json` | User | `chat.plugins.marketplaces` with the authenticated URL | +| File | Scope | Purpose | +| -------------------- | ----- | ------------------------------------------------------ | +| User `settings.json` | User | `chat.plugins.marketplaces` with the authenticated URL | -If `.vscode/mcp.json` already exists, Archgate merges its configuration additively -- existing server entries are preserved. The user settings file is also merged additively -- existing settings are never overwritten. - -The workspace MCP configuration (`.vscode/mcp.json`): - -```json -{ - "servers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` +The user settings file is merged additively -- existing settings are never overwritten. VS Code's built-in default marketplaces (`github/copilot-plugins`, `github/awesome-copilot`) are preserved when the key is set for the first time. The user-level marketplace setting (added to your `settings.json`): @@ -99,13 +85,20 @@ If you prefer not to let the CLI modify your user settings, you can add the mark ## What the plugin provides -The plugin adds role-based skills to VS Code's AI agent. Each skill encapsulates a specific part of the governance workflow, so agents follow the same process every time. +The plugin adds an agent and role-based skills to VS Code's AI. The agent orchestrates the governance workflow, invoking skills as needed. + +### Agent -### Skills included +| Agent | Purpose | +| -------------------- | --------------------------------------------------------------------------- | +| `archgate:developer` | General development agent that reads ADRs before coding and validates after | + +The `archgate:developer` agent is set as the default agent via the plugin settings. It orchestrates the skills below automatically as part of its workflow. + +### Skills | Skill | Purpose | | -------------------------- | ------------------------------------------------------------------------------------- | -| `archgate:developer` | General development agent that reads ADRs before coding and validates after | | `archgate:architect` | Validates code changes against all project ADRs for structural compliance | | `archgate:quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge | | `archgate:adr-author` | Creates and edits ADRs following project conventions | @@ -146,20 +139,8 @@ The agent invokes `archgate:architect` to validate structural ADR compliance bey The agent invokes `archgate:quality-manager` to review the work and identify patterns worth capturing as new ADRs. -## MCP server integration - -The plugin communicates with your project's ADRs through the Archgate MCP server. The server provides: - -- **ADR content** -- full text of any ADR, accessible by ID -- **Review context** -- condensed briefings of all ADRs applicable to a set of changed files -- **Rule checking** -- execution of automated rules with violation reporting -- **ADR listing** -- inventory of all ADRs in the project with metadata - -The MCP server runs locally and reads directly from your `.archgate/adrs/` directory. No data leaves your machine. - ## Tips -- **Commit `.vscode/mcp.json`** to share the MCP configuration with your team. - **Each developer runs `archgate init --editor vscode`** after `archgate login` to configure their user-level marketplace URL. - **Run onboard once per project** to generate your initial ADRs from your actual codebase. - **Keep ADR rule files up to date** -- the agent enforces what the rules check for. diff --git a/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx index 15b6255b..49736040 100644 --- a/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx +++ b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx @@ -3,17 +3,24 @@ title: Plugin para Claude Code description: Configure o plugin Archgate para Claude Code. Dê aos agentes de IA um fluxo de governança que lê ADRs, valida código e captura padrões arquiteturais. --- -O plugin Archgate para Claude Code oferece aos agentes de IA que trabalham no [Claude Code](https://claude.ai/code) um fluxo de governança estruturado. Em vez de depender de instruções em prompts que se deterioram com o tempo, os agentes leem seus ADRs diretamente pelo servidor MCP e validam o próprio código contra suas regras. +O plugin Archgate para Claude Code oferece aos agentes de IA que trabalham no [Claude Code](https://claude.ai/code) um fluxo de governança estruturado. Em vez de depender de instruções em prompts que se deterioram com o tempo, os agentes leem seus ADRs diretamente via comandos do CLI Archgate e validam o próprio código contra suas regras. ## O que o plugin oferece -O plugin adiciona skills baseadas em papéis ao Claude Code. Cada skill encapsula uma parte específica do fluxo de governança, garantindo que os agentes sigam o mesmo processo todas as vezes -- ler as decisões antes de codificar, validar depois e capturar novos padrões para a equipe. +O plugin adiciona um agente e skills baseadas em papéis ao Claude Code. O agente orquestra o fluxo de governança, invocando skills conforme necessário -- ler as decisões antes de codificar, validar depois e capturar novos padrões para a equipe. -### Skills incluídas +### Agente + +| Agente | Propósito | +| -------------------- | ------------------------------------------------------------------------------ | +| `archgate:developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | + +O agente `archgate:developer` é definido como agente padrão via `.claude/settings.local.json`. Ele orquestra as skills abaixo automaticamente como parte do seu fluxo. + +### Skills | Skill | Propósito | | -------------------------- | ------------------------------------------------------------------------------------------ | -| `archgate:developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | | `archgate:architect` | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | | `archgate:quality-manager` | 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 | @@ -49,6 +56,8 @@ Para solicitar explicitamente a instalação do plugin: archgate init --install-plugin ``` +Isso cria `.claude/settings.local.json` com o agente `archgate:developer` e as permissões de skills pré-configuradas. + Se o CLI `claude` estiver no seu PATH, o plugin é instalado automaticamente via: 1. `claude plugin marketplace add` (registra o marketplace do Archgate) @@ -73,9 +82,9 @@ O plugin segue um fluxo estruturado para cada tarefa de codificação: ### 1. Ler os ADRs aplicáveis -Quando o desenvolvedor atribui uma tarefa de codificação, o agente lê todos os ADRs que se aplicam aos arquivos sendo alterados. O servidor MCP fornece um resumo condensado com as seções **Decision** e **Do's and Don'ts** de cada ADR relevante. +Quando o desenvolvedor atribui uma tarefa de codificação, o agente executa `archgate review-context` para ler todos os ADRs que se aplicam aos arquivos sendo alterados. Isso fornece um resumo condensado com as seções **Decision** e **Do's and Don'ts** de cada ADR relevante. -O agente não escreve código até ter lido os ADRs aplicáveis. Isso é garantido pela skill `archgate:developer`. +O agente não escreve código até ter lido os ADRs aplicáveis. Isso é garantido pelo agente `archgate:developer`. ### 2. Escrever código seguindo as restrições dos ADRs @@ -105,20 +114,21 @@ Por exemplo, se um desenvolvedor pedir ao agente para adicionar `chalk` como dep Esse comportamento é consistente independentemente de como o desenvolvedor formula a solicitação. ADRs são tratados como restrições obrigatórias, não sugestões. -## Integração com o servidor MCP +## Como o plugin acessa os ADRs -O plugin se comunica com os ADRs do seu projeto por meio do servidor MCP do Archgate. O servidor fornece: +O plugin usa comandos do CLI Archgate diretamente para ler ADRs e executar verificações de conformidade. Os comandos principais são: -- **Conteúdo de ADRs** -- texto completo de qualquer ADR, acessível por ID -- **Contexto de revisão** -- resumos condensados de todos os ADRs aplicáveis a um conjunto de arquivos alterados -- **Verificação de regras** -- execução de regras automatizadas com relatório de violações -- **Listagem de ADRs** -- inventário de todos os ADRs do projeto com metadados +- **`archgate review-context`** -- resumos condensados de todos os ADRs aplicáveis a arquivos alterados, agrupados por domínio +- **`archgate check --staged`** -- verificação automatizada de regras com relatório de violações +- **`archgate adr show `** -- texto completo de um ADR específico +- **`archgate adr list`** -- inventário de todos os ADRs do projeto com metadados +- **`archgate session-context claude-code`** -- lê transcrições de sessão para recuperação de contexto -O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. +Todos os comandos rodam localmente e leem diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. -## Quando usar cada skill +## Quando usar cada agente ou skill -| Cenário | Skill a usar | +| Cenário | Agente ou skill | | ------------------------------------------------------- | -------------------------- | | Iniciando um novo projeto com Archgate | `archgate:onboard` | | Tarefas de codificação do dia a dia | `archgate:developer` | @@ -126,4 +136,4 @@ O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/ad | Percebendo um padrão recorrente que vale ser codificado | `archgate:quality-manager` | | Criando ou editando um ADR | `archgate:adr-author` | -A skill `archgate:developer` orquestra as outras automaticamente -- ela invoca `archgate:architect` e `archgate:quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa interagir diretamente com a skill de developer. +O agente `archgate:developer` orquestra as skills automaticamente -- ele invoca `archgate:architect` e `archgate:quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa interagir diretamente com o agente developer. diff --git a/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx b/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx index c72cfb85..f562ff56 100644 --- a/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx +++ b/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx @@ -49,26 +49,7 @@ archgate init --editor copilot --install-plugin ### Arquivos gerados -O comando cria a seguinte configuração: - -| Arquivo | Propósito | -| -------------------------- | ------------------------------------------------------------- | -| `.github/copilot/mcp.json` | Conexão do servidor MCP para que o Copilot CLI acesse os ADRs | - -Se `.github/copilot/mcp.json` já existir, o Archgate mescla sua configuração de forma aditiva -- entradas de servidores MCP existentes são preservadas. - -A configuração MCP: - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` +O comando cria o diretório `.github/copilot/` para configuração do plugin. A instalação do plugin é feita separadamente via o comando `copilot plugin install`. ### Instalação manual @@ -82,13 +63,20 @@ Você pode encontrar sua URL autenticada executando `archgate login` e verifican ## O que o plugin oferece -O plugin adiciona skills baseadas em papéis ao Copilot CLI. Cada skill encapsula uma parte específica do fluxo de governança, garantindo que os agentes sigam o mesmo processo todas as vezes. +O plugin adiciona um agente e skills baseadas em papéis ao Copilot CLI. O agente orquestra o fluxo de governança, invocando skills conforme necessário. + +### Agente -### Skills incluídas +| Agente | Propósito | +| -------------------- | ------------------------------------------------------------------------------ | +| `archgate:developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | + +O agente `archgate:developer` é definido como agente padrão via as configurações do plugin. Ele orquestra as skills abaixo automaticamente como parte do seu fluxo. + +### Skills | Skill | Propósito | | -------------------------- | ------------------------------------------------------------------------------------------ | -| `archgate:developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | | `archgate:architect` | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | | `archgate:quality-manager` | 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 | @@ -111,7 +99,7 @@ O plugin segue um fluxo estruturado para cada tarefa de codificação: ### 1. Ler os ADRs aplicáveis -Quando o desenvolvedor atribui uma tarefa de codificação, o agente lê todos os ADRs que se aplicam aos arquivos sendo alterados. O servidor MCP fornece um resumo condensado com as seções **Decision** e **Do's and Don'ts** de cada ADR relevante. +Quando o desenvolvedor atribui uma tarefa de codificação, o agente executa `archgate review-context` para ler todos os ADRs que se aplicam aos arquivos sendo alterados. Isso fornece um resumo condensado com as seções **Decision** e **Do's and Don'ts** de cada ADR relevante. ### 2. Escrever código seguindo as restrições dos ADRs @@ -129,19 +117,7 @@ O agente invoca `archgate:architect` para validar a conformidade estrutural com O agente invoca `archgate:quality-manager` para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs. -## Integração com o servidor MCP - -O plugin se comunica com os ADRs do seu projeto por meio do servidor MCP do Archgate. O servidor fornece: - -- **Conteúdo de ADRs** -- texto completo de qualquer ADR, acessível por ID -- **Contexto de revisão** -- resumos condensados de todos os ADRs aplicáveis a um conjunto de arquivos alterados -- **Verificação de regras** -- execução de regras automatizadas com relatório de violações -- **Listagem de ADRs** -- inventário de todos os ADRs do projeto com metadados - -O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. - ## Dicas -- **Faça commit do `.github/copilot/mcp.json`** para compartilhar a configuração MCP com sua equipe. - **Execute o onboard uma vez por projeto** para gerar seus ADRs iniciais a partir do seu codebase real. - **Mantenha os arquivos de regras dos ADRs atualizados** -- o agente aplica o que as regras verificam. 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 70d44715..ea9cbd9f 100644 --- a/docs/src/content/docs/pt-br/guides/cursor-integration.mdx +++ b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx @@ -28,36 +28,40 @@ archgate login # configuração única archgate init --editor cursor --install-plugin ``` -O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. Ele inclui regras de agente, definições de skills e configuração MCP. +O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. Ele inclui regras de agente e definições de skills. ### Sem plugin (gratuito) -Sem o plugin, `archgate init --editor cursor` ainda configura a conexão com o servidor MCP e uma regra de governança básica. O agente de IA pode acessar seus ADRs e executar verificações, mas não recebe as skills baseadas em papéis descritas abaixo. +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. ### Arquivos gerados -| Arquivo | Propósito | -| --------------------------------------- | --------------------------------------------------------------------------- | -| `.cursor/mcp.json` | Conexão com o servidor MCP para que o agente de IA do Cursor acesse os ADRs | -| `.cursor/rules/archgate-governance.mdc` | Regra sempre ativa do Cursor que instrui o agente a consultar os ADRs | - -Se `.cursor/mcp.json` já existir, o Archgate mescla sua configuração de forma aditiva -- entradas de servidor MCP existentes são preservadas. +| Arquivo | Propósito | +| --------------------------------------- | --------------------------------------------------------------------- | +| `.cursor/rules/archgate-governance.mdc` | Regra sempre ativa do Cursor que instrui o agente a consultar os ADRs | ## O que o plugin oferece -O plugin adiciona skills baseadas em papéis ao Cursor. Cada skill é invocada como um slash command com o prefixo `/ag-`. As skills encapsulam partes específicas do fluxo de governança para que o agente siga o mesmo processo todas as vezes. +O plugin adiciona um agente e skills baseadas em papéis ao Cursor. Cada um é invocado como um slash command com o prefixo `/ag-`. O agente orquestra o fluxo de governança, invocando skills conforme necessário. + +### Agente + +| Slash command | Propósito | +| --------------- | ------------------------------------------------------------------------------ | +| `/ag-developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | + +O agente `/ag-developer` orquestra as skills abaixo automaticamente como parte do seu fluxo. -### Skills incluídas +### Skills -| Slash command | Skill | Propósito | -| --------------------- | --------------- | ------------------------------------------------------------------------------------------ | -| `/ag-developer` | Developer | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | -| `/ag-architect` | Architect | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | -| `/ag-quality-manager` | Quality Manager | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem | -| `/ag-adr-author` | ADR Author | Cria e edita ADRs seguindo as convenções do projeto | -| `/ag-onboard` | Onboard | Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | +| Slash command | Propósito | +| --------------------- | ------------------------------------------------------------------------------------------ | +| `/ag-architect` | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | +| `/ag-quality-manager` | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem | +| `/ag-adr-author` | Cria e edita ADRs seguindo as convenções do projeto | +| `/ag-onboard` | Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | -Essas são as mesmas skills disponíveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptadas para a interface de slash commands do Cursor. +Esses são o mesmo agente e skills disponíveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptados para a interface de slash commands do Cursor com o prefixo `ag-`. ## Configuração inicial com onboard @@ -74,9 +78,9 @@ A skill de onboard foi projetada para ser executada uma vez por projeto. Após o ### Com o plugin -A skill `/ag-developer` segue um fluxo estruturado para cada tarefa de codificação: +O agente `/ag-developer` segue um fluxo estruturado para cada tarefa de codificação: -1. **Ler os ADRs aplicáveis** -- O agente chama `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. +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. @@ -88,15 +92,15 @@ A skill `/ag-developer` segue um fluxo estruturado para cada tarefa de codifica ### Sem o plugin -O agente se conecta ao servidor MCP do Archgate e segue quatro passos manuais: +O agente usa a regra de governança e comandos CLI para seguir quatro passos manuais: -1. **Revisar contexto** -- Chamar `review_context` para ver quais ADRs se aplicam aos arquivos sendo alterados. +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, ler o recurso `adr://` (por exemplo, `adr://ARCH-001`). +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** -- Chamar `check` (opcionalmente com `staged: true`) para validar que o código está em conformidade com todas as regras dos ADRs. +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. ## Recusa orientada por ADRs @@ -110,7 +114,7 @@ Por exemplo, se um desenvolvedor pedir ao agente para adicionar `chalk` como dep Esse comportamento é consistente independentemente de como o desenvolvedor formula a solicitação. ADRs são tratados como restrições obrigatórias, não sugestões. -## Quando usar cada skill +## Quando usar cada agente ou skill | Cenário | Slash command | | ------------------------------------------------------- | --------------------- | @@ -120,42 +124,11 @@ Esse comportamento é consistente independentemente de como o desenvolvedor form | Percebendo um padrão recorrente que vale ser codificado | `/ag-quality-manager` | | Criando ou editando um ADR | `/ag-adr-author` | -A skill `/ag-developer` orquestra as outras automaticamente -- ela invoca `/ag-architect` e `/ag-quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa usar `/ag-developer` diretamente. - -## Configuração do servidor MCP - -O arquivo `.cursor/mcp.json` gerado registra o servidor MCP do Archgate: - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` - -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. - -O servidor MCP fornece: - -- **Conteúdo de ADRs** -- texto completo de qualquer ADR, acessível por ID via recursos `adr://` -- **Contexto de revisão** -- resumos condensados de todos os ADRs aplicáveis a um conjunto de arquivos alterados -- **Verificação de regras** -- execução de regras automatizadas com relatório de violações -- **Listagem de ADRs** -- inventário de todos os ADRs do projeto com metadados - -O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. - -## Acesso a transcrições de sessão - -A ferramenta MCP `cursor_session_context` lê transcrições de sessão do agente Cursor a partir do disco. Isso permite que as skills acessem o histórico da conversa atual, o que é útil para recuperar contexto que pode ter sido compactado ou truncado. +O agente `/ag-developer` orquestra as skills automaticamente -- ele invoca `/ag-architect` e `/ag-quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa usar `/ag-developer` diretamente. -A ferramenta aceita dois parâmetros opcionais: +## Regra de governança -- `maxEntries` -- Número máximo de entradas a retornar (padrão: 200, entradas mais recentes). -- `sessionId` -- Um UUID de sessão específico para ler. Se omitido, a sessão mais recente é usada. +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. ## Dicas para uso eficaz diff --git a/docs/src/content/docs/pt-br/guides/mcp-server.mdx b/docs/src/content/docs/pt-br/guides/mcp-server.mdx index 87216895..8ae0b529 100644 --- a/docs/src/content/docs/pt-br/guides/mcp-server.mdx +++ b/docs/src/content/docs/pt-br/guides/mcp-server.mdx @@ -30,11 +30,15 @@ Adicione o seguinte ao arquivo `.mcp.json` do seu projeto (crie-o se não existi } ``` -O Claude Code lê esse arquivo na inicialização e se conecta ao servidor MCP do Archgate automaticamente. Você também pode executar `archgate init` (que usa `--editor claude` por padrão) para gerar essa configuração junto com o diretório `.archgate/` completo. +O Claude Code lê esse arquivo na inicialização e se conecta ao servidor MCP do Archgate automaticamente. + +:::note[Plugins de editor usam comandos CLI diretamente] +Os plugins de editor do Archgate (Claude Code, Cursor, VS Code, Copilot CLI) **não** usam o servidor MCP. Eles invocam comandos do CLI Archgate diretamente (ex.: `archgate review-context`, `archgate check`). O servidor MCP é para integrações customizadas ou clientes compatíveis com MCP que não usam os plugins de editor. +::: ## Configurando no Cursor -Execute `archgate init --editor cursor` para gerar `.cursor/mcp.json` com a mesma configuração de servidor. Consulte o guia de [Integração com Cursor](/guides/cursor-integration/) para mais detalhes. +Adicione a mesma configuração ao arquivo `.cursor/mcp.json` do seu projeto. Consulte o guia de [Integração com Cursor](/pt-br/guides/cursor-integration/) para mais detalhes. ## Ferramentas MCP disponíveis @@ -119,5 +123,5 @@ Uma sessão típica de agente de IA usando o servidor MCP segue este padrão: 6. **O agente itera** até que `check` reporte zero violações. :::tip[Automatize todo esse fluxo] -Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) automatizam esse fluxo de ponta a ponta. O agente lê ADRs, escreve código em conformidade, executa verificações, valida com a skill de arquiteto e captura aprendizados -- tudo sem chamadas manuais de ferramentas MCP. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +Os plugins de editor para [Claude Code](/pt-br/guides/claude-code-plugin/) e [Cursor](/pt-br/guides/cursor-integration/) automatizam esse fluxo de ponta a ponta usando comandos CLI diretamente. O agente lê ADRs, escreve código em conformidade, executa verificações, valida com a skill de arquiteto e captura aprendizados -- tudo sem intervenção manual. [Cadastre-se para acesso beta](https://plugins.archgate.dev). ::: diff --git a/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx b/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx index 1d72e4b7..79cff865 100644 --- a/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx +++ b/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx @@ -9,7 +9,7 @@ O plugin Archgate para VS Code oferece aos agentes de IA que trabalham no [VS Co O VS Code suporta **plugins de agente** instalados a partir de marketplaces baseados em git. O plugin Archgate é servido a partir de um repositório git em `plugins.archgate.dev/archgate-vscode.git`. Quando você adiciona esse marketplace às suas configurações de usuário do VS Code, o VS Code descobre e instala o plugin automaticamente. -O plugin usa o mesmo formato dos plugins do Claude Code (`.claude-plugin/plugin.json`), que o sistema de plugins de agente do VS Code reconhece nativamente. +O plugin é servido no formato nativo `.github/plugin/` do VS Code Copilot, separado do formato `.claude-plugin/` do Claude Code. ## Instalação @@ -42,8 +42,7 @@ archgate init --editor vscode Se você já estiver logado, este comando: 1. Cria o diretório de governança `.archgate/` (ADRs, regras de lint) -2. Cria `.vscode/mcp.json` com a configuração do servidor MCP do Archgate -3. Adiciona a URL autenticada do marketplace nas suas **configurações de usuário** do VS Code +2. Adiciona a URL autenticada do marketplace nas suas **configurações de usuário** do VS Code A configuração `chat.plugins.marketplaces` tem escopo de aplicação no VS Code, então não pode ser definida por workspace. O CLI escreve automaticamente no seu `settings.json` de nível de usuário: @@ -61,27 +60,13 @@ archgate init --editor vscode --install-plugin ### Arquivos gerados -O comando cria ou atualiza os seguintes arquivos: +O comando cria ou atualiza o seguinte: -| Arquivo | Escopo | Propósito | -| -------------------------- | --------- | ------------------------------------------------------------------- | -| `.vscode/mcp.json` | Workspace | Configuração do servidor MCP para que o VS Code acesse os seus ADRs | -| `settings.json` do usuário | Usuário | `chat.plugins.marketplaces` com a URL autenticada | +| Arquivo | Escopo | Propósito | +| -------------------------- | ------- | ------------------------------------------------- | +| `settings.json` do usuário | Usuário | `chat.plugins.marketplaces` com a URL autenticada | -Se `.vscode/mcp.json` já existir, o Archgate mescla sua configuração de forma aditiva -- entradas de servidores existentes são preservadas. O arquivo de configurações de usuário também é mesclado de forma aditiva -- configurações existentes nunca são sobrescritas. - -A configuração MCP do workspace (`.vscode/mcp.json`): - -```json -{ - "servers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` +O arquivo de configurações de usuário é mesclado de forma aditiva -- configurações existentes nunca são sobrescritas. Os marketplaces padrão do VS Code (`github/copilot-plugins`, `github/awesome-copilot`) são preservados quando a chave é definida pela primeira vez. A configuração do marketplace no nível de usuário (adicionada ao seu `settings.json`): @@ -99,13 +84,20 @@ Se preferir não deixar o CLI modificar suas configurações de usuário, você ## O que o plugin oferece -O plugin adiciona skills baseadas em papéis ao agente de IA do VS Code. Cada skill encapsula uma parte específica do fluxo de governança, garantindo que os agentes sigam o mesmo processo todas as vezes. +O plugin adiciona um agente e skills baseadas em papéis ao VS Code. O agente orquestra o fluxo de governança, invocando skills conforme necessário. + +### Agente -### Skills incluídas +| Agente | Propósito | +| -------------------- | ------------------------------------------------------------------------------ | +| `archgate:developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | + +O agente `archgate:developer` é definido como agente padrão via as configurações do plugin. Ele orquestra as skills abaixo automaticamente como parte do seu fluxo. + +### Skills | Skill | Propósito | | -------------------------- | ------------------------------------------------------------------------------------------ | -| `archgate:developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | | `archgate:architect` | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | | `archgate:quality-manager` | 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 | @@ -128,7 +120,7 @@ O plugin segue um fluxo estruturado para cada tarefa de codificação: ### 1. Ler os ADRs aplicáveis -Quando o desenvolvedor atribui uma tarefa de codificação, o agente lê todos os ADRs que se aplicam aos arquivos sendo alterados. O servidor MCP fornece um resumo condensado com as seções **Decision** e **Do's and Don'ts** de cada ADR relevante. +Quando o desenvolvedor atribui uma tarefa de codificação, o agente executa `archgate review-context` para ler todos os ADRs que se aplicam aos arquivos sendo alterados. Isso fornece um resumo condensado com as seções **Decision** e **Do's and Don'ts** de cada ADR relevante. ### 2. Escrever código seguindo as restrições dos ADRs @@ -146,20 +138,8 @@ O agente invoca `archgate:architect` para validar a conformidade estrutural com O agente invoca `archgate:quality-manager` para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs. -## Integração com o servidor MCP - -O plugin se comunica com os ADRs do seu projeto por meio do servidor MCP do Archgate. O servidor fornece: - -- **Conteúdo de ADRs** -- texto completo de qualquer ADR, acessível por ID -- **Contexto de revisão** -- resumos condensados de todos os ADRs aplicáveis a um conjunto de arquivos alterados -- **Verificação de regras** -- execução de regras automatizadas com relatório de violações -- **Listagem de ADRs** -- inventário de todos os ADRs do projeto com metadados - -O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. - ## Dicas -- **Faça commit do `.vscode/mcp.json`** para compartilhar a configuração MCP com sua equipe. - **Cada desenvolvedor executa `archgate init --editor vscode`** após `archgate login` para configurar a URL do marketplace no nível de usuário. - **Execute o onboard uma vez por projeto** para gerar seus ADRs iniciais a partir do seu codebase real. - **Mantenha os arquivos de regras dos ADRs atualizados** -- o agente aplica o que as regras verificam. diff --git a/docs/src/content/docs/pt-br/reference/mcp-tools.mdx b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx index b02b6099..8f6fa61d 100644 --- a/docs/src/content/docs/pt-br/reference/mcp-tools.mdx +++ b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx @@ -222,5 +222,5 @@ Solicitar `adr://ARCH-001` retorna o conteúdo markdown completo do arquivo ADR Se o ADR solicitado não for encontrado, o recurso retorna uma mensagem em texto simples: `ADR ARCH-001 not found`. :::tip[Pule chamadas MCP manuais com plugins de editor] -Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) chamam essas ferramentas MCP automaticamente como parte de um fluxo de trabalho estruturado de governança. Seu agente lê ADRs, valida conformidade e captura aprendizados sem você invocar nenhuma ferramenta manualmente. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +Os plugins de editor para [Claude Code](/pt-br/guides/claude-code-plugin/) e [Cursor](/pt-br/guides/cursor-integration/) automatizam o fluxo de governança usando comandos CLI diretamente (não via MCP). Seu agente lê ADRs, valida conformidade e captura aprendizados sem você invocar nenhuma ferramenta manualmente. [Cadastre-se para acesso beta](https://plugins.archgate.dev). ::: diff --git a/docs/src/content/docs/reference/mcp-tools.mdx b/docs/src/content/docs/reference/mcp-tools.mdx index a26dcfc5..c09e3176 100644 --- a/docs/src/content/docs/reference/mcp-tools.mdx +++ b/docs/src/content/docs/reference/mcp-tools.mdx @@ -222,5 +222,5 @@ Requesting `adr://ARCH-001` returns the full markdown content of the ARCH-001 AD If the requested ADR is not found, the resource returns a plain text message: `ADR ARCH-001 not found`. :::tip[Skip manual MCP calls with editor plugins] -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) call these MCP tools automatically as part of a structured governance workflow. Your agent reads ADRs, validates compliance, and captures learnings without you invoking any tools manually. [Sign up for beta access](https://plugins.archgate.dev). +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) automate the governance workflow using CLI commands directly (not via MCP). Your agent reads ADRs, validates compliance, and captures learnings without you invoking any tools manually. [Sign up for beta access](https://plugins.archgate.dev). ::: From ad565cbd6fdd0310359c9d97f8953b9c800c6505 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Mon, 16 Mar 2026 01:15:02 +0100 Subject: [PATCH 2/2] fix(docs): remove all MCP server documentation and references The archgate mcp command no longer exists in the CLI. Remove: - MCP Server guide (EN + PT-BR) - MCP Tools reference (EN + PT-BR) - archgate mcp section from CLI commands reference (EN + PT-BR) - Sidebar entries for both pages - All remaining MCP cross-references in index, domains, vscode-plugin, cursor-integration, writing-adrs, and cli-commands pages Co-Authored-By: Claude Opus 4.6 --- docs/astro.config.mjs | 2 - docs/src/content/docs/concepts/domains.mdx | 2 +- .../docs/guides/cursor-integration.mdx | 8 +- docs/src/content/docs/guides/mcp-server.mdx | 127 ---------- .../src/content/docs/guides/vscode-plugin.mdx | 5 +- docs/src/content/docs/guides/writing-adrs.mdx | 2 +- docs/src/content/docs/index.mdx | 5 +- .../content/docs/pt-br/concepts/domains.mdx | 2 +- .../content/docs/pt-br/guides/mcp-server.mdx | 127 ---------- .../docs/pt-br/guides/writing-adrs.mdx | 2 +- docs/src/content/docs/pt-br/index.mdx | 6 +- .../docs/pt-br/reference/cli-commands.mdx | 33 +-- .../docs/pt-br/reference/mcp-tools.mdx | 226 ------------------ .../content/docs/reference/cli-commands.mdx | 33 +-- docs/src/content/docs/reference/mcp-tools.mdx | 226 ------------------ 15 files changed, 18 insertions(+), 788 deletions(-) delete mode 100644 docs/src/content/docs/guides/mcp-server.mdx delete mode 100644 docs/src/content/docs/pt-br/guides/mcp-server.mdx delete mode 100644 docs/src/content/docs/pt-br/reference/mcp-tools.mdx delete mode 100644 docs/src/content/docs/reference/mcp-tools.mdx diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 14ee2c02..3f580ba0 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -232,7 +232,6 @@ export default defineConfig({ label: "Cursor Integration", slug: "guides/cursor-integration", }, - { label: "MCP Server", slug: "guides/mcp-server" }, { label: "Pre-commit Hooks", slug: "guides/pre-commit-hooks", @@ -243,7 +242,6 @@ export default defineConfig({ label: "Reference", items: [ { label: "CLI Commands", slug: "reference/cli-commands" }, - { label: "MCP Tools", slug: "reference/mcp-tools" }, { label: "Rule API", slug: "reference/rule-api" }, { label: "ADR Schema", slug: "reference/adr-schema" }, ], diff --git a/docs/src/content/docs/concepts/domains.mdx b/docs/src/content/docs/concepts/domains.mdx index a53a01e5..e6f698de 100644 --- a/docs/src/content/docs/concepts/domains.mdx +++ b/docs/src/content/docs/concepts/domains.mdx @@ -45,7 +45,7 @@ This is useful in large projects where dozens of ADRs span multiple concerns. Fi ### AI Agent Context -The MCP server's `review_context` tool groups changed files by domain when providing context to AI agents. When an agent is about to write code, it receives only the ADR briefings relevant to the domains its changes touch, rather than the full set of all ADRs. This scoping reduces noise and helps agents focus on the constraints that actually apply. +The `archgate review-context` command groups changed files by domain when providing context to AI agents. When an agent is about to write code, it receives only the ADR briefings relevant to the domains its changes touch, rather than the full set of all ADRs. This scoping reduces noise and helps agents focus on the constraints that actually apply. ### Scoped Validation diff --git a/docs/src/content/docs/guides/cursor-integration.mdx b/docs/src/content/docs/guides/cursor-integration.mdx index b3d9f95d..9a4bb5ed 100644 --- a/docs/src/content/docs/guides/cursor-integration.mdx +++ b/docs/src/content/docs/guides/cursor-integration.mdx @@ -132,12 +132,12 @@ The governance rule in `.cursor/rules/archgate-governance.mdc` uses `alwaysApply ## Session transcript access -The `cursor_session_context` MCP tool reads Cursor agent session transcripts from disk. This allows skills to access the history of the current conversation, which is useful for recovering context that may have been compacted or truncated. +The `archgate session-context cursor` command reads Cursor agent session transcripts from disk. This allows skills to access the history of the current conversation, which is useful for recovering context that may have been compacted or truncated. -The tool accepts two optional parameters: +The command accepts two optional flags: -- `maxEntries` -- Maximum number of entries to return (default: 200, most recent entries). -- `sessionId` -- A specific session UUID to read. If omitted, the most recent session is used. +- `--max-entries ` -- Maximum number of entries to return (default: 200, most recent entries). +- `--session-id ` -- A specific session UUID to read. If omitted, the most recent session is used. ## Tips for effective usage diff --git a/docs/src/content/docs/guides/mcp-server.mdx b/docs/src/content/docs/guides/mcp-server.mdx deleted file mode 100644 index c5001ed0..00000000 --- a/docs/src/content/docs/guides/mcp-server.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: MCP Server -description: Use the Archgate MCP server to give AI agents live access to your Architecture Decision Records. Supports Claude, Cursor, and any MCP-compatible client. ---- - -The Archgate MCP server exposes your project's ADRs and compliance checks to AI agents over the [Model Context Protocol](https://modelcontextprotocol.io/). Any MCP-compatible client -- Claude Code, Cursor, or custom tooling -- can connect to it. - -## Starting the server - -The server uses stdio transport. Start it with: - -```bash -archgate mcp -``` - -You do not typically run this command manually. Instead, configure your AI tool to launch it automatically (see below). - -## Configuring in Claude Code - -Add the following to your project's `.mcp.json` file (create it if it does not exist): - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` - -Claude Code reads this file on startup and connects to the Archgate MCP server automatically. - -:::note[Editor plugins use CLI commands directly] -The Archgate editor plugins (Claude Code, Cursor, VS Code, Copilot CLI) do **not** use the MCP server. They invoke Archgate CLI commands directly (e.g., `archgate review-context`, `archgate check`). The MCP server is for custom integrations or MCP-compatible clients that are not using the editor plugins. -::: - -## Configuring in Cursor - -Add the same configuration to your project's `.cursor/mcp.json` file. See the [Cursor Integration](/guides/cursor-integration/) guide for details. - -## Available MCP tools - -The server registers five tools that AI agents can call. - -### `check` - -Run ADR compliance checks against the codebase. - -| Parameter | Type | Description | -| --------- | ---------- | ------------------------------- | -| `adrId` | `string?` | Only check a specific ADR by ID | -| `staged` | `boolean?` | Only check git-staged files | - -Returns a JSON summary with pass/fail status, violation counts, and detailed results including file paths and line numbers. - -### `list_adrs` - -List all ADRs in the project with metadata. - -| Parameter | Type | Description | -| --------- | --------- | --------------------------------------------------------------------------- | -| `domain` | `string?` | Filter by domain (`backend`, `frontend`, `data`, `architecture`, `general`) | - -Returns an array of objects with `id`, `title`, `domain`, and `rules` fields for each ADR. - -### `review_context` - -Get changed files grouped by domain with applicable ADR briefings. This is the recommended starting point for an agent beginning a task -- it combines file change detection, domain grouping, and ADR summarization into a single call. - -| Parameter | Type | Description | -| ----------- | ---------- | -------------------------------------------------------------------- | -| `staged` | `boolean?` | When true, only include git-staged files. Default: all changed files | -| `runChecks` | `boolean?` | When true, run compliance checks and include results | -| `domain` | `string?` | Filter results to a single domain | - -Returns briefings containing only the Decision and Do's/Don'ts sections of each applicable ADR, keeping the response concise. - -### `claude_code_session_context` - -Read the current Claude Code session transcript for the project. Returns filtered entries (user and assistant messages) from the most recent session JSONL file. - -| Parameter | Type | Description | -| ------------ | --------- | -------------------------------------------------------------- | -| `maxEntries` | `number?` | Maximum relevant entries to return (default: 200, most recent) | - -### `cursor_session_context` - -Read Cursor agent session transcripts for the project. Returns filtered entries from Cursor's agent-transcripts JSONL files. - -| Parameter | Type | Description | -| ------------ | --------- | ------------------------------------------------------------------------ | -| `maxEntries` | `number?` | Maximum relevant entries to return (default: 200, most recent) | -| `sessionId` | `string?` | Specific session UUID to read. If omitted, reads the most recent session | - -## Available MCP resources - -### `adr://\{id\}` - -Read the full content of an ADR by ID. Replace the `id` placeholder with the ADR identifier (for example, `adr://ARCH-001`). - -Returns the complete ADR markdown including frontmatter, rationale, decision, do's and don'ts, consequences, compliance, and references sections. - -## No-project behavior - -If the MCP server starts in a directory without an `.archgate/` directory, all tools remain available but return guidance instructing the agent to run `archgate init` to initialize governance. The server does not crash or refuse to start -- it provides actionable feedback so the agent can bootstrap the project. - -## Example usage flow - -A typical AI agent session using the MCP server follows this pattern: - -1. **Agent calls `review_context`** with `runChecks: false` to get a condensed briefing of all ADRs that apply to the current set of changed files. - -2. **Agent reads the briefings** and identifies which architectural constraints apply to its task. - -3. **Agent reads a full ADR** via `adr://ARCH-002` (for example) when it needs the complete rationale or implementation examples beyond the condensed briefing. - -4. **Agent writes code** following the constraints from the applicable ADRs. - -5. **Agent calls `check`** with `staged: true` to validate compliance. If violations are found, the response includes file paths and line numbers so the agent can fix them. - -6. **Agent iterates** until `check` reports zero violations. - -:::tip[Automate this entire workflow] -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) automate this flow end-to-end using CLI commands directly. The agent reads ADRs, writes compliant code, runs checks, validates with the architect skill, and captures learnings -- all without manual intervention. [Sign up for beta access](https://plugins.archgate.dev). -::: diff --git a/docs/src/content/docs/guides/vscode-plugin.mdx b/docs/src/content/docs/guides/vscode-plugin.mdx index af522aad..d436bf50 100644 --- a/docs/src/content/docs/guides/vscode-plugin.mdx +++ b/docs/src/content/docs/guides/vscode-plugin.mdx @@ -42,8 +42,7 @@ archgate init --editor vscode If you are already logged in, this command: 1. Creates the `.archgate/` governance directory (ADRs, lint rules) -2. Creates `.vscode/mcp.json` with the Archgate MCP server configuration -3. Adds the authenticated marketplace URL to your VS Code **user settings** +2. Adds the authenticated marketplace URL to your VS Code **user settings** The `chat.plugins.marketplaces` setting is application-scoped in VS Code, so it cannot be set per-workspace. The CLI automatically writes it to your user-level `settings.json`: @@ -121,7 +120,7 @@ The plugin follows a structured workflow for every coding task: ### 1. Read applicable ADRs -When the developer gives a coding task, the agent reads all ADRs that apply to the files being changed. The MCP server provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR. +When the developer gives a coding task, the agent runs `archgate review-context` to read all ADRs that apply to the files being changed. This provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR. ### 2. Write code following ADR constraints diff --git a/docs/src/content/docs/guides/writing-adrs.mdx b/docs/src/content/docs/guides/writing-adrs.mdx index 8178b8fc..e4a68298 100644 --- a/docs/src/content/docs/guides/writing-adrs.mdx +++ b/docs/src/content/docs/guides/writing-adrs.mdx @@ -114,7 +114,7 @@ Good context sections include: ## Context The CLI needs a consistent pattern for defining and registering commands. As the -command surface grows (init, check, adr, mcp, upgrade, clean), the registration +command surface grows (init, check, adr, login, upgrade, clean), the registration mechanism must scale without introducing hidden coupling or making the dependency graph opaque. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 7a51f223..e578b631 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -47,8 +47,9 @@ When you run `archgate check`, the CLI loads every ADR that has `rules: true` in that respects exit codes. - The MCP server gives AI agents live access to your ADRs. They read decisions - before writing code and validate after. No copy-pasting rules into prompts. + Editor plugins give AI agents direct access to your ADRs via CLI commands. + They read decisions before writing code and validate after. No copy-pasting + rules into prompts. Archgate governs its own development. The same tool that checks your code diff --git a/docs/src/content/docs/pt-br/concepts/domains.mdx b/docs/src/content/docs/pt-br/concepts/domains.mdx index a9ccd31f..e25b5652 100644 --- a/docs/src/content/docs/pt-br/concepts/domains.mdx +++ b/docs/src/content/docs/pt-br/concepts/domains.mdx @@ -45,7 +45,7 @@ Isso é útil em projetos grandes onde dezenas de ADRs abrangem múltiplas preoc ### Contexto para Agentes de IA -A ferramenta `review_context` do servidor MCP agrupa arquivos alterados por domínio ao fornecer contexto para agentes de IA. Quando um agente está prestes a escrever código, ele recebe apenas os resumos de ADR relevantes para os domínios que suas alterações afetam, em vez do conjunto completo de todos os ADRs. Esse escopo reduz o ruído e ajuda os agentes a focar nas restrições que realmente se aplicam. +O comando `archgate review-context` agrupa arquivos alterados por domínio ao fornecer contexto para agentes de IA. Quando um agente está prestes a escrever código, ele recebe apenas os resumos de ADR relevantes para os domínios que suas alterações afetam, em vez do conjunto completo de todos os ADRs. Esse escopo reduz o ruído e ajuda os agentes a focar nas restrições que realmente se aplicam. ### Validação com Escopo diff --git a/docs/src/content/docs/pt-br/guides/mcp-server.mdx b/docs/src/content/docs/pt-br/guides/mcp-server.mdx deleted file mode 100644 index 8ae0b529..00000000 --- a/docs/src/content/docs/pt-br/guides/mcp-server.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Servidor MCP -description: Use o servidor MCP do Archgate para dar aos agentes de IA acesso aos seus Architecture Decision Records. Compatível com Claude, Cursor e qualquer cliente MCP. ---- - -O servidor MCP do Archgate expõe os ADRs e verificações de conformidade do seu projeto para agentes de IA por meio do [Model Context Protocol](https://modelcontextprotocol.io/). Qualquer cliente compatível com MCP -- Claude Code, Cursor ou ferramentas customizadas -- pode se conectar a ele. - -## Iniciando o servidor - -O servidor usa transporte stdio. Inicie-o com: - -```bash -archgate mcp -``` - -Normalmente você não executa esse comando manualmente. Em vez disso, configure sua ferramenta de IA para iniciá-lo automaticamente (veja abaixo). - -## Configurando no Claude Code - -Adicione o seguinte ao arquivo `.mcp.json` do seu projeto (crie-o se não existir): - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` - -O Claude Code lê esse arquivo na inicialização e se conecta ao servidor MCP do Archgate automaticamente. - -:::note[Plugins de editor usam comandos CLI diretamente] -Os plugins de editor do Archgate (Claude Code, Cursor, VS Code, Copilot CLI) **não** usam o servidor MCP. Eles invocam comandos do CLI Archgate diretamente (ex.: `archgate review-context`, `archgate check`). O servidor MCP é para integrações customizadas ou clientes compatíveis com MCP que não usam os plugins de editor. -::: - -## Configurando no Cursor - -Adicione a mesma configuração ao arquivo `.cursor/mcp.json` do seu projeto. Consulte o guia de [Integração com Cursor](/pt-br/guides/cursor-integration/) para mais detalhes. - -## Ferramentas MCP disponíveis - -O servidor registra cinco ferramentas que agentes de IA podem chamar. - -### `check` - -Executa verificações de conformidade com ADRs no codebase. - -| Parâmetro | Tipo | Descrição | -| --------- | ---------- | ----------------------------------------- | -| `adrId` | `string?` | Verificar apenas um ADR específico por ID | -| `staged` | `boolean?` | Verificar apenas arquivos staged no git | - -Retorna um resumo JSON com status de aprovação/reprovação, contagem de violações e resultados detalhados incluindo caminhos de arquivo e números de linha. - -### `list_adrs` - -Lista todos os ADRs do projeto com metadados. - -| Parâmetro | Tipo | Descrição | -| --------- | --------- | ------------------------------------------------------------------------------ | -| `domain` | `string?` | Filtrar por domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | - -Retorna um array de objetos com os campos `id`, `title`, `domain` e `rules` para cada ADR. - -### `review_context` - -Obtém arquivos alterados agrupados por domínio com resumos dos ADRs aplicáveis. Este é o ponto de partida recomendado para um agente iniciando uma tarefa -- ele combina detecção de alterações em arquivos, agrupamento por domínio e sumarização de ADRs em uma única chamada. - -| Parâmetro | Tipo | Descrição | -| ----------- | ---------- | -------------------------------------------------------------------------------------- | -| `staged` | `boolean?` | Quando true, inclui apenas arquivos staged no git. Padrão: todos os arquivos alterados | -| `runChecks` | `boolean?` | Quando true, executa verificações de conformidade e inclui os resultados | -| `domain` | `string?` | Filtra os resultados para um único domínio | - -Retorna resumos contendo apenas as seções Decision e Do's/Don'ts de cada ADR aplicável, mantendo a resposta concisa. - -### `claude_code_session_context` - -Lê a transcrição da sessão atual do Claude Code para o projeto. Retorna entradas filtradas (mensagens do usuário e do assistente) do arquivo JSONL da sessão mais recente. - -| Parâmetro | Tipo | Descrição | -| ------------ | --------- | ---------------------------------------------------------------------------- | -| `maxEntries` | `number?` | Número máximo de entradas relevantes a retornar (padrão: 200, mais recentes) | - -### `cursor_session_context` - -Lê transcrições de sessão do agente Cursor para o projeto. Retorna entradas filtradas dos arquivos JSONL de agent-transcripts do Cursor. - -| Parâmetro | Tipo | Descrição | -| ------------ | --------- | ---------------------------------------------------------------------------- | -| `maxEntries` | `number?` | Número máximo de entradas relevantes a retornar (padrão: 200, mais recentes) | -| `sessionId` | `string?` | UUID de sessão específico para ler. Se omitido, lê a sessão mais recente | - -## Recursos MCP disponíveis - -### `adr://\{id\}` - -Lê o conteúdo completo de um ADR por ID. Substitua o placeholder `id` pelo identificador do ADR (por exemplo, `adr://ARCH-001`). - -Retorna o ADR completo em markdown incluindo frontmatter, justificativa, decisão, do's and don'ts, consequências, conformidade e seções de referências. - -## Comportamento sem projeto - -Se o servidor MCP iniciar em um diretório sem um diretório `.archgate/`, todas as ferramentas permanecem disponíveis mas retornam orientações instruindo o agente a executar `archgate init` para inicializar a governança. O servidor não trava nem se recusa a iniciar -- ele fornece feedback acionável para que o agente possa configurar o projeto. - -## Exemplo de fluxo de uso - -Uma sessão típica de agente de IA usando o servidor MCP segue este padrão: - -1. **O agente chama `review_context`** com `runChecks: false` para obter um resumo condensado de todos os ADRs que se aplicam ao conjunto atual de arquivos alterados. - -2. **O agente lê os resumos** e identifica quais restrições arquiteturais se aplicam à sua tarefa. - -3. **O agente lê um ADR completo** via `adr://ARCH-002` (por exemplo) quando precisa da justificativa completa ou exemplos de implementação além do resumo condensado. - -4. **O agente escreve código** seguindo as restrições dos ADRs aplicáveis. - -5. **O agente chama `check`** com `staged: true` para validar a conformidade. Se violações forem encontradas, a resposta inclui caminhos de arquivo e números de linha para que o agente possa corrigi-las. - -6. **O agente itera** até que `check` reporte zero violações. - -:::tip[Automatize todo esse fluxo] -Os plugins de editor para [Claude Code](/pt-br/guides/claude-code-plugin/) e [Cursor](/pt-br/guides/cursor-integration/) automatizam esse fluxo de ponta a ponta usando comandos CLI diretamente. O agente lê ADRs, escreve código em conformidade, executa verificações, valida com a skill de arquiteto e captura aprendizados -- tudo sem intervenção manual. [Cadastre-se para acesso beta](https://plugins.archgate.dev). -::: diff --git a/docs/src/content/docs/pt-br/guides/writing-adrs.mdx b/docs/src/content/docs/pt-br/guides/writing-adrs.mdx index e2f467e6..dc0b7a92 100644 --- a/docs/src/content/docs/pt-br/guides/writing-adrs.mdx +++ b/docs/src/content/docs/pt-br/guides/writing-adrs.mdx @@ -114,7 +114,7 @@ Boas seções de contexto incluem: ## Context The CLI needs a consistent pattern for defining and registering commands. As the -command surface grows (init, check, adr, mcp, upgrade, clean), the registration +command surface grows (init, check, adr, login, upgrade, clean), the registration mechanism must scale without introducing hidden coupling or making the dependency graph opaque. diff --git a/docs/src/content/docs/pt-br/index.mdx b/docs/src/content/docs/pt-br/index.mdx index 15cc909b..dce25fe3 100644 --- a/docs/src/content/docs/pt-br/index.mdx +++ b/docs/src/content/docs/pt-br/index.mdx @@ -47,9 +47,9 @@ Quando você executa `archgate check`, a CLI carrega cada ADR que possui `rules: qualquer sistema de CI que respeite códigos de saída. - O servidor MCP dá aos agentes de IA acesso em tempo real aos seus ADRs. Eles - leem as decisões antes de escrever código e validam depois. Sem copiar e - colar regras nos prompts. + Plugins de editor dão aos agentes de IA acesso direto aos seus ADRs via + comandos CLI. Eles leem as decisões antes de escrever código e validam + depois. Sem copiar e colar regras nos prompts. O Archgate governa seu próprio desenvolvimento. A mesma ferramenta que diff --git a/docs/src/content/docs/pt-br/reference/cli-commands.mdx b/docs/src/content/docs/pt-br/reference/cli-commands.mdx index 6b763e27..20c80c73 100644 --- a/docs/src/content/docs/pt-br/reference/cli-commands.mdx +++ b/docs/src/content/docs/pt-br/reference/cli-commands.mdx @@ -29,7 +29,7 @@ archgate login Inicia um GitHub Device Flow (OAuth). A CLI exibe um código de uso único e uma URL. Abra a URL no seu navegador, insira o código e autorize o Archgate GitHub OAuth App. Após a autorização, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em `~/.archgate/credentials`. -As credenciais são necessárias para instalar plugins de editor via `archgate init --install-plugin`. A CLI em si (check, init, mcp, etc.) funciona sem login. +As credenciais são necessárias para instalar plugins de editor via `archgate init --install-plugin`. A CLI em si (check, init, etc.) funciona sem login. :::tip[Plugin em beta] Os plugins de editor estão atualmente em beta. Cadastre-se em [plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. @@ -385,37 +385,6 @@ archgate adr update \ --- -## archgate mcp - -Inicia o servidor MCP para integração com agentes de IA. - -```bash -archgate mcp -``` - -Executa um servidor MCP usando transporte stdio. O servidor expõe ferramentas para verificar conformidade com ADRs, listar ADRs e obter contexto de revisão. Consulte a referência de [Ferramentas MCP](/pt-br/reference/mcp-tools/) para a lista completa de ferramentas e recursos disponíveis. - -O servidor inicia mesmo quando nenhum diretório `.archgate/` é encontrado. Nesse caso, as ferramentas retornam orientações direcionando o agente a inicializar a governança primeiro. - -### Configuração - -Adicione a configuração MCP do seu projeto (`.mcp.json` na raiz do projeto): - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` - -Executar `archgate init` cria essa configuração automaticamente para o seu editor. - ---- - ## archgate upgrade Atualiza o Archgate para a versão mais recente via npm. diff --git a/docs/src/content/docs/pt-br/reference/mcp-tools.mdx b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx deleted file mode 100644 index 8f6fa61d..00000000 --- a/docs/src/content/docs/pt-br/reference/mcp-tools.mdx +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Ferramentas MCP -description: Referência da API de todas as ferramentas MCP expostas pelo servidor Archgate. Inclui adr_list, adr_read, check_compliance e review_context. ---- - -O servidor MCP do Archgate expõe ferramentas e recursos que agentes de IA utilizam para ler ADRs, validar código contra regras e acessar o contexto de revisão. Inicie o servidor com `archgate mcp`. - -## Ferramentas - -### check - -Executa verificações de conformidade com ADRs no codebase. - -**Parâmetros:** - -| Nome | Tipo | Obrigatório | Descrição | -| -------- | ------- | ----------- | ----------------------------------------- | -| `adrId` | string | Não | Verificar apenas um ADR específico por ID | -| `staged` | boolean | Não | Verificar apenas arquivos no git stage | - -**Retorna** um objeto JSON com os resultados da verificação: - -```json -{ - "pass": false, - "total": 4, - "passed": 3, - "failed": 1, - "warnings": 0, - "errors": 1, - "infos": 0, - "ruleErrors": 0, - "truncated": false, - "results": [ - { - "adrId": "ARCH-001", - "ruleId": "register-function-export", - "description": "Command file must export a register*Command function", - "status": "fail", - "totalViolations": 1, - "shownViolations": 1, - "violations": [ - { - "message": "Command file must export a register*Command function", - "file": "src/commands/broken.ts", - "severity": "error" - } - ], - "durationMs": 12 - } - ], - "durationMs": 42 -} -``` - -Quando nenhuma regra é encontrada, retorna `{ "pass": true, "total": 0, "results": [], "message": "No rules to check" }`. - -As violações são limitadas a 20 por regra para manter as respostas concisas. Quando uma regra tem mais violações do que o limite, `totalViolations` reflete a contagem real enquanto `shownViolations` e o array `violations` incluem apenas as 20 primeiras. O campo `truncated` no nível superior é definido como `true` quando alguma regra foi limitada. - ---- - -### list_adrs - -Lista todos os ADRs do projeto com seus metadados. - -**Parâmetros:** - -| Nome | Tipo | Obrigatório | Descrição | -| -------- | ------ | ----------- | ------------------------------------------------------------------------------ | -| `domain` | string | Não | Filtrar por domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | - -**Retorna** um array JSON de objetos ADR: - -```json -[ - { - "id": "ARCH-001", - "title": "Command Structure", - "domain": "architecture", - "rules": true - }, - { - "id": "BE-001", - "title": "API Response Envelope", - "domain": "backend", - "rules": true - } -] -``` - ---- - -### review_context - -Obtém arquivos alterados agrupados por domínio com resumos dos ADRs aplicáveis. Esta é a ferramenta principal que os agentes usam antes de escrever código -- ela fornece uma visão condensada de todas as decisões e restrições de ADR relevantes sem precisar ler cada arquivo de ADR individualmente. - -**Parâmetros:** - -| Nome | Tipo | Obrigatório | Descrição | -| ----------- | ------- | ----------- | -------------------------------------------------------------------------------------------- | -| `staged` | boolean | Não | Quando `true`, inclui apenas arquivos no git stage. Padrão: `false` (todos os alterados). | -| `runChecks` | boolean | Não | Quando `true`, executa verificações de conformidade e inclui os resultados. Padrão: `false`. | -| `domain` | string | Não | Filtrar por um único domínio (`backend`, `frontend`, `data`, `architecture`, `general`). | - -**Retorna** um objeto JSON com resumos agrupados por domínio: - -```json -{ - "allChangedFiles": ["src/commands/init.ts", "src/helpers/log.ts"], - "truncatedFiles": false, - "domains": [ - { - "domain": "architecture", - "changedFiles": ["src/commands/init.ts", "src/helpers/log.ts"], - "adrs": [ - { - "id": "ARCH-001", - "title": "Command Structure", - "domain": "architecture", - "files": ["src/commands/**/*.ts"], - "rules": true, - "decision": "Commands export register*Command(program)...", - "dosAndDonts": "### Do's\n- Export a register function..." - } - ] - } - ], - "checkSummary": null -} -``` - -Cada grupo de domínio inclui os arquivos alterados que correspondem aos seus ADRs, e resumos condensados dos ADRs com apenas as seções **Decision** e **Do's and Don'ts**. - -Quando `runChecks` é `true`, `checkSummary` contém os resultados completos da verificação (mesmo formato da resposta da ferramenta `check`). Quando `false` ou omitido, `checkSummary` é `null`. - ---- - -### claude_code_session_context - -Lê a transcrição da sessão atual do Claude Code para o projeto. Útil para recuperar contexto da sessão que pode ter sido compactado da conversa. - -**Parâmetros:** - -| Nome | Tipo | Obrigatório | Padrão | Descrição | -| ------------ | ------ | ----------- | ------ | ----------------------------------------------------------------------------------- | -| `maxEntries` | number | Não | 200 | Número máximo de entradas relevantes a retornar. Retorna as entradas mais recentes. | - -**Retorna** um objeto JSON com metadados da sessão e transcrição filtrada: - -```json -{ - "sessionFile": "abc123.jsonl", - "totalEntries": 450, - "relevantEntries": 180, - "transcript": [ - { - "type": "user", - "role": "user", - "contentPreview": "Add a dark mode toggle..." - }, - { - "type": "assistant", - "role": "assistant", - "contentPreview": "[tool_use: edit_file] | Updated styles..." - } - ] -} -``` - -Apenas tipos de mensagem `user` e `assistant` são incluídos. As prévias de conteúdo são truncadas para 500 caracteres para mensagens de usuário e 300 caracteres por bloco de conteúdo para mensagens do assistente. - ---- - -### cursor_session_context - -Lê as transcrições de sessão do agente Cursor para o projeto. Funciona da mesma forma que `claude_code_session_context`, mas lê do diretório `agent-transcripts` do Cursor. - -**Parâmetros:** - -| Nome | Tipo | Obrigatório | Padrão | Descrição | -| ------------ | ------ | ----------- | ------ | ------------------------------------------------------------------------- | -| `maxEntries` | number | Não | 200 | Número máximo de entradas relevantes a retornar. | -| `sessionId` | string | Não | -- | UUID de sessão específico para ler. Se omitido, lê a sessão mais recente. | - -**Retorna** um objeto JSON com metadados da sessão e transcrição filtrada: - -```json -{ - "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "sessionFile": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.jsonl", - "totalEntries": 320, - "relevantEntries": 140, - "transcript": [ - { - "role": "user", - "contentPreview": "Fix the build error..." - }, - { - "role": "assistant", - "contentPreview": "The error is caused by..." - } - ] -} -``` - -Se o `sessionId` especificado não for encontrado, a resposta inclui uma lista de IDs de sessão disponíveis. - ---- - -## Recursos - -### adr://\{id\} - -Lê o conteúdo completo de um ADR pelo seu ID. Retorna o markdown completo incluindo frontmatter YAML e corpo. - -**Formato da URI:** `adr://\{id\}` onde `\{id\}` é o identificador do ADR (ex.: `ARCH-001`, `BE-003`). - -**Exemplo:** - -Solicitar `adr://ARCH-001` retorna o conteúdo markdown completo do arquivo ADR ARCH-001 com tipo MIME `text/markdown`. - -Se o ADR solicitado não for encontrado, o recurso retorna uma mensagem em texto simples: `ADR ARCH-001 not found`. - -:::tip[Pule chamadas MCP manuais com plugins de editor] -Os plugins de editor para [Claude Code](/pt-br/guides/claude-code-plugin/) e [Cursor](/pt-br/guides/cursor-integration/) automatizam o fluxo de governança usando comandos CLI diretamente (não via MCP). Seu agente lê ADRs, valida conformidade e captura aprendizados sem você invocar nenhuma ferramenta manualmente. [Cadastre-se para acesso beta](https://plugins.archgate.dev). -::: diff --git a/docs/src/content/docs/reference/cli-commands.mdx b/docs/src/content/docs/reference/cli-commands.mdx index 4392713c..29a7665e 100644 --- a/docs/src/content/docs/reference/cli-commands.mdx +++ b/docs/src/content/docs/reference/cli-commands.mdx @@ -29,7 +29,7 @@ archgate login Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores both in `~/.archgate/credentials`. -Credentials are required to install editor plugins via `archgate init --install-plugin`. The CLI itself (check, init, mcp, etc.) works without login. +Credentials are required to install editor plugins via `archgate init --install-plugin`. The CLI itself (check, init, etc.) works without login. :::tip[Plugin beta] Editor plugins are currently in beta. Sign up at [plugins.archgate.dev](https://plugins.archgate.dev) to get access. @@ -385,37 +385,6 @@ archgate adr update \ --- -## archgate mcp - -Start the MCP server for AI agent integration. - -```bash -archgate mcp -``` - -Launches an MCP server using stdio transport. The server exposes tools for checking ADR compliance, listing ADRs, and retrieving review context. See the [MCP Tools](/reference/mcp-tools/) reference for the full list of available tools and resources. - -The server starts even when no `.archgate/` directory is found. In that case, tools return guidance directing the agent to initialize governance first. - -### Configuration - -Add to your project's MCP configuration (`.mcp.json` at the project root): - -```json -{ - "mcpServers": { - "archgate": { - "command": "archgate", - "args": ["mcp"] - } - } -} -``` - -Running `archgate init` creates this configuration automatically for your editor. - ---- - ## archgate upgrade Upgrade Archgate to the latest version via npm. diff --git a/docs/src/content/docs/reference/mcp-tools.mdx b/docs/src/content/docs/reference/mcp-tools.mdx deleted file mode 100644 index c09e3176..00000000 --- a/docs/src/content/docs/reference/mcp-tools.mdx +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: MCP Tools -description: API reference for all MCP tools and resources exposed by the Archgate server. Includes adr_list, adr_read, check_compliance, and review_context. ---- - -The Archgate MCP server exposes tools and resources that AI coding agents use to read ADRs, validate code against rules, and access review context. Start the server with `archgate mcp`. - -## Tools - -### check - -Run ADR compliance checks against the codebase. - -**Parameters:** - -| Name | Type | Required | Description | -| -------- | ------- | -------- | ------------------------------- | -| `adrId` | string | No | Only check a specific ADR by ID | -| `staged` | boolean | No | Only check git-staged files | - -**Returns** a JSON object with check results: - -```json -{ - "pass": false, - "total": 4, - "passed": 3, - "failed": 1, - "warnings": 0, - "errors": 1, - "infos": 0, - "ruleErrors": 0, - "truncated": false, - "results": [ - { - "adrId": "ARCH-001", - "ruleId": "register-function-export", - "description": "Command file must export a register*Command function", - "status": "fail", - "totalViolations": 1, - "shownViolations": 1, - "violations": [ - { - "message": "Command file must export a register*Command function", - "file": "src/commands/broken.ts", - "severity": "error" - } - ], - "durationMs": 12 - } - ], - "durationMs": 42 -} -``` - -When no rules are found, returns `{ "pass": true, "total": 0, "results": [], "message": "No rules to check" }`. - -Violations are capped at 20 per rule to keep responses concise. When a rule has more violations than the cap, `totalViolations` reflects the true count while `shownViolations` and the `violations` array only include the first 20. The top-level `truncated` field is set to `true` when any rule was capped. - ---- - -### list_adrs - -List all ADRs in the project with their metadata. - -**Parameters:** - -| Name | Type | Required | Description | -| -------- | ------ | -------- | --------------------------------------------------------------------------- | -| `domain` | string | No | Filter by domain (`backend`, `frontend`, `data`, `architecture`, `general`) | - -**Returns** a JSON array of ADR objects: - -```json -[ - { - "id": "ARCH-001", - "title": "Command Structure", - "domain": "architecture", - "rules": true - }, - { - "id": "BE-001", - "title": "API Response Envelope", - "domain": "backend", - "rules": true - } -] -``` - ---- - -### review_context - -Get changed files grouped by domain with applicable ADR briefings. This is the primary tool agents use before writing code -- it provides a condensed view of all relevant ADR decisions and constraints without reading each ADR file individually. - -**Parameters:** - -| Name | Type | Required | Description | -| ----------- | ------- | -------- | ------------------------------------------------------------------------------------- | -| `staged` | boolean | No | When `true`, only include git-staged files. Default: `false` (all changed files). | -| `runChecks` | boolean | No | When `true`, run compliance checks and include results. Default: `false`. | -| `domain` | string | No | Filter to a single domain (`backend`, `frontend`, `data`, `architecture`, `general`). | - -**Returns** a JSON object with domain-grouped briefings: - -```json -{ - "allChangedFiles": ["src/commands/init.ts", "src/helpers/log.ts"], - "truncatedFiles": false, - "domains": [ - { - "domain": "architecture", - "changedFiles": ["src/commands/init.ts", "src/helpers/log.ts"], - "adrs": [ - { - "id": "ARCH-001", - "title": "Command Structure", - "domain": "architecture", - "files": ["src/commands/**/*.ts"], - "rules": true, - "decision": "Commands export register*Command(program)...", - "dosAndDonts": "### Do's\n- Export a register function..." - } - ] - } - ], - "checkSummary": null -} -``` - -Each domain group includes the changed files that match its ADRs, and condensed ADR briefings with only the **Decision** and **Do's and Don'ts** sections. - -When `runChecks` is `true`, `checkSummary` contains the full check results (same format as the `check` tool response). When `false` or omitted, `checkSummary` is `null`. - ---- - -### claude_code_session_context - -Read the current Claude Code session transcript for the project. Useful for recovering session context that may have been compacted from the conversation. - -**Parameters:** - -| Name | Type | Required | Default | Description | -| ------------ | ------ | -------- | ------- | ------------------------------------------------------------------------------ | -| `maxEntries` | number | No | 200 | Maximum number of relevant entries to return. Returns the most recent entries. | - -**Returns** a JSON object with session metadata and filtered transcript: - -```json -{ - "sessionFile": "abc123.jsonl", - "totalEntries": 450, - "relevantEntries": 180, - "transcript": [ - { - "type": "user", - "role": "user", - "contentPreview": "Add a dark mode toggle..." - }, - { - "type": "assistant", - "role": "assistant", - "contentPreview": "[tool_use: edit_file] | Updated styles..." - } - ] -} -``` - -Only `user` and `assistant` message types are included. Content previews are truncated to 500 characters for user messages and 300 characters per content block for assistant messages. - ---- - -### cursor_session_context - -Read Cursor agent session transcripts for the project. Works the same way as `claude_code_session_context` but reads from Cursor's `agent-transcripts` directory. - -**Parameters:** - -| Name | Type | Required | Default | Description | -| ------------ | ------ | -------- | ------- | ------------------------------------------------------------------------- | -| `maxEntries` | number | No | 200 | Maximum number of relevant entries to return. | -| `sessionId` | string | No | -- | Specific session UUID to read. If omitted, reads the most recent session. | - -**Returns** a JSON object with session metadata and filtered transcript: - -```json -{ - "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "sessionFile": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.jsonl", - "totalEntries": 320, - "relevantEntries": 140, - "transcript": [ - { - "role": "user", - "contentPreview": "Fix the build error..." - }, - { - "role": "assistant", - "contentPreview": "The error is caused by..." - } - ] -} -``` - -If the specified `sessionId` is not found, the response includes a list of available session IDs. - ---- - -## Resources - -### adr://\{id\} - -Read the full content of an ADR by its ID. Returns the complete markdown including YAML frontmatter and body. - -**URI format:** `adr://\{id\}` where `\{id\}` is the ADR identifier (e.g., `ARCH-001`, `BE-003`). - -**Example:** - -Requesting `adr://ARCH-001` returns the full markdown content of the ARCH-001 ADR file with MIME type `text/markdown`. - -If the requested ADR is not found, the resource returns a plain text message: `ADR ARCH-001 not found`. - -:::tip[Skip manual MCP calls with editor plugins] -The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) automate the governance workflow using CLI commands directly (not via MCP). Your agent reads ADRs, validates compliance, and captures learnings without you invoking any tools manually. [Sign up for beta access](https://plugins.archgate.dev). -:::