AI-Rulez Documentation¶

AI-Rulez is a standards-compliant lifecycle tool for agent knowledge and capabilities. Keep your rules, context, skills, agents, commands, hooks, permissions and MCP servers in one source of truth, .ai-rulez/, and take them through every stage:

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

The claim is "standards compliant": each format ai-rulez names is checked against that standard's own schema or rules. Standards lists the pinned spec versions, the conformance tests and the known gaps.

The lifecycle¶

Section	What you do	Start with
Author	Write rules, context, skills, agents and checks as markdown; organize them 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; `ai-rulez migrate okf` converts it.	Configuration, Rules, Skill frontmatter
Generate	Render native files for 52 harnesses, per project or per user, with hooks and permissions translated for each.	Supported harnesses, AGENTS.md, User-level configuration
Bundle and publish	Package plugin bundles, Agent Plugins and ARD manifests, then release them to GitHub, npm, OCI and marketplaces.	Authoring plugins, Agent Plugins, ARD, Publish
Validate	Lint configured projects or existing harness files without a config; run content and security checks with stable `AR` codes, deterministic verifiers and per-standard validators. Review changed units with evidence-verified security, governance and quality findings.	Strict validation, Verifiers, Judge
Govern	Pin content in a lock, record reviewer approvals, sign with Sigstore, set an organization policy and ship an SBOM.	Trust model, Lock file, Signing, SBOM
Operate	Serve configuration and skills over MCP, search the catalog, export telemetry, run evals and improve skills.	MCP server, Search, Telemetry, Evals, Improve
Embed	Load projects, validate, plan or apply generated files and manage locks through the Go API, with directory, memory and Git snapshot workspaces.	Embedding (Go API)

Get started¶

Install ai-rulez (pnpm dlx ai-rulez@latest needs no install).
Follow the Quick Start: ai-rulez init, pick presets, ai-rulez generate.
Run ai-rulez validate --strict, then commit .ai-rulez/ together with the generated files.

ai-rulez init "my-project"
ai-rulez generate
ai-rulez validate --strict

Coming from 4.x? Run ai-rulez migrate v5 --dry-run and read Migrating to v5.

Project layout¶

project-root/
├── .ai-rulez/
│   ├── config.toml           # Presets, profiles, lifecycle settings
│   ├── rules/                # Mandatory constraints
│   ├── context/              # Reference documentation
│   ├── skills/               # Skills (SKILL.md)
│   ├── agents/, commands/    # Subagents and slash commands
│   ├── checks/               # Code-review guidelines
│   └── domains/              # Team or subsystem content
├── CLAUDE.md                 # Generated for Claude (rules go to .claude/rules/)
├── .cursor/rules/            # Generated for Cursor
├── GEMINI.md                 # Generated for Gemini
└── .github/copilot-instructions.md

Generated files are committed by default. Set gitignore = true to keep them out of git through a managed .gitignore block instead.

Reference¶

CLI commands: every command and flag; ai-rulez --help and ai-rulez <command> --help are authoritative.
Schema: the JSON schemas of the configuration and of every --format json document.
Embedding (Go API): use ai-rulez as a library.
Changelog.

Getting help¶

CLI help: ai-rulez --help, ai-rulez generate --help, and so on.
Rule explanations: ai-rulez validate --explain AR001.
Diagnostics: ai-rulez doctor reports drift, removed presets and missing tools without changing anything.
Issues: report problems on GitHub.

This documentation covers ai-rulez v5 (version = "5.0" in config.toml).