Skip to content

docs: align plugin docs with plugins repo #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhuanbarreto merged 2 commits into from
Mar 16, 2026
Merged

docs: align plugin docs with plugins repo #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8f3eb26
docs: align plugin docs with plugins repo reality
rhuanbarreto Mar 15, 2026
ad565cb
fix(docs): remove all MCP server documentation and references
rhuanbarreto Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions docs/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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" },
],
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/concepts/domains.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
40 changes: 25 additions & 15 deletions docs/src/content/docs/guides/claude-code-plugin.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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)
Expand All @@ -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.

Expand Down Expand Up @@ -105,25 +114,26 @@ 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 <id>`** -- 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` |
| Reviewing a PR for ADR compliance | `archgate:architect` |
| 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.
48 changes: 12 additions & 36 deletions docs/src/content/docs/guides/copilot-cli-plugin.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |
Expand All @@ -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

Expand All @@ -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.
Loading
Loading