Ai Rulez

What it is

ai-rulez is a standards-compliant lifecycle tool for agent knowledge and capabilities. You keep rules, context, skills, agents, commands, hooks, permissions and MCP servers in one source of truth, .ai-rulez/, and ai-rulez takes them through the whole lifecycle:

author  ->  generate  ->  bundle  ->  lint / validate  ->  govern  ->  publish

Most tools in this space stop at "turn my rules into markdown." ai-rulez treats agent knowledge like software you ship: versioned, linted, locked, signed and audited, with an organization policy layer that enforces a floor no repository can loosen.

• One source, 52 targets. Author once in .ai-rulez/; generate native files for every harness your team uses instead of hand-copying rules across tools.
• A real lock file. ai-rulez.lock pins remote includes, installed skills and authored content the way go.sum or package-lock.json pin dependencies.
• Supply-chain-grade trust. Sigstore signing, in-toto/DSSE attestations, CycloneDX/SPDX SBOMs and reviewer approvals, so "what prompt is actually running in production" has a verifiable answer.
• Org-wide policy, not just repo config. A central policy sets tighten-only floors; verify and CI gates enforce it everywhere.

Features

The table covers the implemented capabilities. The CLI reference lists every command and flag; standards below distinguishes supported formats from partial integrations.

Supported tools

ai-rulez ships 52 built-in presets — one per AI coding assistant, CLI agent or IDE integration — each writing that tool's own file layout, frontmatter and settings documents from the same .ai-rulez/ source. Mix and match any combination in presets = [...]; the full feature matrix (rules, skills, agents, commands, MCP, hooks, permissions, checks, user scope) is in Supported harnesses, and a provider that isn't listed yet still gets full parity through a custom provider-backed preset.

Standards

Generation isn't limited to harness files — ai-rulez aims to be compliant with the major emerging standards in the agentic ecosystem. A standard is listed when the code generates and validates it today. docs/standards.md carries the pinned spec version, the conformance test suite and the known gaps for each row, and is the source of truth for test status.

Usage

Every option below produces the same .ai-rulez/ tree and the same generated output — pick however your project already runs tools. Each one walks through init, generate and validate; Bundle and publish, Validate and Govern below cover what comes after.

# .ai-rulez/config.toml
presets = ["claude", "cursor", "codex", "copilot", "gemini"]   # any of the 52 harnesses

npx ai-rulez@latest init
npx ai-rulez@latest generate
npx ai-rulez@latest validate --strict

uvx ai-rulez init
uvx ai-rulez generate
uvx ai-rulez validate --strict

brew install goldziher/tap/ai-rulez
ai-rulez init
ai-rulez generate
ai-rulez validate --strict

go install github.com/Goldziher/ai-rulez/v5/cmd/ai-rulez@latest
ai-rulez init
ai-rulez generate
ai-rulez validate --strict

The module path needs /v5; without it @latest resolves to an old build. This local build needs cgo, a C toolchain and the Go module cache at runtime. For a statically linked build, use task build from a clone; see source installation.

npm install -g ai-rulez
ai-rulez init
ai-rulez generate
ai-rulez validate --strict

uv tool install ai-rulez
ai-rulez init
ai-rulez generate
ai-rulez validate --strict

pip install ai-rulez
# or, isolated:
pipx install ai-rulez

ai-rulez init
ai-rulez generate
ai-rulez validate --strict

ai-rulez generate --watch                # regenerate on every change to .ai-rulez/
ai-rulez generate --check                # CI: exit 2 when committed outputs differ from the sources
ai-rulez doctor                          # read-only diagnostics: drift, removed presets, missing tools
ai-rulez generate --user                 # the same, for your home directory (~/.claude, ~/.codex, ...)

Prefer the project-level .config/ convention? ai-rulez also discovers .config/ai-rulez/, and ai-rulez init --config-dir .config/ai-rulez scaffolds it.

Bundle and publish

Bundling and publishing need a [plugin] block (name, version and description) in config.toml:

ai-rulez generate --plugin               # plugin bundles and a marketplace index from the [plugin] block
ai-rulez export okf                      # an OKF bundle of your rules, context and skills (docs/okf)
ai-rulez publish --emit agent-plugins --emit ard --dry-run
ai-rulez publish --to github-release --execute --yes

publish runs a preflight first (validate --strict, lock --check, verify --plugin, a secret scan and the policy gates), writes a byte-reproducible tar.gz with SHA256SUMS, and uploads only when you pass --execute --yes. See Publish and Authoring plugins.

Pi packages are opt-in with [plugin] runtimes = ["pi"]: skills and prompt templates can be installed from Git or npm. Publishing to npm preserves Pi and OpenCode runtime metadata while using the configured scope and plugin name for the released package.

verify --plugin reports a hand-edited or stray file in a bundle as drift, and generate --plugin restores it:

Validate

ai-rulez validate                        # config plus content checks, exit 2 on findings
ai-rulez validate --explain AR001        # what a rule checks and how to suppress it
ai-rulez validate --format sarif --output ai-rulez.sarif
ai-rulez validate --path catalog --glob "plugins/**/*.json"   # also lint files outside .ai-rulez/
ai-rulez validate --outputs              # also lint the generated files; each problem is reported once
ai-rulez validate --strict               # in any repo: with no config it lints AGENTS.md, SKILL.md, .claude/, .agents/
ai-rulez okf validate docs/okf           # lint any OKF bundle, ai-rulez's or a third party's
ai-rulez generate --check                # generated files still match their sources

Govern

ai-rulez lock                            # pin remote includes, installed skills and authored content
ai-rulez approve --list                  # what still needs a reviewer's approval
ai-rulez sign --lock                     # a Sigstore bundle (DSSE over an in-toto statement) for the lock
ai-rulez verify --attestation            # check it offline against the [signing] policy
ai-rulez sbom -o ai-bom.cdx.json         # CycloneDX 1.6 (or --type spdx-json)

An organization policy sets tighten-only floors a repository cannot loosen. See the trust model.

Operate

• MCP server. ai-rulez mcp lets an assistant manage the configuration; with --serve-skills one server serves skills on demand and the config tools together (--read-only keeps only the read-only tools). See MCP server. Served skills cost nothing until an assistant asks for them:

• Monorepos. Nested roots each carry their own .ai-rulez/; generate --recursive and validate --recursive walk them all, and tokens --budget gates what every session loads. See Monorepos.

• Telemetry. Item-load records with an optional OTLP export. See telemetry.

• Evals and improve. ai-rulez eval scores skills; improve (experimental) optimizes them behind a held-out eval gate. See evals and improve.

• Judge. ai-rulez judge reviews skills, agents, commands, rules, CLAUDE.md, AGENTS.md, MCP and settings files with models, from the command line alone: security, quality and governance reviewers, a verifier that checks quoted evidence, an independent adjudicator, and scores computed in code. Failed rubric criteria without a verifiable quote are reported separately as unit-level findings. Governance reads the rules and CLAUDE.md files that apply to each unit, nested .claude/ directories at any depth. ai-rulez judge --estimate, then --allow-llm to send; --changed=origin/main for a pull request, --format sarif for code scanning. See judge.

• Cost and inventory. tokens, cost, catalog and search report what the configuration contains and costs.

• Session exposure. exposure reports what a Claude Code session loads at its start and gates it with [exposure] start_budget; with an [exposure] area map, exposure leakage and exposure collisions find area terms in start-of-session text and overlapping skill listings. See Session exposure.

Existing project on 4.x? Run ai-rulez migrate v5 --dry-run, then see Migrating to v5.

Documentation

Full documentation at goldziher.github.io/ai-rulez. For how a source becomes generated files, and the package map, see Architecture.

Git Hooks

ai-rulez supports multiple pre-commit hook harnesses.

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Goldziher/ai-rulez
    rev: v5.9.0
    hooks:
      - id: ai-rulez-recursive   # generate: write outputs for every nested .ai-rulez/ root
      - id: ai-rulez-validate    # validate --recursive: content, security and link checks

Every hook runs scripts/pre-commit/run-ai-rulez.sh and triggers only on root or nested .ai-rulez/ changes:

Add ai-rulez-plugin-generate and ai-rulez-plugin-verify too if the repository ships plugin bundles; the --if-configured flag makes them no-ops on consumer-only repositories.

Add ai-rulez as a managed source in your existing poly.toml and select the hooks your repository needs:

[[hooks.sources]]
id = "ai-rulez"
git = "https://github.com/Goldziher/ai-rulez.git"
revision = "v5.9.0"
hooks = ["ai-rulez-recursive", "ai-rulez-plugin-verify"]

The source also provides ai-rulez-validate, ai-rulez-generate, and ai-rulez-plugin-generate. Plugin hooks use --if-configured, so they skip consumer-only repositories that do not contain a producer [plugin] or multi-member [marketplace] block.

Resolve and commit the source lock, then install the Git shims:

poly hooks update
git add poly.toml poly-hooks.lock
poly hooks install

Add to lefthook.yml:

pre-commit:
  commands:
    ai-rulez:
      glob: ".ai-rulez/**"
      run: ai-rulez generate --recursive --no-local

Hooks run on each developer's machine and would otherwise load that developer's gitignored config.local.toml overlay and .ai-rulez/local/ content. Pass --no-local (also accepted by validate and tokens) where a hook should see only the shared configuration, as a teammate or CI does. If you do not, generate still refuses to write local-derived changes into tracked shared files; never add --allow-local-drift to a hook. See Poly hooks guide.

In a monorepo, ai-rulez generate --recursive and ai-rulez validate --recursive process every nested .ai-rulez/ root, report all failures, and exit non-zero if any root failed.

Or run ai-rulez init --setup-hooks while initializing a repo to wire hooks in automatically.

GitHub Actions

ai-rulez ships its own composite Action (action.yml at the repository root), so any workflow can uses: Goldziher/ai-rulez@<ref> directly — no subpath. It downloads a release binary, verifies its sha256 against the release's checksums.txt, caches it (keyed by OS, arch and the resolved version) and adds it to PATH. No Go toolchain, Node or Python needed in the job. It reuses the same scripts/pre-commit/run-ai-rulez.sh download-and-verify logic the pre-commit hooks above use, so the two stay in sync.

Use Goldziher/ai-rulez@v5 for compatible action updates: publishing a stable v5 release moves this annotated floating tag after all distribution jobs succeed. uses: Goldziher/ai-rulez@v5 with version: latest keeps a workflow on the newest 5.x action and the newest released CLI with no per-release edits. Pin a full release tag or commit SHA to fix the action code. The action ref and installed CLI version are independent: set version as well to pin the binary; its default latest can eventually select a newer major release.

name: ai-rulez
on:
  pull_request:
  push:
    branches: [main]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Goldziher/ai-rulez@v5
        with:
          version: 5.9.0   # pin the CLI independently of the floating action ref
      - run: ai-rulez generate --check   # the committed output matches the sources
      - run: ai-rulez validate --strict  # content and security checks, warnings fail
      - run: ai-rulez lock --check        # pins were updated when the sources were

uses: Goldziher/ai-rulez/check@v5 installs the CLI the same way and runs the whole governance gate per configuration root: migrate okf --check, validate --strict --no-local, lock --check, generate then generate --check, optionally verify --plugin and tokens --budget, then a clean git diff HEAD with no new untracked files. expected-config-count fails a run that finds a different number of roots, and a job summary lists every command. See the check sub-action. uses: Goldziher/ai-rulez/update@v5 on a schedule runs ai-rulez update when lock --outdated reports an allowed update, regenerates, re-pins the content and opens a pull request with the outdated table (or pushes directly with direct: true). See scheduled pin updates.

For model-backed reviews, configure llm-model, llm-allow-network: 'true' and spend limits, pass provider credentials through env: on the command step or job, and run ai-rulez judge --allow-llm. Installation itself makes no model requests. See the action guide for all inputs, environment precedence, Bedrock, outputs and complete examples.

See CI usage for the lock-check-vs-generate-check distinction and a scheduled "outdated sources" report job.