Creating a Pack

A pack is a directory of Architecture Decision Records and their executable rules, described by a small metadata file. You can build a pack for your own team’s private repository, or submit it to the official registry for a Curated badge. The structure is identical either way.

Pack Anatomy

Every pack follows the same layout. The key idea is that each ADR is a pair: a Markdown document that humans and AI agents read, and a co-located .rules.ts file that machines execute.

packs/my-pack/
  archgate-pack.yaml         # pack metadata (required)
  README.md                  # overview and ADR listing (required)
  rules.d.ts                 # ambient types for .rules.ts (required)
  adrs/
    ADR-001-my-decision.md         # ADR document (at least one)
    ADR-001-my-decision.rules.ts   # corresponding rule file

archgate-pack.yaml

Pack metadata — name, version, description, maintainers, and tags. This is authoritative; the directory path is just an address.

ADR documents

Markdown with YAML frontmatter, one decision each. They explain why a choice was made and what trade-offs follow.

Rule files

A co-located .rules.ts per ADR that turns the decision into an automated check archgate check can run.

rules.d.ts

Ambient type definitions so your rule files get full type safety against the rule API.

1. Pack Metadata

Create archgate-pack.yaml at the pack root:

name: my-pack
version: 0.1.0
description: Short description of what this pack covers.
maintainers:
  - github: your-github-username
tags:
  - language:typescript
  - concern:security

Tags use the <axis>:<value> convention (language:, runtime:, framework:, tool:, concern:, domain:, stack:). They drive filtering in the web builder, so the directory never has to be re-organized when a pack spans two categories.

2. ADR Documents

Each ADR is a Markdown file under adrs/ with YAML frontmatter:

---
id: ADR-001
title: My Decision
domain: architecture
rules: true
files: ["**/*.ts"]
---

Follow the frontmatter with these sections, in order: ## Context, ## Decision, ## Do's and Don'ts, and ## Consequences. Set rules: true when the ADR ships a paired rule file, and use files to scope which paths the rule applies to.

ADR schema reference The full frontmatter schema, domains, and ADR authoring conventions are documented in the CLI docs.

3. Rule Files

Pair each rule-bearing ADR with a <adr-id>-<slug>.rules.ts file in the same adrs/ directory. Every rule file must:

1. Start with a triple-slash reference to the ambient types: /// <reference path="../rules.d.ts" />
2. Export a default object validated with satisfies RuleSet
3. Use only the RuleContext API — glob(), grep(), grepFiles(), readFile(), readJSON(), and report.violation() / report.warning() / report.info()
4. Be async

Here is the rule paired with the SEC-001-no-secrets-in-code ADR in the curated security pack, abridged:

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

export default {
  rules: {
    "no-secrets-in-code": {
      description:
        "Source files must not contain hardcoded secrets, API keys, or tokens",
      async check(ctx) {
        const sourceGlob = "**/*.{ts,tsx,js,jsx}";
        const matches = await ctx.grepFiles(
          /API_KEY\s*=\s*["'][^"']{8,}["']/u,
          sourceGlob,
        );
        for (const m of matches) {
          if (m.file.includes(".env.example")) continue;
          ctx.report.violation({
            message: "Possible hardcoded API key — do not hardcode secrets.",
            file: m.file,
            line: m.line,
            fix: "Move the secret to an environment variable and read it via `process.env`.",
          });
        }
      },
    },
  },
} satisfies RuleSet;

Reuse the rule sandbox

Rules run in Archgate’s static-analysis sandbox, which already rejects unsafe APIs. Keep checks deterministic and side-effect free — read the workspace, report findings, return.

The rules.d.ts file supplies ambient types for RuleSet, RuleContext, GrepMatch, the report API, and PackageJson. Copy it from any curated pack so your editor and the validator agree on the contract.

Rule API reference Every method on RuleContext, the report API, and severity levels are documented authoritatively in the CLI docs.

4. README

Write a README.md that names the pack, gives a one-line description, lists the included ADRs in a table (ID and title), and shows the archgate adr import packs/<name> quick-start command. This is what renders on the pack’s detail page in the builder.

Submitting a Curated Pack

To get your pack hosted in the registry with a Curated badge:

1. Fork archgate/awesome-adrs and create packs/my-pack/ with the files above.

2. Validate locally — every .rules.ts must compile without errors, and the archgate-pack.yaml and rule-file structure must pass CI validation.

3. Open a pull request using the curated pack PR template. A maintainer reviews and approves it.

Once merged, the pack is importable by anyone with archgate adr import packs/my-pack.

Keeping the badge

A Curated badge can be revoked if a pack’s rules break after upstream changes and the maintainer does not respond within 30 days. Packs abandoned for more than 6 months may be archived. Keep your rules green.

Private and Third-Party Packs

You do not have to submit to the official registry. The same structure works in any git repository, and consumers import it with the git URL or <org>/<repo>/<path> form — no publishing step required. A team’s own ADR set is just a pack at a path in their repo.

Community links Index an external pack as a community link instead of hosting it.

Curated catalog See finished packs for structure and tone to model yours on.