### Install Archgate using Proto

Source: https://cli.archgate.dev/getting-started/installation

Install and use Archgate as a proto tool. Proto handles version management and binary installation automatically.

```bash
proto install archgate
archgate check
```

--------------------------------

### Setup Archgate CLI for Custom Commands

Source: https://cli.archgate.dev/guides/ci-integration

Use `archgate/setup-action` to install the CLI and add it to the PATH, enabling the execution of custom Archgate commands like `adr list --json`.

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: archgate/setup-action@v1
  - run: archgate check --ci
  - run: archgate adr list --json

```

--------------------------------

### Initialize Project and Install Plugin

Source: https://cli.archgate.dev/guides/vscode-plugin

Explicitly request plugin installation during project initialization.

```bash
archgate init --editor vscode --install-plugin
```

--------------------------------

### Install Archgate opencode Plugin

Source: https://cli.archgate.dev/guides/opencode-integration

Use these commands for a one-time setup and to install the Archgate agent bundle for opencode. This requires opencode to be installed and authenticated via `archgate login`.

```bash
archgate login                                  # one-time setup
archgate init --editor opencode --install-plugin
```

--------------------------------

### Install Archgate Plugin

Source: https://cli.archgate.dev/reference/cli/plugin

Installs the Archgate plugin for the specified editor on an already-initialized project. Installation behavior varies by editor.

```bash
archgate plugin install [options]
```

--------------------------------

### Initialize Project and Explicitly Install Plugin

Source: https://cli.archgate.dev/guides/copilot-cli-plugin

Initialize your project and explicitly request the installation of the Archgate Copilot CLI plugin.

```bash
archgate init --editor copilot --install-plugin
```

--------------------------------

### Initialize Project with Plugin

Source: https://cli.archgate.dev/guides/claude-code-plugin

Initialize your project with the plugin. If already logged in, the plugin installs automatically. Use --install-plugin to explicitly request installation.

```bash
archgate init
```

```bash
archgate init --install-plugin
```

--------------------------------

### Install Plugin on Existing Project

Source: https://cli.archgate.dev/guides/claude-code-plugin

Install or reinstall the plugin on an existing project without re-running 'archgate init'.

```bash
archgate plugin install
```

--------------------------------

### Example: Read Latest OpenCode Session

Source: https://cli.archgate.dev/reference/cli/session-context

This example shows how to fetch the most recent session transcript from OpenCode.

```bash
archgate session-context opencode
```

--------------------------------

### Archgate Upgrade Output Example

Source: https://cli.archgate.dev/reference/cli/upgrade

This example shows the typical output when Archgate is successfully upgraded to a newer version.

```bash
Checking for latest Archgate release...
Upgrading 0.34.0 -> 0.35.0...
Archgate upgraded to 0.35.0 successfully.
```

--------------------------------

### Install or Reinstall Plugin

Source: https://cli.archgate.dev/guides/vscode-plugin

Install or reinstall the Archgate VS Code plugin on an already-initialized project.

```bash
archgate plugin install --editor vscode
```

--------------------------------

### Install Archgate Globally via Yarn

Source: https://cli.archgate.dev/getting-started/installation

Install Archgate globally using Yarn. Ensure Yarn is installed and configured in your environment.

```bash
# Yarn
yarn global add archgate
```

--------------------------------

### Install Archgate CLI

Source: https://cli.archgate.dev/getting-started/quick-start

Install the Archgate CLI using curl for a standalone version or npm for Node.js environments. Refer to the Installation page for other OS options.

```bash
# Standalone (no Node.js required)
curl -fsSL https://cli.archgate.dev/install-unix | sh
```

```bash
# Or via npm
npm install -g archgate
```

--------------------------------

### Install Archgate Standalone (macOS/Linux)

Source: https://cli.archgate.dev/getting-started/installation

Use this command to download and install the Archgate CLI directly on macOS and Linux systems. The installer adds the binary to your PATH.

```bash
# macOS / Linux
curl -fsSL https://cli.archgate.dev/install-unix | sh
```

--------------------------------

### Verify Archgate Installation

Source: https://cli.archgate.dev/getting-started/installation

Run this command after installation to confirm Archgate is installed correctly and accessible in your PATH. It should output the installed version.

```bash
archgate --version
```

--------------------------------

### Directory Structure Example (Correct)

Source: https://cli.archgate.dev/examples/test-file-coverage

Shows a project structure where every source file has a corresponding test file.

```text
src/
  helpers/
    log.ts
    paths.ts
tests/
  helpers/
    log.test.ts
    paths.test.ts


```

--------------------------------

### Example: Read Latest Copilot CLI Session

Source: https://cli.archgate.dev/reference/cli/session-context

This example shows how to fetch the most recent session transcript from Copilot CLI.

```bash
archgate session-context copilot
```

--------------------------------

### Install or Reinstall Plugin on Existing Project

Source: https://cli.archgate.dev/guides/copilot-cli-plugin

Install or reinstall the Archgate Copilot CLI plugin on a project that has already been initialized.

```bash
archgate plugin install --editor copilot
```

--------------------------------

### Archgate Plugin CLI Usage

Source: https://cli.archgate.dev/reference/cli/plugin

The base command for managing Archgate editor plugins. Use subcommands to perform specific actions like installing plugins or getting repository URLs.

```bash
archgate plugin <subcommand> [options]
```

--------------------------------

### Install Archgate with Bun in CI

Source: https://cli.archgate.dev/guides/ci-integration

Install Archgate using Bun in CI environments that already utilize Bun. This requires the oven-sh/setup-bun@v2 action.

```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
```

--------------------------------

### Install Plugin for Cursor

Source: https://cli.archgate.dev/reference/cli/plugin

Installs the Archgate plugin specifically for the Cursor editor.

```bash
archgate plugin install --editor cursor
```

--------------------------------

### Correct Filename Examples

Source: https://cli.archgate.dev/examples/kebab-case-filenames

Shows the expected file naming convention using kebab-case.

```text
src/
  helpers/
    path-utils.ts
    git-helper.ts
    adr-writer.ts
```

--------------------------------

### Install or Reinstall Cursor Plugin

Source: https://cli.archgate.dev/guides/cursor-integration

Use this command to install or reinstall the Archgate plugin for Cursor on an already-initialized project. It installs the VS Code extension via the `cursor` CLI if available.

```bash
archgate plugin install --editor cursor
```

--------------------------------

### Do's and Don'ts Section Example

Source: https://cli.archgate.dev/guides/writing-adrs

Shows concrete examples of correct and incorrect patterns for ADRs, focusing on command file structure and logic placement.

```markdown
## Do's and Don'ts


### Do


- Export a register*Command function from each command module
- Keep commands thin: parse args, call helpers/engine, format output
- Use src/commands/<name>.ts for top-level commands


### Don't


- Don't put business logic in command files -- move it to src/engine/ or src/helpers/
- Don't use executableDir() for command discovery
- Don't call .parse() in command files -- the entry point handles parsing
```

--------------------------------

### Manual Archgate Installation in CI

Source: https://cli.archgate.dev/guides/ci-integration

Install Archgate globally using npm as an alternative to official actions. This method requires an explicit install step before running checks.

```yaml
steps:
  - uses: actions/checkout@v4
  - run: npm install -g archgate
  - run: archgate check

```

--------------------------------

### Install Archgate Globally via npm

Source: https://cli.archgate.dev/getting-started/installation

Install Archgate globally using npm. This creates a lightweight wrapper that delegates to a platform-specific binary.

```bash
# npm
npm install -g archgate
```

--------------------------------

### Install Archgate Globally via pnpm

Source: https://cli.archgate.dev/getting-started/installation

Install Archgate globally using pnpm. This is a recommended method for users who prefer pnpm.

```bash
# pnpm
pnpm add -g archgate
```

--------------------------------

### Install Archgate Standalone (Windows PowerShell)

Source: https://cli.archgate.dev/getting-started/installation

Execute this command in PowerShell to install the Archgate CLI on Windows. It handles binary download and PATH configuration.

```powershell
# Windows (PowerShell)
irm https://cli.archgate.dev/install-windows | iex
```

--------------------------------

### Example: Read Latest Claude Code Session

Source: https://cli.archgate.dev/reference/cli/session-context

This example shows how to fetch the most recent session transcript from Claude Code.

```bash
archgate session-context claude-code
```

--------------------------------

### Initialize Archgate with opencode Editor

Source: https://cli.archgate.dev/guides/opencode-integration

Run this command to configure opencode integration in your project. Ensure opencode is installed and on your PATH.

```bash
archgate init --editor opencode
```

--------------------------------

### Configure Proto to use Archgate Plugin

Source: https://cli.archgate.dev/getting-started/installation

Add the Archgate plugin to your `.prototools` file to manage Archgate installations via proto. This requires proto to be installed.

```toml
[plugins.tools]
archgate = "github://archgate/proto-plugin"
```

--------------------------------

### Directory Structure Example (Incorrect)

Source: https://cli.archgate.dev/examples/test-file-coverage

Illustrates a project structure where a source file is missing its corresponding test file.

```text
src/
  helpers/
    log.ts          ← has a test ✓
    paths.ts        ← no test file ✗
tests/
  helpers/
    log.test.ts


```

--------------------------------

### Initialize Archgate Governance

Source: https://cli.archgate.dev/reference/cli/init

Run this command in your project's root directory to create the `.archgate/` directory, an example ADR, a companion rules file, and linter configuration.

```bash
archgate init [options]
```

--------------------------------

### Install Lefthook Hook

Source: https://cli.archgate.dev/guides/pre-commit-hooks

After configuring Lefthook, run this command to install the git hook. This command should be executed in your project's root directory.

```bash
lefthook install

```

--------------------------------

### Install Copilot CLI Plugin Manually

Source: https://cli.archgate.dev/guides/copilot-cli-plugin

Manually install the Archgate Copilot CLI plugin using the provided git repository URL. Replace placeholders with your GitHub user and token.

```bash
copilot plugin install https://<github-user>:<token>@plugins.archgate.dev/archgate.git
```

--------------------------------

### Install Archgate Globally via Bun

Source: https://cli.archgate.dev/getting-started/installation

Install Archgate globally using Bun. This method is efficient for projects using Bun as their package manager.

```bash
# Bun
bun install -g archgate
```

--------------------------------

### Install Specific Archgate Version Standalone

Source: https://cli.archgate.dev/guides/ci-integration

Install a specific version of Archgate using the standalone installer by setting the ARCHGATE_VERSION environment variable. This ensures consistent behavior across builds.

```shell
- run: curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | ARCHGATE_VERSION=v0.11.2 sh
```

--------------------------------

### Initialize Project with Copilot Editor

Source: https://cli.archgate.dev/guides/copilot-cli-plugin

Initialize your project with the Archgate plugin, specifying Copilot as the editor. This command automatically installs the plugin if Copilot CLI is found.

```bash
archgate init --editor copilot
```

--------------------------------

### Context Section Example

Source: https://cli.archgate.dev/guides/writing-adrs

Provides an example of how to describe the problem statement, alternatives considered, and constraints for an ADR's context section.

```markdown
## Context


The CLI needs a consistent pattern for defining and registering commands. As the
command surface grows (init, check, adr, login, upgrade, clean), the registration
mechanism must scale without introducing hidden coupling or making the dependency
graph opaque.

**Alternatives considered:**

- **Auto-discovery via `executableDir()`** -- Commander.js supports automatic
  command discovery by scanning a directory. This hides the dependency graph and
  makes dead command detection impossible.
- **Single-file command map** -- Simple but creates a monolithic file that grows
  with every command.
```

--------------------------------

### Manually Download and Install VS Code Extension

Source: https://cli.archgate.dev/guides/vscode-plugin

Manually download the Archgate VS Code extension `.vsix` file and install it using the `code` CLI. Replace `<token>` with your Archgate token.

```bash
curl -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix
code --install-extension archgate.vsix
rm archgate.vsix
```

--------------------------------

### Manage Archgate Versions with Proto

Source: https://cli.archgate.dev/getting-started/installation

Use proto commands to list available Archgate versions, install a specific version, or pin a version in your configuration.

```bash
proto list-remote archgate   # list available versions
proto install archgate 0.15.0  # install a specific version
proto pin archgate 0.15.0      # pin version in .prototools
```

--------------------------------

### Install Archgate Standalone (Windows Git Bash/MSYS2)

Source: https://cli.archgate.dev/getting-started/installation

For Windows users with Git Bash or MSYS2, use this curl command to install the Archgate CLI. It also configures the PATH.

```bash
# Windows (Git Bash / MSYS2)
curl -fsSL https://cli.archgate.dev/install-unix | sh
```

--------------------------------

### Example: Read Specific Cursor Session

Source: https://cli.archgate.dev/reference/cli/session-context

This example demonstrates how to retrieve a specific Cursor session transcript using its unique session ID.

```bash
archgate session-context cursor --session-id abc123
```

--------------------------------

### Archgate Check JSON Output Example

Source: https://cli.archgate.dev/reference/cli/check

Example of the JSON output format when the `--json` flag is used. Includes details on pass/fail status, totals, and specific rule violations.

```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",
          "line": 1,
          "endLine": 1,
          "endColumn": 42,
          "severity": "error"
        }
      ],
      "durationMs": 12
    }
  ],
  "durationMs": 42
}
```

--------------------------------

### Standalone Archgate Installer for CI

Source: https://cli.archgate.dev/guides/ci-integration

Use the standalone installer script to download and run Archgate in CI environments without Node.js. This method requires `curl` and `tar`.

```yaml
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://cli.archgate.dev/install-unix | sh
      - run: ~/.archgate/bin/archgate check --ci
```

--------------------------------

### Archgate Initialization Output

Source: https://cli.archgate.dev/reference/cli/init

This is an example of the output you will see after successfully initializing Archgate governance. It confirms the creation of directories for ADRs, linting rules, and editor-specific settings.

```text
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.
```

--------------------------------

### Archgate Doctor Output Example

Source: https://cli.archgate.dev/reference/cli/doctor

This is an example output of the `archgate doctor` command, showing system, Archgate CLI, project, and editor integration statuses. It helps in identifying missing dependencies or configuration problems.

```text
System
  OS:           win32/x64
  Bun:          1.3.11
  Node:         v24.3.0


Archgate
  Version:      0.25.1
  Install:      binary
  Exec path:    /home/user/.archgate/bin/archgate
  Config dir:   /home/user/.archgate OK
  Telemetry:    enabled
  Logged in:    yes


Project
  ADRs:         5 (3 with rules)
  Domains:      ARCH, GEN


Editor CLIs
  claude:       OK
  cursor:       MISSING
  code (vscode):OK
  copilot:      MISSING
  git:          OK


Project Integrations
  Claude:       OK (.claude/settings.local.json)
  Cursor:       MISSING (.cursor/rules/archgate-governance.mdc)
  VS Code:      OK (.vscode/settings.json)
  Copilot:      MISSING (.github/copilot/instructions.md)
```

--------------------------------

### Archgate Login and Plugin Installation

Source: https://cli.archgate.dev/getting-started/quick-start

Log in to Archgate to authenticate and initialize the AI governance plugin for AI agents to read ADRs before coding.

```bash
archgate login
```

```bash
archgate init --install-plugin
```

--------------------------------

### Correct package.json: Approved Dependencies

Source: https://cli.archgate.dev/examples/no-unapproved-deps

This example demonstrates a correct package.json where all production dependencies ('zod') are on the approved list, and 'chalk' is correctly placed in devDependencies.

```json
{ "dependencies": { "zod": "^3.23.0" }, "devDependencies": { "chalk": "^5.3.0" } }
```

--------------------------------

### Direct Import Example

Source: https://cli.archgate.dev/examples/no-barrel-files

Instead of using a barrel file, import directly from the source modules to improve clarity and tree-shaking.

```typescript
import { logInfo } from "./helpers/log";
import { resolvePaths } from "./helpers/paths";

```

--------------------------------

### Example ADR File Names

Source: https://cli.archgate.dev/concepts/adrs

Example file names for an ADR related to command structure within the 'ARCH' domain, demonstrating the naming convention for both the document and its optional rules file.

```plaintext
ARCH-001-command-structure.md

```

```plaintext
ARCH-001-command-structure.rules.ts

```

--------------------------------

### Pin Archgate Version with Proto

Source: https://cli.archgate.dev/getting-started/installation

Specify a particular version of Archgate in your `.prototools` file to ensure consistent installations across environments.

```toml
archgate = "0.15.0"


[plugins.tools]
archgate = "github://archgate/proto-plugin"
```

--------------------------------

### Incorrect Filename Examples

Source: https://cli.archgate.dev/examples/kebab-case-filenames

Illustrates common file naming conventions that violate the kebab-case rule.

```text
src/
  helpers/
    pathUtils.ts        ← camelCase
    Git_Helper.ts       ← PascalCase + snake_case
    ADRWriter.ts        ← PascalCase
```

--------------------------------

### Incorrect Code: Missing SPDX Header

Source: https://cli.archgate.dev/examples/spdx-license-headers

This example shows a TypeScript file missing the required SPDX license identifier header. Files must start with this header for compliance.

```typescript
import { join } from "node:path";


export function resolvePath(base: string, rel: string): string {
  return join(base, rel);
}

```

--------------------------------

### Correct Code Example (with logic)

Source: https://cli.archgate.dev/examples/no-barrel-files

This file contains its own logic in addition to re-exports, so it is not considered a barrel file.

```typescript
export { logInfo, logError } from "./log";
export { resolvePaths } from "./paths";


// This file has its own logic, so it is not a barrel
export function getHelperVersion(): string {
  return "1.0.0";
}

```

--------------------------------

### Reinstall Archgate opencode Plugin

Source: https://cli.archgate.dev/guides/opencode-integration

Run this command to install or reinstall the Archgate agent bundle on a project that has already been initialized with opencode integration.

```bash
archgate plugin install --editor opencode
```

--------------------------------

### Monorepo Documentation Folder Structure

Source: https://cli.archgate.dev/reference/configuration

Example of a monorepo project structure with ADRs located in a 'docs/adrs' directory, configured via .archgate/config.json.

```plaintext
my-project/
  .archgate/
    config.json          # { "paths": { "adrs": "docs/adrs" } }
    lint/
    rules.d.ts
  docs/
    adrs/
      ARCH-001-api-design.md
      ARCH-001-api-design.rules.ts
      BE-001-database-access.md
      BE-001-database-access.rules.ts
    rules.d.ts           # auto-generated by archgate check
    guides/
    ...
  src/
    ...
```

--------------------------------

### Install Archgate as a Dev Dependency (Bun)

Source: https://cli.archgate.dev/getting-started/installation

Add Archgate as a development dependency using Bun. This ensures Archgate is available for development tasks within your project.

```bash
# Bun
bun add -d archgate
```

--------------------------------

### Initialize Archgate Project

Source: https://cli.archgate.dev/getting-started/quick-start

Navigate to your project's root directory and run the `init` command to create the necessary Archgate configuration files and directories.

```bash
cd my-project
archgate init
```

--------------------------------

### Add Archgate Marketplace to Claude Code

Source: https://cli.archgate.dev/reference/cli/plugin

Example of how to add the Archgate marketplace to Claude Code using the plugin URL obtained from the CLI.

```bash
claude plugin marketplace add "$(archgate plugin url)"
claude plugin install archgate@archgate
```

--------------------------------

### Login and Initialize Cursor Integration with Plugin

Source: https://cli.archgate.dev/guides/cursor-integration

First, log in to sign up and authenticate. Then, initialize Archgate with the `--editor cursor` and `--install-plugin` flags to install the Archgate plugin for Cursor.

```bash
archgate login              # one-time setup
archgate init --editor cursor --install-plugin
```

--------------------------------

### Correct Component Pairing Example

Source: https://cli.archgate.dev/examples/component-pairing

Shows a correctly paired set of Connected and presentational components, where `UserListConnected.tsx` passes data to `UserList.tsx`.

```typescript
src/components/
  UserListConnected.tsx     ← fetches data, passes to UserList
  UserList.tsx              ← pure presentational component
```

--------------------------------

### Install Archgate as a Dev Dependency (pnpm)

Source: https://cli.archgate.dev/getting-started/installation

Add Archgate as a development dependency using pnpm. This approach is efficient for managing project-specific dependencies.

```bash
# pnpm
pnpm add -D archgate
```

--------------------------------

### ADR File Structure Example

Source: https://cli.archgate.dev/guides/writing-adrs

Illustrates the relationship between ADR markdown files and their companion `.rules.ts` files when `rules: true` is set in the frontmatter.

```directory
.archgate/adrs/
  ARCH-001-command-structure.md          # rules: true
  ARCH-001-command-structure.rules.ts    # companion rules file
  ARCH-002-error-handling.md             # rules: true
  ARCH-002-error-handling.rules.ts       # companion rules file
  GEN-001-code-review-process.md         # rules: false (no automated checks)
```

--------------------------------

### Correct Export for CLI Command

Source: https://cli.archgate.dev/examples/required-export-pattern

This example demonstrates the correct way to export a 'registerDeployCommand' function, adhering to the required pattern for CLI command files.

```typescript
import type { Command } from "commander";


export function registerDeployCommand(program: Command) {
  program
    .command("deploy")
    .description("Deploy the application")
    .action(() => {
      // ...
    });
}
```

--------------------------------

### Install Archgate as a Dev Dependency (npm)

Source: https://cli.archgate.dev/getting-started/installation

Add Archgate as a development dependency to your project using npm. This is useful for CI environments or pinning specific versions.

```bash
# npm
npm install -D archgate
```

--------------------------------

### Correct Code Example (No TODO Comments)

Source: https://cli.archgate.dev/examples/no-todo-comments

This snippet represents code that adheres to the 'no-todo-comments' rule, indicating proper implementation without deferred work markers.

```javascript
// Proper implementation with no deferred work
```

--------------------------------

### Initialize Project with VS Code Plugin

Source: https://cli.archgate.dev/guides/vscode-plugin

Initialize your project with the Archgate VS Code plugin. This command creates the governance directory, adds the marketplace URL to user settings, and installs the extension if the `code` CLI is available.

```bash
archgate init --editor vscode
```

--------------------------------

### Correct Dependency Versioning with Catalog and Workspace

Source: https://cli.archgate.dev/examples/version-catalog

This example demonstrates the correct usage of 'catalog:' for dependencies resolved from a central catalog and 'workspace:*' for internal packages, ensuring all versions are managed centrally.

```json
{ "dependencies": { "zod": "catalog:", "hono": "catalog:", "@myorg/shared": "workspace:*" } }
```

--------------------------------

### ADR Frontmatter Schema Example

Source: https://cli.archgate.dev/reference/adr-schema

This is an example of the YAML frontmatter block for an Archgate ADR. It defines the ADR's identity and scope.

```yaml
---
id: ARCH-001
title: Command Structure
domain: architecture
rules: true
files: ["src/commands/**/*.ts"]
---
```

--------------------------------

### Configure Proto for Global npm Binaries

Source: https://cli.archgate.dev/getting-started/installation

If you prefer `npm install -g archgate` over the proto plugin, configure proto to expose global npm binaries by setting `shared-globals-dir = true` and adding the global binaries directory to your shell PATH.

```toml
# Add to ~/.proto/config.toml
[tools.npm]
shared-globals-dir = true

# Add to your shell PATH
# export PATH="$HOME/.proto/tools/node/globals/bin:$PATH"
```

--------------------------------

### Example task runner configuration (Moon)

Source: https://cli.archgate.dev/examples/monorepo-task-runner

This YAML configuration demonstrates how tasks like build, test, and lint can be defined in a centralized task runner configuration file, such as moon.yml.

```yaml
tasks:
  build:
    command: tsc
    inputs:
      - src/**/*
  test:
    command: vitest
    deps:
      - ~:build
  lint:
    command: eslint .
```

--------------------------------

### Invalid ADR Frontmatter Example

Source: https://cli.archgate.dev/reference/adr-schema

An example of invalid ADR frontmatter that would cause a parse error due to a missing required field.

```text
Invalid ADR frontmatter in ARCH-001-example.md:
  - domain: Required
```

--------------------------------

### Initialize Cursor Integration

Source: https://cli.archgate.dev/guides/cursor-integration

Run this command to configure Cursor integration in your project. Use the `--editor cursor` flag.

```bash
archgate init --editor cursor
```

--------------------------------

### Companion Rules File Example

Source: https://cli.archgate.dev/getting-started/quick-start

Write automated checks for your ADRs in TypeScript using the `RuleSet` type. This example defines a rule to prevent the use of `console.error`.

```typescript
/// <reference path="../rules.d.ts" />


export default {
  rules: {
    "no-console-error": {
      description: "Use logError() instead of console.error()",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const matches = await ctx.grep(file, /console\.error\(/);
          for (const match of matches) {
            ctx.report.violation({
              message: "Use logError() instead of console.error()",
              file: match.file,
              line: match.line,
              fix: "Import logError from your helpers and use it instead",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

--------------------------------

### Archgate Rule Violation Output Example

Source: https://cli.archgate.dev/concepts/rules

This is an example of the output generated by Archgate when the 'no-direct-fs-import' rule is violated. It shows the rule ID, severity, file, line number, and the suggested fix.

```text
ARCH-007/no-direct-fs-import  ERROR
  src/services/config.ts:3 — Direct import from "node:fs" is not allowed. Use the fs wrapper from "src/helpers/fs" instead.
  Fix: Replace the import with: import { readFile, writeFile } from "../helpers/fs"
```

--------------------------------

### Log in with GitHub

Source: https://cli.archgate.dev/guides/copilot-cli-plugin

Authenticate with your GitHub account to obtain a plugin token. This initiates a GitHub Device Flow.

```bash
archgate login
```

--------------------------------

### Cache Archgate Installation in GitHub Actions

Source: https://cli.archgate.dev/guides/ci-integration

Cache the ~/.archgate directory to speed up repeated installs in GitHub Actions. This uses the actions/cache@v4 action with a specific key based on the runner's OS.

```yaml
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4


      - name: Cache Archgate
        uses: actions/cache@v4
        with:
          path: ~/.archgate
          key: archgate-${{ runner.os }}


      - run: npm install -g archgate
      - run: archgate check --ci
```

--------------------------------

### Get Authenticated Repository URL

Source: https://cli.archgate.dev/guides/claude-code-plugin

Retrieve the authenticated repository URL for manual configuration.

```bash
archgate plugin url
```

--------------------------------

### Report a Violation with Fix Suggestion

Source: https://cli.archgate.dev/guides/writing-rules

Provide a clear 'fix' message to guide developers on resolving the violation.

```typescript
ctx.report.violation({
  message: `Unapproved dependency: "chalk"`,
  file: "package.json",
  fix: "Use styleText() from node:util instead of chalk",
});
```

--------------------------------

### Example imports.json Manifest

Source: https://cli.archgate.dev/guides/importing-adrs

The `.archgate/imports.json` file records details of each ADR import, including the source, version, import timestamp, and the IDs of the ADRs that were imported. Commit this file to version control.

```json
{
  "imports": [
    {
      "source": "packs/typescript-strict",
      "version": "0.3.0",
      "importedAt": "2026-05-10T14:32:00.000Z",
      "adrIds": ["ARCH-006", "ARCH-007", "ARCH-008"]
    }
  ]
}
```

--------------------------------

### Incorrect Barrel File Example

Source: https://cli.archgate.dev/examples/no-barrel-files

A file that only re-exports symbols from other modules is considered a barrel file and will be flagged by the rule.

```typescript
export { logInfo, logError } from "./log";
export { resolvePaths } from "./paths";
export type { PathConfig } from "./paths";

```

--------------------------------

### Decision Section Example

Source: https://cli.archgate.dev/guides/writing-adrs

Illustrates how to clearly state the decision made and any key constraints in an ADR's decision section.

```markdown
## Decision


Commands live in src/commands/ and export a register*Command(program) function.
The main entry point (src/cli.ts) explicitly imports and calls each register
function.

**Key constraints:**

1. **One command per file** -- Each .ts file defines exactly one command
2. **Explicit registration** -- Every command must be manually imported in src/cli.ts
3. **Thin commands** -- Command files handle I/O only; no business logic
```

--------------------------------

### Import Recommended Library (date-fns)

Source: https://cli.archgate.dev/examples/no-banned-imports

This code snippet shows the correct way to import from 'date-fns', a recommended alternative for date formatting.

```typescript
import { format } from "date-fns";
```

--------------------------------

### Missing Required Export

Source: https://cli.archgate.dev/examples/required-export-pattern

This example shows a file that does not export the required 'register*Command' function, which would trigger a violation.

```typescript
// Missing the required register*Command export
export function deploy() {
  // ...
}
```

--------------------------------

### Show Help for a Command

Source: https://cli.archgate.dev/reference/cli

Access help information for any Archgate command using the `--help` or `-h` option. This is a global option available on all commands.

```bash
archgate check --help
```

--------------------------------

### Incorrect Component Pairing Example

Source: https://cli.archgate.dev/examples/component-pairing

Illustrates a scenario where a `UserListConnected.tsx` file exists without a corresponding `UserList.tsx` presentational component.

```typescript
src/components/
  UserListConnected.tsx     ← no UserList.tsx ✗
```

--------------------------------

### Incorrect User Table Schema

Source: https://cli.archgate.dev/examples/database-audit-fields

Example of a user table definition missing the required 'created_at' and 'updated_at' audit columns.

```typescript
export const users = sqliteTable("users", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull(),
  // Missing created_at and updated_at
});
```

--------------------------------

### Review Context with Archgate CLI

Source: https://cli.archgate.dev/guides/cursor-integration

Run this command to see which ADRs apply to the files being changed. This is a manual step before writing code.

```bash
archgate review-context
```

--------------------------------

### Get JSON Output

Source: https://cli.archgate.dev/reference/cli/check

Provides machine-readable JSON output for the compliance checks. Useful for integration with other tools or CI/CD pipelines.

```bash
archgate check --json
```

--------------------------------

### Correct Route Definition with OpenAPI Integration

Source: https://cli.archgate.dev/examples/openapi-routes

This example demonstrates a correctly defined backend route using `@hono/zod-openapi`. It imports the necessary components and uses `.openapi()` for schema validation and documentation.

```typescript
import {
  OpenAPIHono,
  createRoute,
  z
} from "@hono/zod-openapi";


const route = createRoute({
  method: "get",
  path: "/users",
  responses: {
    200: {
      content: {
        "application/json": {
          schema: UserListSchema
        }
      },
      description: "List of users",
    },
  },
});


app.openapi(route, async (c) => {
  return c.json(await getUsers());
});

```

--------------------------------

### ORM Table Pattern Adaptations

Source: https://cli.archgate.dev/examples/database-audit-fields

Examples of how to adapt the 'TABLE_PATTERN' regex for different ORMs like Drizzle with PostgreSQL or Prisma-style definitions.

```regex
// For Drizzle with PostgreSQL
const TABLE_PATTERN = /pgTable\s*\(\s*["']([^"']+)["']/g;
```

```regex
// For Prisma-style definitions
const TABLE_PATTERN = /model\s+(\w+)\s*\{/g;
```