Skip to content

docs: slim README and point to docs website #29

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
Feb 28, 2026
Merged

docs: slim README and point to docs website #29

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
93ccd14
docs: slim README and point to docs website
rhuanbarreto Feb 28, 2026
e0aad1f
fix: update homepage URL in package.json
rhuanbarreto Feb 28, 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
257 changes: 32 additions & 225 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,6 @@ When a rule is violated, `archgate check` reports the file, line, and which ADR

**The CLI is free and open source.** Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription.

**Editor plugins are an optional paid add-on** for teams that want AI agents (Claude Code, Cursor) to read ADRs, validate changes, and capture new patterns automatically. Plugins are distributed from [plugins.archgate.dev](https://plugins.archgate.dev). See [Editor plugins](#editor-plugins) for details.

## Installation

```bash
Expand All @@ -54,31 +52,14 @@ yarn global add archgate
pnpm add -g archgate
```

You can also install Archgate as a dev dependency and run it through your package manager:
You can also install as a dev dependency:

```bash
# Install as dev dependency
npm install -D archgate # or: bun add -d archgate

# Run via package manager
npx archgate check # npm / Yarn / pnpm
bun run archgate check # Bun
npx archgate check # run via package manager
```

**Requirements:** macOS (arm64), Linux (x86_64), or Windows (x86_64). Node.js is only needed to run the npm/yarn/pnpm wrapper — the CLI itself is a standalone binary.

> **Using [proto](https://moonrepo.dev/proto)?** Add the following to `~/.proto/config.toml` and your shell profile so globals persist across Node.js version switches:
>
> ```toml
> # ~/.proto/config.toml
> [tools.npm]
> shared-globals-dir = true
> ```
>
> ```sh
> # ~/.zshrc or ~/.bashrc
> export PATH="$HOME/.proto/tools/node/globals/bin:$PATH"
> ```
**Requirements:** macOS (arm64), Linux (x86_64), or Windows (x86_64). See the [installation guide](https://cli.archgate.dev/getting-started/installation/) for more options.

## Quick start

Expand All @@ -100,223 +81,49 @@ archgate init
archgate check
```

`archgate init` creates the `.archgate/adrs/` directory with an example ADR and rules file, and configures editor settings. No account or login is needed — the CLI is fully functional without plugins.

**Want AI agent integration?** See [Editor plugins](#editor-plugins) to add the optional paid plugin for Claude Code or Cursor.

## Writing rules

A companion `.rules.ts` file exports checks using `defineRules()` from the `archgate` package:

```typescript
// .archgate/adrs/ARCH-002-error-handling.rules.ts
import { defineRules } from "archgate/rules";

export default defineRules([
{
id: "use-log-error",
description:
"Use logError() instead of console.error() for user-facing errors",
severity: "error",
async check({ files }) {
const violations = [];
for (const file of files) {
const content = await Bun.file(file).text();
const lines = content.split("\n");
lines.forEach((line, i) => {
if (line.includes("console.error(")) {
violations.push({
file,
line: i + 1,
message: "Use logError() instead",
});
}
});
}
return violations;
},
},
]);
```
Each ADR can have a companion `.rules.ts` file that exports checks using `defineRules()` from the `archgate` package. Rules receive the list of files to check and return an array of violations with file paths and line numbers.

Rules receive the list of files to check (filtered by the ADR's `files` glob if set), and return an array of violations with file paths and line numbers.
See the [writing rules guide](https://cli.archgate.dev/guides/writing-rules/) for examples and the full [rule API reference](https://cli.archgate.dev/reference/rule-api/).

## Commands

### `archgate login`

Authenticate with GitHub to access the optional paid editor plugins.

```bash
archgate login # authenticate via GitHub Device Flow
archgate login status # show current auth status
archgate login logout # remove stored credentials
archgate login refresh # re-authenticate and claim a new token
```

Opens a browser-based GitHub Device Flow. Once authorized, an archgate plugin token is stored in `~/.archgate/credentials`. This token is used by `archgate init` to install the editor plugin. Not required for CLI-only usage.

### `archgate init`

Initialize governance in the current project.

```bash
archgate init # Claude Code (default)
archgate init --editor cursor # Cursor
archgate init --install-plugin # force plugin install attempt
```

Creates `.archgate/adrs/` with an example ADR and rules file and configures editor settings. Works without an account — plugin installation only happens when you are logged in.

**Plugin install behavior** (optional — requires `archgate login`):

- If you are logged in, init auto-detects your credentials and installs the plugin.
- For **Claude Code**: if the `claude` CLI is on PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If not, the manual commands are printed.
- For **Cursor**: the plugin bundle is downloaded from [plugins.archgate.dev](https://plugins.archgate.dev) and extracted into `.cursor/`.
- Use `--install-plugin` to explicitly request plugin installation (useful if auto-detection is skipped).

### `archgate check`

Run all automated ADR checks against your codebase.

```bash
archgate check # check all files
archgate check --staged # check only git-staged files (for pre-commit hooks)
archgate check --json # machine-readable JSON output
```

Exits with code 0 if all checks pass, 1 if any violations are found.

### `archgate adr create`

Create a new ADR interactively.

```bash
archgate adr create
```

Prompts for a title, domain, and optional file glob. Generates a sequential ID (`ARCH-001`, `ARCH-002`, ...) and writes the markdown file.

### `archgate adr list`

List all ADRs in the project.

```bash
archgate adr list # table output
archgate adr list --json # JSON output
archgate adr list --domain backend # filter by domain
```

### `archgate adr show <id>`

Print a specific ADR.

```bash
archgate adr show ARCH-001
```

### `archgate adr update`
| Command | Description |
| ------------------------ | ---------------------------------------------------------- |
| `archgate init` | Initialize `.archgate/` with example ADR and editor config |
| `archgate check` | Run ADR compliance checks (`--staged` for pre-commit) |
| `archgate adr create` | Create a new ADR interactively |
| `archgate adr list` | List all ADRs (`--json`, `--domain`) |
| `archgate adr show <id>` | Print a specific ADR |
| `archgate adr update` | Update an ADR's frontmatter |
| `archgate login` | Authenticate with GitHub for editor plugins |
| `archgate mcp` | Start the MCP server for AI agent integration |
| `archgate upgrade` | Upgrade to the latest release |
| `archgate clean` | Remove the CLI cache (`~/.archgate/`) |

Update an existing ADR's frontmatter.
See the [CLI reference](https://cli.archgate.dev/reference/cli-commands/) for full usage and options.

```bash
archgate adr update ARCH-001 --title "New Title" --domain backend
```

### `archgate mcp`

Start the MCP server for AI agent integration.

```bash
archgate mcp
```

Exposes five tools to MCP-compatible clients (Claude Code, Cursor, etc.):

| Tool | Description |
| ----------------------------- | ----------------------------------------------------------------- |
| `check` | Run ADR compliance checks, optionally on staged files only |
| `list_adrs` | List all ADRs with metadata |
| `review_context` | Get changed files grouped by domain with applicable ADR briefings |
| `claude_code_session_context` | Read the current Claude Code session transcript |
| `cursor_session_context` | Read Cursor agent session transcripts |

Also exposes `adr://{id}` resources for reading individual ADRs by ID.

### `archgate upgrade`

Upgrade to the latest release.

```bash
npm update -g archgate
```

### `archgate clean`

Remove the CLI cache directory (`~/.archgate/`).

```bash
archgate clean
```

## CI integration

Add a check step to your pipeline:

```yaml
# GitHub Actions example
- name: ADR compliance check
run: archgate check
```

For pre-commit hooks (using [lefthook](https://github.com/evilmartians/lefthook) or similar):

```yaml
pre-commit:
commands:
adr-check:
run: archgate check --staged
```

## Editor plugins

> **Plugins are an optional paid add-on.** The CLI works fully without them. Plugins add AI agent integration — your AI coding agent reads ADRs before writing code, validates changes after implementation, and captures new patterns back into ADRs.

Plugins are distributed from [plugins.archgate.dev](https://plugins.archgate.dev).

### Setup

```bash
# 1. Log in (one-time) — links your GitHub account and issues a plugin token
archgate login

# 2. Initialize a project with the plugin
archgate init # Claude Code (default)
archgate init --editor cursor # or Cursor
```
## CI and pre-commit hooks

If you are logged in, `archgate init` auto-detects your credentials and installs the plugin. You can also pass `--install-plugin` explicitly.
Add `archgate check` to your CI pipeline or pre-commit hooks to block merges that violate ADRs. See the [CI integration guide](https://cli.archgate.dev/guides/ci-integration/) and [pre-commit hooks guide](https://cli.archgate.dev/guides/pre-commit-hooks/) for setup instructions.

### Claude Code
## Supercharge with AI plugins

If the `claude` CLI is on your PATH, the plugin is installed automatically. Otherwise, run the printed commands manually:

```bash
claude plugin marketplace add https://<user>:<token>@plugins.archgate.dev/archgate.git
claude plugin install archgate@archgate
```

Once installed, run `archgate:onboard` in Claude Code to initialize governance for your project.

### Cursor

The Cursor plugin bundle is downloaded from [plugins.archgate.dev](https://plugins.archgate.dev) and extracted into `.cursor/` automatically.

Once installed, run the `ag-onboard` skill in Cursor to initialize governance for your project.
> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically.
>
> Plugins are available for [**Claude Code**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/).
>
> ```bash
> archgate login # one-time GitHub auth
> archgate init # installs the plugin automatically
> ```
>
> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code.

## 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.
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

Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"description": "Enforce Architecture Decision Records as executable rules — for both humans and AI agents",
"readme": "README.md",
"license": "FSL-1.1-ALv2",
"homepage": "https://archgate.dev",
"homepage": "https://cli.archgate.dev",
"bin": {
"archgate": "bin/archgate.cjs"
},
Expand Down