diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 6a98cd59..3f960b71 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -28,6 +28,8 @@ jobs: - name: Setup toolchain uses: moonrepo/setup-toolchain@v0 + with: + auto-install: true - name: Install dependencies run: bun install --frozen-lockfile diff --git a/CLAUDE.md b/CLAUDE.md index 2773c18f..0f57a031 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,17 +33,18 @@ bun run commit # conventional commit wizard Entry point: `src/cli.ts` (shebang `#!/usr/bin/env bun`). Commands registered via `register*Command(program)`. -| Command | File | Description | -| --------------- | ------------------------ | -------------------------------------- | -| `init` | `commands/init.ts` | Initialize `.archgate/` skeleton | -| `check` | `commands/check.ts` | Run ADR compliance checks | -| `adr create` | `commands/adr/create.ts` | Create ADR interactively | -| `adr list` | `commands/adr/list.ts` | List ADRs (`--json`, `--domain`) | -| `adr show ` | `commands/adr/show.ts` | Show ADR by ID | -| `adr update` | `commands/adr/update.ts` | Update ADR by ID | -| `mcp` | `commands/mcp.ts` | Start MCP server | -| `upgrade` | `commands/upgrade.ts` | Upgrade CLI binary via GitHub Releases | -| `clean` | `commands/clean.ts` | Remove `~/.archgate/` cache | +| Command | File | Description | +| --------------- | ------------------------ | -------------------------------- | +| `init` | `commands/init.ts` | Initialize `.archgate/` skeleton | +| `check` | `commands/check.ts` | Run ADR compliance checks | +| `adr create` | `commands/adr/create.ts` | Create ADR interactively | +| `adr list` | `commands/adr/list.ts` | List ADRs (`--json`, `--domain`) | +| `adr show ` | `commands/adr/show.ts` | Show ADR by ID | +| `adr update` | `commands/adr/update.ts` | Update ADR by ID | +| `login` | `commands/login.ts` | GitHub auth for editor plugins | +| `mcp` | `commands/mcp.ts` | Start MCP server | +| `upgrade` | `commands/upgrade.ts` | Upgrade CLI via npm | +| `clean` | `commands/clean.ts` | Remove `~/.archgate/` cache | ### Key Paths diff --git a/README.md b/README.md index 27988536..813fae0d 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ [![License: FSL-1.1-ALv2](https://img.shields.io/badge/License-FSL--1.1--ALv2-blue.svg)](LICENSE.md) [![Release](https://github.com/archgate/cli/actions/workflows/release.yml/badge.svg)](https://github.com/archgate/cli/actions/workflows/release.yml) +[![Docs](https://img.shields.io/badge/docs-cli.archgate.dev-blue)](https://cli.archgate.dev) @@ -313,6 +314,10 @@ The Cursor plugin bundle is downloaded from [plugins.archgate.dev](https://plugi Once installed, run the `ag-onboard` skill in Cursor to initialize governance for your project. +## Documentation + +Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** -- including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI and MCP reference. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow. diff --git a/docs/src/content/docs/concepts/adrs.mdx b/docs/src/content/docs/concepts/adrs.mdx index e5a88ddc..c07b8153 100644 --- a/docs/src/content/docs/concepts/adrs.mdx +++ b/docs/src/content/docs/concepts/adrs.mdx @@ -15,6 +15,10 @@ The document is a Markdown file with YAML frontmatter stored in `.archgate/adrs/ Both humans and AI agents consume this document. When an AI coding agent is about to write code, it reads the relevant ADRs to understand the constraints before generating anything. +:::tip[Automate this with editor plugins] +With the [Claude Code](/guides/claude-code-plugin/) or [Cursor](/guides/cursor-integration/) plugin, your AI agent reads the applicable ADRs automatically before every coding task -- no manual copy-pasting into prompts. [Sign up for beta access](https://plugins.archgate.dev). +::: + ### ADR as Rules The rules file is a companion `.rules.ts` file that exports automated checks via `defineRules()`. When you run `archgate check`, the CLI loads every ADR that has `rules: true` in its frontmatter, executes the companion rules file against your codebase, and reports any violations with file paths and line numbers. diff --git a/docs/src/content/docs/concepts/rules.mdx b/docs/src/content/docs/concepts/rules.mdx index a12e3d38..d112a1ac 100644 --- a/docs/src/content/docs/concepts/rules.mdx +++ b/docs/src/content/docs/concepts/rules.mdx @@ -160,3 +160,7 @@ Rules execute with the following guarantees: - **Sequential within an ADR** -- Rules belonging to the same ADR run one after another, so earlier rules can establish context for later ones. - **Scoped files are pre-resolved** -- The `ctx.scopedFiles` array is populated before your `check` function is called, based on the ADR's `files` globs. - **Changed files for staged mode** -- When running `archgate check --staged`, `ctx.changedFiles` contains only the files staged in git, letting rules skip unchanged files for faster feedback. + +:::tip[Run checks automatically with editor plugins] +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) run `archgate check` automatically after every code change. The agent reads the applicable ADRs, writes compliant code, and validates -- no manual check commands needed. [Sign up for beta access](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/examples/common-rule-patterns.mdx b/docs/src/content/docs/examples/common-rule-patterns.mdx index 466cf65f..e1b3cd50 100644 --- a/docs/src/content/docs/examples/common-rule-patterns.mdx +++ b/docs/src/content/docs/examples/common-rule-patterns.mdx @@ -267,3 +267,7 @@ To adapt for projects that colocate tests next to source files, change the path const testPath = rel.replace(/\.ts$/, ".test.ts"); // src/helpers/log.ts -> src/helpers/log.test.ts ``` + +:::tip[Let AI agents write rules for you] +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include a Quality Manager skill that identifies recurring patterns in your codebase and proposes new rules to enforce them. [Sign up for beta access](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/getting-started/installation.mdx b/docs/src/content/docs/getting-started/installation.mdx index 402268a0..bbf13d4c 100644 --- a/docs/src/content/docs/getting-started/installation.mdx +++ b/docs/src/content/docs/getting-started/installation.mdx @@ -108,3 +108,11 @@ export PATH="$HOME/.proto/tools/node/globals/bin:$PATH" ``` Restart your shell, then run `npm install -g archgate` again. The `archgate` command should now be available globally. + +## Next steps + +Once installed, run `archgate init` in your project to set up governance. See the [Quick Start](/getting-started/quick-start/) guide for a walkthrough. + +:::tip[Editor plugins (beta)] +Want your AI agent to read ADRs before coding and validate after? The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) add a full governance workflow on top of the CLI. [Sign up for beta access](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/getting-started/quick-start.mdx b/docs/src/content/docs/getting-started/quick-start.mdx index af3f207e..4722f273 100644 --- a/docs/src/content/docs/getting-started/quick-start.mdx +++ b/docs/src/content/docs/getting-started/quick-start.mdx @@ -51,7 +51,7 @@ files: ["src/**/*.ts"] - **id** — Unique identifier. Convention is `ARCH-NNN` but any string works. - **title** — Human-readable name for the decision. -- **domain** — Groups related ADRs together (e.g., `architecture`, `security`, `testing`). +- **domain** — Groups related ADRs together (`architecture`, `backend`, `frontend`, `data`, or `general`). - **rules** — Set to `true` if this ADR has a companion `.rules.ts` file with automated checks. - **files** — Optional glob patterns that scope which files the rules apply to. @@ -116,6 +116,25 @@ archgate check --staged Now that you have a working setup, dive deeper: +**Understand the concepts:** + +- [ADRs](/concepts/adrs/) — What Architecture Decision Records are and how Archgate uses them. +- [Rules](/concepts/rules/) — How companion `.rules.ts` files turn decisions into automated checks. +- [Domains](/concepts/domains/) — How domains group related ADRs and scope file matching. + +**Write your own:** + - [Writing ADRs](/guides/writing-adrs/) — Learn the full ADR format and best practices for writing effective decisions. - [Writing Rules](/guides/writing-rules/) — Explore the rule API, advanced patterns, and how to test your rules. +- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns for dependency checks, naming conventions, and more. + +**Integrate into your workflow:** + - [CI Integration](/guides/ci-integration/) — Wire `archgate check` into GitHub Actions, GitLab CI, or any pipeline. +- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Run checks locally before every commit. +- [Claude Code Plugin](/guides/claude-code-plugin/) — Give AI agents a full governance workflow with role-based skills. +- [Cursor Integration](/guides/cursor-integration/) — Use Archgate with Cursor IDE for AI-assisted development. + +:::tip[Editor plugins (beta)] +Want AI agents that automatically read your ADRs before coding? Sign up for the editor plugin beta at [plugins.archgate.dev](https://plugins.archgate.dev), then run `archgate login` and `archgate init --install-plugin`. +::: diff --git a/docs/src/content/docs/guides/ci-integration.mdx b/docs/src/content/docs/guides/ci-integration.mdx index 5f465e14..fea5183f 100644 --- a/docs/src/content/docs/guides/ci-integration.mdx +++ b/docs/src/content/docs/guides/ci-integration.mdx @@ -54,13 +54,23 @@ The JSON output includes: "errors": 1, "infos": 0, "ruleErrors": 0, + "truncated": false, "results": [ { - "ruleId": "no-unapproved-deps", "adrId": "ARCH-006", - "message": "Unapproved production dependency: \"chalk\"", - "file": "package.json", - "severity": "error" + "ruleId": "no-unapproved-deps", + "description": "Production dependencies must be on the approved list", + "status": "fail", + "totalViolations": 1, + "shownViolations": 1, + "violations": [ + { + "message": "Unapproved production dependency: \"chalk\"", + "file": "package.json", + "severity": "error" + } + ], + "durationMs": 18 } ], "durationMs": 142 @@ -149,11 +159,26 @@ adr-compliance: - archgate check ``` +## Bun-based CI + +If your CI already uses Bun, install Archgate with `bun` instead of `npm`: + +```yaml +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: oven-sh/setup-bun@v2 + - run: bun install -g archgate + - run: archgate check --ci +``` + ## Other CI systems Archgate works with any CI system that can run shell commands. The pattern is always the same: -1. Install: `npm install -g archgate` +1. Install: `npm install -g archgate` (or `bun install -g archgate`) 2. Run: `archgate check` 3. Check the exit code (0 = pass, 1 = violations, 2 = error) @@ -177,3 +202,7 @@ Use `--verbose` to see passing rules and timing information alongside failures. ```yaml - run: archgate check --verbose ``` + +:::tip[Add AI governance to your workflow] +CI catches violations at merge time. Editor plugins catch them at coding time. With the [Claude Code](/guides/claude-code-plugin/) or [Cursor](/guides/cursor-integration/) plugin, your AI agent reads ADRs before writing code and validates compliance before you even commit. [Sign up for beta access](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/guides/claude-code-plugin.mdx b/docs/src/content/docs/guides/claude-code-plugin.mdx index b345477d..587515e9 100644 --- a/docs/src/content/docs/guides/claude-code-plugin.mdx +++ b/docs/src/content/docs/guides/claude-code-plugin.mdx @@ -21,7 +21,40 @@ The plugin adds role-based skills to Claude Code. Each skill encapsulates a spec ## Installation -Install the plugin from the `archgate/claude-code-plugin` GitHub repository. Follow the instructions in the repository README to add it to your Claude Code configuration. +:::note[Beta access required] +The Claude Code plugin is currently in beta. [Sign up at plugins.archgate.dev](https://plugins.archgate.dev) to get access before following the steps below. +::: + +### 1. Log in with GitHub + +Authenticate with your GitHub account to obtain a plugin token: + +```bash +archgate login +``` + +This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`. + +### 2. Initialize your project with the plugin + +Run `archgate init` in your project. If you are already logged in, the plugin is installed automatically: + +```bash +archgate init +``` + +To explicitly request plugin installation: + +```bash +archgate init --install-plugin +``` + +If the `claude` CLI is on your PATH, the plugin is installed automatically via: + +1. `claude plugin marketplace add` (registers the Archgate marketplace) +2. `claude plugin install archgate@archgate` (installs the plugin) + +If the `claude` CLI is not found, the command prints the manual commands for you to run. ## Initial setup with onboard diff --git a/docs/src/content/docs/guides/cursor-integration.mdx b/docs/src/content/docs/guides/cursor-integration.mdx index f18b82c6..1afd62e5 100644 --- a/docs/src/content/docs/guides/cursor-integration.mdx +++ b/docs/src/content/docs/guides/cursor-integration.mdx @@ -3,6 +3,8 @@ title: Cursor Integration description: Use Archgate with Cursor IDE for AI-assisted development with governance. --- +Archgate integrates with [Cursor](https://cursor.com) to give AI agents a structured governance workflow. The agent reads your ADRs before writing code, validates after, and captures new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/). + ## Setup Run `archgate init` with the `--editor cursor` flag to configure Cursor integration in your project: @@ -11,7 +13,28 @@ Run `archgate init` with the `--editor cursor` flag to configure Cursor integrat archgate init --editor cursor ``` -This creates the following files inside your project: +### With plugin (beta) + +:::note[Beta access required] +The Cursor plugin is currently in beta. [Sign up at plugins.archgate.dev](https://plugins.archgate.dev) to get access. +::: + +If you have logged in via `archgate login`, the init command also downloads and installs the Archgate plugin for Cursor. The plugin provides pre-built agent rules and skills that give Cursor's AI agent a full governance workflow. + +To explicitly install the plugin: + +```bash +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. + +### 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. + +### Generated files | File | Purpose | | --------------------------------------- | -------------------------------------------------------------- | @@ -20,7 +43,86 @@ This creates the following files inside your project: If `.cursor/mcp.json` already exists, Archgate merges its configuration additively -- existing MCP server entries are preserved. -## What it configures +## 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. + +### Skills included + +| 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 | + +These are the same skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's slash command interface. + +## Initial setup with onboard + +After installing the plugin, run `/ag-onboard` in your project once. This skill: + +1. Explores your codebase structure (directories, key files, package configuration) +2. Interviews you about your team's conventions, constraints, and architectural decisions +3. Creates an initial set of ADRs based on your responses +4. Sets up the `.archgate/` directory with your first rules + +The onboard skill is designed to run once per project. After onboarding, the other skills handle day-to-day development. + +## How it works in practice + +### With the plugin + +The `/ag-developer` skill follows a structured workflow for every coding task: + +1. **Read applicable ADRs** -- The agent calls `review_context` to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs. + +2. **Write code following ADR constraints** -- The agent implements changes following the Do's and Don'ts from the applicable ADRs. + +3. **Run compliance checks** -- The agent runs `archgate check` to execute automated rules. Any violations are fixed before proceeding. + +4. **Architect review** -- The agent invokes `/ag-architect` to validate structural ADR compliance beyond what automated rules catch. + +5. **Capture learnings** -- The agent invokes `/ag-quality-manager` to review the work and identify patterns worth capturing as new ADRs or updates to existing ones. + +### Without the plugin + +The agent connects to the Archgate MCP server and follows four manual steps: + +1. **Review context** -- Call `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`). + +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. + +## ADR-driven refusal + +When the agent encounters a task that would require violating an ADR, it refuses and explains which ADR would be violated. It then suggests how to achieve the same goal while staying compliant. + +For example, if a developer asks the agent to add `chalk` as a dependency in a project governed by a dependency policy ADR, the agent will: + +1. Refuse, citing the ADR and the approved dependency list +2. Suggest using the approved alternative instead +3. Offer to implement the task using the compliant approach + +This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions. + +## When to use each skill + +| Scenario | Slash command | +| -------------------------------------------- | --------------------- | +| Starting a new project with Archgate | `/ag-onboard` | +| Day-to-day coding tasks | `/ag-developer` | +| Reviewing a PR for ADR compliance | `/ag-architect` | +| 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: @@ -37,21 +139,18 @@ The generated `.cursor/mcp.json` registers the Archgate MCP server: 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. -## How it works - -Once configured, Cursor's AI agent connects to the Archgate MCP server and gains access to your project's ADRs. The workflow follows four steps: - -1. **Review context** -- The agent calls `review_context` to see which ADRs apply to the files being changed. This returns changed files grouped by domain with condensed ADR briefings (Decision and Do's/Don'ts sections only). - -2. **Read individual ADRs** -- For full context on a specific decision, the agent reads the `adr://` resource (for example, `adr://ARCH-001`) to get the complete ADR content including rationale, consequences, and compliance sections. +The MCP server provides: -3. **Write code** -- The agent implements changes following the constraints from the applicable ADRs. +- **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 -4. **Run compliance checks** -- The agent calls `check` (optionally with `staged: true` for pre-commit scenarios) to validate that the code complies with all ADR rules. Violations include file paths and line numbers. +The MCP server runs locally and reads directly from your `.archgate/adrs/` directory. No data leaves your machine. ## Session transcript access -The `cursor_session_context` MCP tool reads Cursor agent session transcripts from disk. This allows Archgate-aware plugins and skills to access the history of the current Cursor agent conversation, which is useful for recovering context that may have been compacted or truncated. +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 tool accepts two optional parameters: @@ -60,8 +159,9 @@ The tool accepts two optional parameters: ## Tips for effective usage -- **Run `check` before committing.** Use `staged: true` to scope checks to only the files being committed. -- **Use `review_context` at the start of a task.** It is more efficient than calling `list_adrs` and reading each ADR individually. -- **Read full ADRs when the briefing is not enough.** The `adr://` resource provides the complete document including rationale and examples. +- **Use `/ag-developer` for coding tasks.** It orchestrates the full read-validate-capture workflow automatically. +- **Run `/ag-onboard` once per project.** It sets up your initial ADRs based on your actual codebase and conventions. +- **Use `/ag-architect` for PR reviews.** It validates structural compliance beyond what automated rules catch. +- **Use `/ag-quality-manager` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated. - **Commit the `.cursor/` directory.** This ensures every team member gets the same governance configuration when they clone the repository. - **Keep ADR rules files up to date.** The agent enforces what the rules check for -- if a rule is missing, the violation will not be caught. diff --git a/docs/src/content/docs/guides/mcp-server.mdx b/docs/src/content/docs/guides/mcp-server.mdx index 4901d609..cc225cf4 100644 --- a/docs/src/content/docs/guides/mcp-server.mdx +++ b/docs/src/content/docs/guides/mcp-server.mdx @@ -117,3 +117,7 @@ A typical AI agent session using the MCP server follows this pattern: 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. 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). +::: diff --git a/docs/src/content/docs/guides/writing-adrs.mdx b/docs/src/content/docs/guides/writing-adrs.mdx index e9a7cf30..89379558 100644 --- a/docs/src/content/docs/guides/writing-adrs.mdx +++ b/docs/src/content/docs/guides/writing-adrs.mdx @@ -304,3 +304,7 @@ The `--id` and `--body` flags are required. All other frontmatter fields (`--tit 6. **Write rules for decisions that can be checked automatically.** If a rule can catch a violation before code review, set `rules: true` and write a companion `.rules.ts` file. See the [Writing Rules](/guides/writing-rules/) guide. 7. **Use domain prefixes to organize.** The domain field (`backend`, `frontend`, `data`, `architecture`, `general`) determines the ID prefix and helps filter ADRs by area. + +:::tip[Let AI agents write ADRs for you] +The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include an ADR Author skill that creates and updates ADRs following your project's conventions. The Quality Manager skill also proposes new ADRs when it detects recurring patterns. [Sign up for beta access](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/guides/writing-rules.mdx b/docs/src/content/docs/guides/writing-rules.mdx index f6495e6a..3990e112 100644 --- a/docs/src/content/docs/guides/writing-rules.mdx +++ b/docs/src/content/docs/guides/writing-rules.mdx @@ -445,3 +445,9 @@ ARCH-006/no-unapproved-deps ``` 7. **Handle missing files gracefully.** If your rule reads a specific file like `package.json`, wrap the read in a try/catch and return early if the file does not exist. + +## Next steps + +- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns for dependency checks, naming conventions, import restrictions, and more. +- [Rule API Reference](/reference/rule-api/) — Full reference for all rule API types and functions. +- [CI Integration](/guides/ci-integration/) — Wire `archgate check` into your pipeline to enforce rules on every PR. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index f05ba08e..251db7a1 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -15,7 +15,7 @@ hero: variant: minimal --- -import { Card, CardGrid } from "@astrojs/starlight/components"; +import { Card, CardGrid, LinkCard } from "@astrojs/starlight/components"; ## How it works @@ -61,3 +61,61 @@ When you run `archgate check`, the CLI loads every ADR that has `rules: true` in formatting, testing, and more. + +## Editor plugins + +The Archgate CLI works standalone, but **editor plugins** unlock a full AI governance workflow. Plugins give AI agents role-based skills so they read your ADRs before coding, validate after, and capture new patterns for your team -- automatically. + + + + The Claude Code plugin adds five skills: developer, architect, + quality-manager, adr-author, and onboard. Agents follow a structured + read-validate-capture loop on every task. + + + The Cursor plugin provides pre-built agent rules and skills that give + Cursor's AI agent the same governance workflow as Claude Code. + + + +:::tip[Beta access] +Editor plugins are currently in beta. Sign up at [plugins.archgate.dev](https://plugins.archgate.dev) to get access, then install with `archgate login` and `archgate init --install-plugin`. +::: + + + + + + +## Learn more + + + + + + + diff --git a/docs/src/content/docs/reference/cli-commands.mdx b/docs/src/content/docs/reference/cli-commands.mdx index 72605fbf..05d94467 100644 --- a/docs/src/content/docs/reference/cli-commands.mdx +++ b/docs/src/content/docs/reference/cli-commands.mdx @@ -3,21 +3,117 @@ title: CLI Commands description: Complete reference for all Archgate CLI commands. --- +## Global options + +These options are available on all commands: + +| Option | Description | +| ----------------- | -------------------------- | +| `--version`, `-V` | Print the Archgate version | +| `--help`, `-h` | Show help for any command | + +```bash +archgate --version +archgate check --help +``` + +--- + +## archgate login + +Authenticate with GitHub to access Archgate editor plugins. + +```bash +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. + +:::tip[Plugin beta] +Editor plugins are currently in beta. Sign up at [plugins.archgate.dev](https://plugins.archgate.dev) to get access. +::: + +### Subcommands + +| Subcommand | Description | +| ------------------------ | ----------------------------------------- | +| `archgate login` | Authenticate (skips if already logged in) | +| `archgate login status` | Show current authentication status | +| `archgate login logout` | Remove stored credentials | +| `archgate login refresh` | Re-authenticate and claim a new token | + +### Examples + +Log in for the first time: + +```bash +archgate login +``` + +``` +Authenticating with GitHub... + +Open https://github.com/login/device in your browser +and enter the code: ABCD-1234 + +Waiting for authorization... +GitHub user: yourname +Claiming archgate plugin token... + +Authenticated as yourname. Plugin access is now available. +Run `archgate init` to set up a project with the archgate plugin. +``` + +Check login status: + +```bash +archgate login status +``` + +``` +Logged in as yourname (since 2026-02-28) +``` + +Log out: + +```bash +archgate login logout +``` + +Re-authenticate: + +```bash +archgate login refresh +``` + +--- + ## archgate init Initialize Archgate governance in the current project. ```bash -archgate init [--editor ] +archgate init [options] ``` -Creates the `.archgate/` directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows. +Creates the `.archgate/` directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows and installs the Archgate editor plugin. ### Options -| Option | Default | Description | -| ------------------- | -------- | ---------------------------------------------------- | -| `--editor ` | `claude` | Editor integration to configure (`claude`, `cursor`) | +| Option | Default | Description | +| ------------------- | -------- | -------------------------------------------------------------------- | +| `--editor ` | `claude` | Editor integration to configure (`claude`, `cursor`) | +| `--install-plugin` | auto | Install the Archgate editor plugin (requires prior `archgate login`) | + +When `--install-plugin` is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous `archgate login`) and skips otherwise. + +### Plugin installation behavior + +**Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead. + +**Cursor:** The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. ### Output @@ -26,6 +122,8 @@ Initialized Archgate governance in /path/to/project adrs/ - architecture decision records lint/ - linter-specific rules .claude/ - Claude Code settings configured + +Archgate plugin installed for Claude Code. ``` When `--editor cursor` is used, the output shows `.cursor/` instead of `.claude/`. @@ -117,17 +215,23 @@ When `--json` is used, the output is a single JSON object: "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 @@ -295,7 +399,7 @@ The server starts even when no `.archgate/` directory is found. In that case, to ### Configuration -Add to your Claude Code MCP configuration (`.claude/settings.json`): +Add to your project's MCP configuration (`.mcp.json` at the project root): ```json { @@ -308,6 +412,8 @@ Add to your Claude Code MCP configuration (`.claude/settings.json`): } ``` +Running `archgate init` creates this configuration automatically for your editor. + --- ## archgate upgrade diff --git a/docs/src/content/docs/reference/mcp-tools.mdx b/docs/src/content/docs/reference/mcp-tools.mdx index 293bdcfc..3722ed8a 100644 --- a/docs/src/content/docs/reference/mcp-tools.mdx +++ b/docs/src/content/docs/reference/mcp-tools.mdx @@ -30,26 +30,32 @@ Run ADR compliance checks against the codebase. "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": [] }`. +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. +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. --- @@ -96,9 +102,36 @@ Get changed files grouped by domain with applicable ADR briefings. This is the p | `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. Each briefing includes the **Decision** and **Do's and Don'ts** sections extracted from the applicable ADR, along with the list of changed files in that domain. +**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`, the response also includes the check results for each domain. +When `runChecks` is `true`, `checkSummary` contains the full check results (same format as the `check` tool response). When `false` or omitted, `checkSummary` is `null`. --- @@ -187,3 +220,7 @@ Read the full content of an ADR by its ID. Returns the complete markdown includi 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/) 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). +::: diff --git a/package.json b/package.json index af650fed..61a2c691 100644 --- a/package.json +++ b/package.json @@ -21,8 +21,11 @@ }, "keywords": [ "archgate", - "cli", - "framework" + "adr", + "architecture-decision-records", + "governance", + "linter", + "cli" ], "bugs": { "url": "https://github.com/archgate/cli/issues"