From 93ccd142a2edadc0bc040a9ea80e3f85caa21be4 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sat, 28 Feb 2026 19:42:02 +0100 Subject: [PATCH 1/2] docs: slim README and point to docs website Replace detailed command docs, rule examples, CI snippets, and plugin setup with concise summaries linking to cli.archgate.dev. Add a prominent "Supercharge with AI plugins" CTA section. Co-Authored-By: Claude Opus 4.6 --- README.md | 257 +++++++----------------------------------------------- 1 file changed, 32 insertions(+), 225 deletions(-) diff --git a/README.md b/README.md index 813fae0d..4d2d40c5 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 ` - -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 ` | 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://:@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 From e0aad1fed1e8ff294bce85491ba330b8e7c8f7ba Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sat, 28 Feb 2026 19:51:04 +0100 Subject: [PATCH 2/2] fix: update homepage URL in package.json --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index e81266a9..53a648f3 100644 --- a/package.json +++ b/package.json @@ -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" },