ai-rulez

AI-Rulez

The standards-compliant lifecycle tool for agentic governance

Documentation · Quick Start · Examples

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.

Stage	What happens	Commands	Docs
Author	Rules, context, skills, agents, commands and checks as markdown in `.ai-rulez/`, with domains, profiles, roles and includes. `.ai-rulez/` is an OKF bundle: OKF is the internal format, and `init`, `add` and the MCP tools write it. A pre-OKF tree still loads, with a deprecation notice; `migrate okf` converts it. Or keep `AGENTS.md` and `.agents/` as the source with `source = "agents"`: ai-rulez translates them to every other tool and never writes into them (guide).	`init`, `add`, `convert`, `import`, `migrate okf`	Author
Generate	Native files for 52 harnesses (Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Devin, Kilo and more), per project or per user.	`generate`, `doctor`, `clean`	Harnesses
Bundle	Distributable plugin bundles, an Agent Plugins package, an OKF bundle, an ARD manifest, `AGENTS.md` and `llms.txt`.	`generate --plugin`, `export okf`	Plugins
Lint and validate	Content and security checks with stable `AR` codes, plus each standard's own schema or rules. Works in a repository with no ai-rulez config (`--path`, `--glob` and `--outputs` pick what to lint); `judge` grades instruction files with a model, also without config.	`validate`, `scan`, `judge`, `okf validate`, `verify`	Validate
Govern	A content-pinning lock, reviewer approvals, Sigstore signing, an organization policy and an SBOM.	`lock`, `approve`, `sign`, `verify --attestation`, `sbom`	Trust model
Publish	Reproducible, checksummed release artifacts to GitHub releases, npm, OCI and marketplaces.	`publish`	Publish

ai-rulez init and generate: one .ai-rulez source becomes the native files of four AI tools

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.

All 52 supported tools

Preset	Tool
`aiassistant`	JetBrains AI Assistant
`amp`	Sourcegraph Amp
`antigravity`	Google Antigravity
`augment`	Augment Code
`baz`	Baz
`bob`	IBM Bob
`claude`	Claude Code
`cline`	Cline
`codebuddy`	CodeBuddy Code
`codebuff`	Codebuff
`codewhale`	Codewhale
`codex`	OpenAI Codex
`commandcode`	Command Code
`copilot`	GitHub Copilot
`copilot-cli`	GitHub Copilot CLI
`cortex`	Snowflake Cortex Code
`crush`	Crush
`cursor`	Cursor
`deepagents`	Deep Agents Code
`devin`	Devin CLI
`dsh`	DeepSeek Harness
`factory`	Factory Droid
`gemini`	Gemini CLI
`gitlab-duo`	GitLab Duo CLI
`goose`	goose
`grok`	Grok Build CLI
`hermes`	Hermes Agent
`junie`	JetBrains Junie
`kilo`	Kilo Code
`kimi`	Kimi Code
`kiro`	Kiro
`letta`	Letta Code
`mimocode`	MiMo Code
`muse`	Meta Muse Code
`omp`	oh-my-pi
`openclaw`	OpenClaw
`opencode`	OpenCode
`pi`	pi
`poolside`	Poolside Pool
`qoder`	Qoder
`qwen`	Qwen Code
`reasonix`	Reasonix
`replit`	Replit Agent
`rovodev`	Atlassian Rovo Dev
`takt`	Takt
`trae`	Trae
`vibe`	Mistral Vibe
`warp`	Warp
`xum`	Xum
`zcode`	ZCode
`zed`	Zed
`zoocode`	Zoo Code

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 marked supported when the code generates it and validates it today, and planned when it does not yet. 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.

Standard	Status	Generate / bundle	Lint / validate
OKF (Open Knowledge Format, v0.2), the internal format of `.ai-rulez/`	supported	`export okf`, the `okf` preset	`okf validate`
Agent Plugins (agent-plugins.org)	supported	`generate --plugin`, `publish --emit agent-plugins`	`validate --strict` (AR9O codes)
ARD (Agentic Resource Discovery, a proposal)	supported	`publish --emit ard`	`validate` (entry schema, URN grammar)
Agent Skills (agentskills.io)	supported	`generate`	`validate` (frontmatter checks; partial)
AGENTS.md, also as the source with `source = "agents"`	supported	`generate`	`validate`
llms.txt	supported	the `llms-txt` preset	`validate`
MCP server config	supported	`generate`	`validate` (partial)
MCP server card	partial (experimental extension, pinned `526201b`)	`publish --emit mcp-server-card`, `publish --emit ard`	conformance tests only
CycloneDX / SPDX SBOM	supported	`sbom`	`sbom --check`
in-toto / DSSE / Sigstore	supported	`sign`	`verify --attestation`
OpenTelemetry (OTLP)	supported	`telemetry export --to otlp`	not applicable
"Agent bundle"	planned, no pinned spec	none	none

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 (Node.js, no install)

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

uvx (Python, no install)

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

Homebrew (macOS / Linux)

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.

npm (global)

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

uv tool

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

pip / pipx

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

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

Day-to-day commands

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:

Show commands

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:

ai-rulez verify --plugin reporting changed and extra files in a plugin bundle, then generate --plugin restoring it

Validate

ai-rulez validate --strict flags a defect, --explain describes it, and generate --check fails on drift

Show commands

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

Show commands

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 grades AGENTS.md and .agents/* with a model from the command line alone, with no config file: ai-rulez judge --estimate --model openai/gpt-4o-mini, then --allow-llm to send. See judge.
Cost and inventory. tokens, cost, catalog and search report what the configuration contains and costs.

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.

pre-commit/prek

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Goldziher/ai-rulez
    rev: v5.3.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:

Hook id	Runs
`ai-rulez-generate`	`generate`, the root `.ai-rulez/` only
`ai-rulez-recursive`	`generate --recursive`, every nested root
`ai-rulez-validate`	`validate --recursive` — a real validation run, not a dry run
`ai-rulez-plugin-generate`	`generate --recursive --plugin --if-configured`
`ai-rulez-plugin-verify`	`verify --recursive --plugin --if-configured`

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.

Poly

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

Lefthook

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.


Input `version`	`X.Y.Z`, `vX.Y.Z`, or `latest` (default). Optional — omit it to always use the newest release.
Output `version`	The resolved version, without the leading `v`.
Output `path`	Absolute path to the installed `ai-rulez` binary.

Show workflow

name: ai-rulez
on:
  pull_request:
  push:
    branches: [main]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Goldziher/ai-rulez@v5.2.1   # a release tag from v5.2.0 on carries action.yml; pin the one you reviewed
        # with:
        #   version: 5.2.1   # optional; omit (or "latest") to always use the newest release
      - 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

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

ai ai-assistant ai-rules claude cursor copilot devin baz gemini cline mcp model-context-protocol cli configuration config rules generator golang go development developer-tools automation workflow productivity pre-commit git-hooks code-generation ai-development assistant-configuration monorepo presets agents claude-code codex opencode hooks permissions skills code-review okf agent-plugins ard agent-skills agents-md llms-txt sbom cyclonedx spdx sigstore in-toto supply-chain governance standards

Metadata

Release files for ai-rulez 5.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-rulez 5.3.0
File	Size	Uploaded
ai_rulez-5.3.0.tar.gz	23.2 kB	Oct 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ai-rulez 5.3.0
File	Interpreter	ABI	Platform	Reset
ai_rulez-5.3.0-py3-none-any.whl 14.0 kB Oct 14, 2026	Python 3	none	any	Details

Total release size: 37.2 kB

Release files / ai_rulez-5.3.0.tar.gz

Download URL	ai_rulez-5.3.0.tar.gz
Size	23.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`b8bcc639ebc407fe4dae135a3bc59d328ef989b3ce35eeab11784c56a84e1cfb`
BLAKE2b-256 checksum How to use checksums	`8d1116d70aaadb4183a537135562af71f0c04c72be7b462b7948ca51626701a5`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Goldziher/ai-rulez
Publishing commit: github.com/Goldziher/ai-rulez/tree/5e0bb9e03377f781ecbeac4110ffeac731d0ceef

Workflow

Publishing configuration: github.com/Goldziher/ai-rulez/blob/5e0bb9e03377f781ecbeac4110ffeac731d0ceef/.github/workflows/publish.yaml
Publishing logs: github.com/Goldziher/ai-rulez/actions/runs/38556493072/attempts/1

Artifact

Subject: ai_rulez-5.3.0.tar.gz
SHA-256 checksum: b8bcc639ebc407fe4dae135a3bc59d328ef989b3ce35eeab11784c56a84e1cfb Verifying attestations

Release files / ai_rulez-5.3.0-py3-none-any.whl

Download URL	ai_rulez-5.3.0-py3-none-any.whl
Size	14.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`452b928e5396c9eb4c5f11beae27fe6ada3c3450ff322bfe253dcb3a3140c99d`
BLAKE2b-256 checksum How to use checksums	`3748fde77cd264afba147197c1fe01939233ec41bc96321b0f39ce4e19db275d`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Goldziher/ai-rulez
Publishing commit: github.com/Goldziher/ai-rulez/tree/5e0bb9e03377f781ecbeac4110ffeac731d0ceef

Workflow

Publishing configuration: github.com/Goldziher/ai-rulez/blob/5e0bb9e03377f781ecbeac4110ffeac731d0ceef/.github/workflows/publish.yaml
Publishing logs: github.com/Goldziher/ai-rulez/actions/runs/38556493072/attempts/1

Artifact

Subject: ai_rulez-5.3.0-py3-none-any.whl
SHA-256 checksum: 452b928e5396c9eb4c5f11beae27fe6ada3c3450ff322bfe253dcb3a3140c99d Verifying attestations