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.

Features

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

Feature	What it does	Commands / configuration	Docs
Content authoring	Manage rules, context, skills with scripts and references, agents, commands and code-review checks.	init, add, edit, show, list, remove	Configuration, Skills, Checks
Open-standard sources	Use .ai-rulez/ as an OKF bundle, or author in AGENTS.md and .agents/ without generation overwriting that source. Convert a pre-OKF content tree in place.	source = "agents", migrate okf, export okf, import okf, okf validate	OKF, Agents source
Domains, profiles and roles	Organize content by domain, select domains by profile, and compose roles that filter items and control skill modes.	domain, profile, roles, --profile, --role	Domains and profiles, Roles
Configuration layers and local overrides	Merge named TOML layers, a developer's local overlay and user-level settings; inspect the effective local changes.	config layers, local, config.<name>.toml, --no-local	Layers, Local configuration
Shared includes and skill installation	Reuse local or Git content, choose merge precedence, install individual skills and load skill sources with pinned revisions or version ranges.	include, skill install/list/remove/update, includes, installed_skills, skill_sources	Includes, Installed skills
Builtin content	Select bundled domains and individual guidance items, or exclude items from a selected pack.	builtins list/show, builtins	Builtin domains
Import and migration	Convert existing harness files and supported third-party layouts with a lossiness report; migrate a 4.x configuration to v5.	convert, migrate v5	Conversion, Migration
Native generation	Render the file layouts, frontmatter and settings of 52 built-in harnesses, including Claude Code, Cursor, Codex, Copilot and Gemini CLI.	generate, presets	Harness matrix
Custom presets	Define templates or provider-backed presets for an additional harness and its supported content and settings.	presets inline tables, provider specs	Custom presets, Provider-backed presets
Hooks, permissions and MCP settings	Translate shared hooks, allow/deny rules and MCP server definitions to each harness's supported native settings; report unsupported translations.	hooks, permissions, mcp_servers	Settings, Permissions
Generated-file guard	Install a supported harness's PreToolUse hook to block agent edits to generated files.	[guard] generated = true, guard	Guard
User scope and monorepos	Generate user-level assistant configuration, watch source changes, or process nested project roots with ordered reports.	generate --user, generate --watch, generate/validate --recursive	User scope, Monorepos
Drift, cleanup and diagnostics	Preview a generation plan, detect output drift, remove generated files and diagnose configuration, locks, tools and MCP placeholders.	generate --dry-run/--emit-plan/--check, clean, doctor	CLI reference, Architecture
Plugin and marketplace authoring	Bundle runtime-specific plugins and marketplace indexes, including multi-plugin definitions, Agent Plugins and opt-in Pi packages.	generate --plugin, plugin, plugins_authoring, marketplaces_authoring	Plugins, Agent Plugins
Discovery and documentation formats	Generate AGENTS.md and llms.txt; emit ARD manifests and experimental MCP Server Cards.	agents_md, llms-txt preset, publish --emit, publish emit	AGENTS.md, llms.txt, ARD, MCP Server Cards
Release artifacts and publishing	Build reproducible archives, manifests and checksums, optionally sign them, verify a dist directory and explicitly upload to GitHub releases, npm or OCI.	publish, publish verify, --to, --execute --yes	Publishing
Static validation and security scanning	Check config, content, scripts and conventional harness files with stable AR codes, without requiring an ai-rulez config. Scope by paths, globs or Git changes; use fixes, suppressions, baselines and JSON/SARIF reports.	validate, scan, --strict, --path, --glob, --outputs, --changed	Validation and security rules, Harness traps
External scanners	Run configured scanner programs with explicit execution/egress controls and merge their findings into validation reports.	lint.external, scanners list/doctor, validate/scan --external	Scanner integrations
Repository verifiers	Run declared deterministic checks, opt into command or LLM predicates, link checks to rules, test fixtures and calibrate model-backed checks.	verifiers run/list/explain/test/calibrate/suggest, validate --verifiers	Verifiers
Model-based judge	Review agent configuration for security, quality and governance with quoted evidence, an adjudicator, rubric skills, change-impact selection and explicit incomplete coverage. Estimate before sending; cap spend and emit JSON or SARIF.	judge, --estimate, --allow-llm, --changed, --skill, --fail-on	Judge
Rubric review and patch proposals	Score configured items offline or with a semantic model, calibrate a rubric's gate and propose verified patches for findings.	review, review calibrate/explain/fix, rubric	Review
Skill evaluation	Run harness-neutral eval cases through adapters; measure pass rate, trigger precision/recall, ablation and cost; import scenarios and calibrate estimates.	eval run/import/calibrate-estimate	Evals
Skill improvement (experimental)	Run an external optimizer on a copy, gate candidates against held-out evals, inspect results, apply an accepted change or open an isolated PR.	improve run/show/apply/pr/clean/adapters	Improve
Locks and source updates	Pin remote sources, installed skills, authored content and outputs; check drift, inspect outdated sources and update version-range pins.	lock, lock --check/--diff/--outdated, update, skill update	Lock file
Organization policy	Apply central floors for sources, approvals, signatures, execution and model use that repository settings cannot loosen.	--policy, AI_RULEZ_POLICY, validate --show-policy	Policy, Trust model
Reviewer approvals	Bind approvals to content digests, review diffs, revoke or deny content, enforce authorized reviewers and verify signed approvals.	approve, verify --approvals	Approvals
Signatures and attestations	Sign locks, bundles, skills, SBOMs and policies; verify Sigstore bundles, in-toto/DSSE attestations and publisher provenance.	sign, verify --attestation/--self/--plugin, trust update	Signing
Software bills of materials	Inventory AI content, dependencies and MCP packages in CycloneDX 1.6 or SPDX 2.3; detect SBOM drift and enforce lock and pin gates.	sbom, sbom --check -o <file>, --require-lock, --strict-pins, --type spdx-json	SBOM
MCP management and skill serving	Expose configuration tools and reports to assistants; serve skills and supporting resources on demand with role filters and session budgets. Select a read-only server or reuse a local daemon.	mcp, --serve-skills, --read-only, --daemon	MCP server
Skill search	Rank skills lexically, by vectors or with hybrid embeddings, maintain the index, evaluate ranking and mine queries from usage.	search, search index/status/mine, search --eval	Search
Catalog and inventory	Inspect item metadata, owners, roles, dependencies and lock status; join eval/usage results, compare catalogs and build a static catalog website.	catalog, catalog diff, catalog --html	Catalog
Token and context budgets	Report generated prompt tokens, compare profiles and roles, identify costly content and gate always-loaded or on-demand budgets.	tokens, cost, --budget, --on-demand-budget	Token reports, Cost reports
Usage and item-load telemetry	Opt into identifier-only skill invocation, feedback and item-load records; report usage and optionally export item-load telemetry through OTLP.	telemetry record/report/feedback/enable/export	Usage telemetry, Item loads and OTLP
Shared model access	Route model calls through liter-llm, including AWS Bedrock credential refresh and OpenAI-compatible gateways, with network consent, budgets, authenticated caching and redacted diagnostics.	[llm], llm doctor, llm estimate	LLM access
Automation and embedding	Use the composite GitHub Action, pre-commit/prek, Poly or Lefthook; call the experimental Go API to load, validate, plan/apply generation and manage locks. Shell completion and JSON schemas support other integrations.	Action, init --setup-hooks, completion, pkg/airulez	Git hooks, GitHub Actions, Go API, Schemas

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

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

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

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 (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:

Validate

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

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.4.1
    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.4.1"
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.

Use Goldziher/ai-rulez@v5 for compatible action updates: publishing a stable v5 release advances this floating tag after all distribution jobs succeed. 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.

Input version	X.Y.Z, vX.Y.Z, or latest (default). Optional — omit it to always use the newest release.
Inputs llm-*	Optional provider, model, gateway, credential variable name, network opt-in, budgets and other LLM settings exported to later steps. Full reference.
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@v7
      - uses: Goldziher/ai-rulez@v5
        with:
          version: 5.4.1   # 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

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.