ai-rulez
The standards-compliant lifecycle tool for agent knowledge and capabilities: author, generate, bundle, validate, govern, publish
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
| 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. |
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. |
validate, scan, 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 |
Standards
The claim is "standards compliant", so each format ai-rulez names is generated or bundled from the same sources and checked against that standard's own schema or rules. 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 | supported | generate |
validate |
| llms.txt | supported | the llms-txt preset |
validate |
| MCP server config | supported | generate |
validate (partial) |
| MCP server card | planned | not generated | none |
| 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 | spec to be confirmed | spec to be confirmed |
Quick start
pnpm dlx ai-rulez@latest init # author: scaffold .ai-rulez/ with config.toml
# .ai-rulez/config.toml
presets = ["claude", "cursor", "codex", "copilot", "gemini"] # any of the 52 harnesses
pnpm dlx ai-rulez@latest generate # generate: write native files for each preset
pnpm dlx ai-rulez@latest validate --strict # validate: content and security checks, warnings fail
pnpm dlx ai-rulez@latest lock # govern: pin includes, skills and authored content in ai-rulez.lock
pnpm dlx ai-rulez@latest export okf # bundle: an OKF bundle of your knowledge in docs/okf
Day-to-day:
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.
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 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 mcplets an assistant manage the configuration; with--serve-skillsit serves skills on demand. See MCP server. - Telemetry. Item-load records with an optional OTLP export. See telemetry.
- Evals and improve.
ai-rulez evalscores skills;improve(experimental) optimizes them behind a held-out eval gate. See evals and improve. - Cost and inventory.
tokens,cost,catalogandsearchreport what the configuration contains and costs.
Existing project on 4.x? Run ai-rulez migrate v5 --dry-run, then see Migrating to v5.
Installation
No install needed — pnpm dlx ai-rulez@latest <command> works out of the box. Pick a permanent option below:
Homebrew (macOS / Linux)
brew install goldziher/tap/ai-rulez
pnpm dlx (no install)
pnpm dlx ai-rulez@latest <command>
npm (global)
pnpm add -g ai-rulez
uvx (no install)
uvx ai-rulez <command>
uv tool
uv tool install ai-rulez
pip / pipx
pip install ai-rulez
# or, isolated:
pipx install ai-rulez
Go
go install github.com/Goldziher/ai-rulez/v5/cmd/ai-rulez@latest
The module path needs /v5; without it @latest resolves to an old build.
pre-commit hook
Add to .pre-commit-config.yaml:
repos:
- repo: https://github.com/Goldziher/ai-rulez
rev: v5.0.0
hooks:
- id: ai-rulez-recursive # generate outputs across the repo
- id: ai-rulez-validate # dry-run validation
Available hook ids: ai-rulez-validate, ai-rulez-generate,
ai-rulez-recursive, ai-rulez-plugin-generate, and
ai-rulez-plugin-verify. They trigger on root or nested .ai-rulez/ changes.
poly hook source
Add ai-rulez as a managed source in your existing poly.toml and select the hooks your
repository needs. This requires Poly 0.14.0+; pin revision to the AI-Rulez release you want (the
hooks run that release):
[[hooks.sources]]
id = "ai-rulez"
git = "https://github.com/Goldziher/ai-rulez.git"
revision = "v5.0.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
See the Poly hooks guide for local sources, machine install preferences, hook behavior, and the producer catalog.
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.
Documentation
Full documentation at goldziher.github.io/ai-rulez.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for ai-rulez 5.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ai_rulez-5.0.2.tar.gz | 16.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ai_rulez-5.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 26.6 kB
Release files / ai_rulez-5.0.2.tar.gz
| Download URL | ai_rulez-5.0.2.tar.gz |
|---|---|
| Size | 16.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a14ea0389898f9d48c4d7f815d3e04e81806140f88d961f489305abfe7a0dbd2
|
|
BLAKE2b-256 checksum How to use checksums |
b07634c201afc1dd69ee546afcd1d8581d41916f482b7a8b0877c4f2bbfde306
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / ai_rulez-5.0.2-py3-none-any.whl
| Download URL | ai_rulez-5.0.2-py3-none-any.whl |
|---|---|
| Size | 10.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
915ec2f39315a935d9261e192646663c9b51a2c5fe1fc530387b7ec833ba1691
|
|
BLAKE2b-256 checksum How to use checksums |
6ee834109c7b724265354ca43338d96667d6a1946535f3e13acca47d96959754
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency log
