ai-rulez
A complete development workflow for AI coding tools
Documentation · Quick Start · Examples
The Problem
Every AI coding tool wants its own config: Claude needs CLAUDE.md, Cursor wants .cursor/rules/, Copilot expects .github/copilot-instructions.md. Each has different formats, frontmatter, and directory conventions. If you use more than one tool, you're maintaining duplicate rules that inevitably drift apart.
The Solution
Write your rules, context, skills, agents, and commands once in .ai-rulez/. Run generate. Get native configs for every tool you use.
npx ai-rulez@latest init && npx ai-rulez@latest generate
Prefer the project-level .config/ convention? ai-rulez auto-discovers .config/ai-rulez/ as well, and ai-rulez init --config-dir .config/ai-rulez scaffolds it.
ai-rulez generates correct, tool-native output for 14 platforms: Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Continue.dev, Codex, OpenCode, Hermes, Amp, Junie, Antigravity, and Xum. Each preset respects the target tool's conventions — proper frontmatter, directory structure, file extensions, agent formats.
For a tool that isn't built in, a custom preset can point at a declarative provider spec (provider = ".ai-rulez/providers/my-tool.toml") and get the same full feature set as a built-in — root instructions file, skills/agents/commands, per-agent frontmatter, and MCP sidecars. See Custom Presets.
Generate Plugins, Not Just Config
ai-rulez doesn't only write config into your repo — it also packages your project as distributable plugins. Run ai-rulez generate --plugin and the same .ai-rulez/ source (skills, commands, agents, MCP servers) becomes installable plugin bundles and a marketplace index for Claude, Cursor, Codex, Gemini, Kimi, OpenCode, Factory, and Hermes Agent. An opt-in Agent Plugins runtime (runtimes = ["agent-plugins"]) additionally emits portable Agent Plugins 1.0.0 packages.
ai-rulez generate --plugin # write plugin bundles + marketplace.json
ai-rulez generate --plugin --dry-run # preview
ai-rulez verify --plugin # prove committed output matches its sources
Write MCP launch commands and hooks once with the canonical ${PLUGIN_ROOT} variable — a hook either runs a command already on the consumer’s machine or bundles a project script into the plugin’s hooks/ directory, so it works in a fresh clone — and each runtime gets its own manifest with the variable and hook format rewritten to fit. Hermes generation emits both a project plugin and a buildable Python entry-point package. Use plugin.content_root to keep distributable skills separate from contributor governance. Supports single-plugin repos and monorepos ([marketplace].members), plus a Claude statusline passthrough. See Authoring Plugins.
What Ships Out of the Box
ai-rulez isn't just a config generator. It ships with 33 builtin domains containing opinionated rules, skills, agents, and workflows that establish a professional development baseline immediately.
Auto-Included Domains
Set builtins in your config — true for every domain, or a list to pick — and these seven come along
without being named, unless you exclude one with !. Omit the builtins field entirely and no builtin
content is loaded at all.
Each one ships always-on content (rules, or context such as the agent roster), inlined into
CLAUDE.md and so read on every request, and some also ship on-demand skills, whose body costs
nothing until the assistant loads it.
| Domain | Always-on rules | On-demand skills |
|---|---|---|
| ai-governance | No AI signatures in commits. Concise communication. Read before write. Minimal changes. Systematic debugging. Verification before claiming success. Critical review of subagent output. Reasoning stated for non-obvious decisions. | — |
| git-workflow | Atomic commits. Conventional commit messages. Safe operations. Branch hygiene. | — |
| security | Secrets handling. Input validation. Least privilege. | owasp-quick-reference, dependency-awareness |
| token-efficiency | Context preservation. Output awareness. | task-runner, incremental-approach |
| testing | Tests ship with the behaviour change; failing test before a bug fix; full suite before committing. | tdd-workflow, testing-conventions |
| code-quality | — | code-quality-standards, error-handling |
| agent-delegation | Multi-agent coordination and delegation patterns (emitted as context). | — |
Builtin Agents
Specialized agents ready to use as subagents:
| Agent | Domain | Model | What it does |
|---|---|---|---|
| code-reviewer | ai-governance | sonnet | Reviews changes for correctness, security, and conventions. Reports by severity. |
| test-writer | testing | sonnet | Writes tests following strict TDD. Fails first, then implements. |
| security-auditor | security | sonnet | Audits dependencies, scans for CVEs, reviews input validation. |
| docs-writer | ai-governance | sonnet | Writes clear, concise documentation. No fluff. |
| devops-engineer | cicd | sonnet | CI/CD pipelines, GitHub Actions, Docker, deployment automation. |
| release-engineer | cicd | sonnet | Version management, changelogs, multi-registry publishing. |
| ffi-engineer | polyglot-bindings | sonnet | Native FFI and cross-language binding work. |
| polyglot-architect | polyglot-bindings | opus | Cross-language architecture and binding design. |
Opt-in Domains
Enable these based on your stack:
Languages (10): rust, python, typescript, go, java, ruby, php, elixir, csharp, r
Bindings (10): pyo3, napi-rs, magnus, ext-php-rs, rustler, wasm, jni-rs, extendr, cgo, vite-plus
Operational: cicd, docker, observability, documentation, polyglot-bindings, default-commands
# .ai-rulez/config.toml
builtins = ["rust", "python", "pyo3", "cicd", "docker", "default-commands"]
Anything scoped to one technology or one activity is emitted as an on-demand Agent Skill
(.claude/skills/<id>/SKILL.md) rather than inlined into CLAUDE.md, so the always-loaded file stays
small and the guidance arrives only when it is relevant: every language and binding domain,
polyglot-bindings, security's OWASP and dependency references, all of code-quality, most of
testing, token-efficiency's task-runner and incremental-approach, and the whole of docker and
observability. What stays inline is behavioural governance that has to land before the first file is
read — ai-governance, git-workflow, security's secrets and boundary rules, and the one testing
rule that says tests ship with the change. !domain and !domain/name exclusions work for skill
entries too, so an exclusion written against a rule keeps working after it becomes a skill.
Content Types
| Type | Purpose | Example |
|---|---|---|
| Rules | What AI must/must not do | Security standards, coding conventions |
| Context | What AI should know | Architecture docs, domain knowledge |
| Skills | Reusable prompts and workflows | Deployment checklist, review protocol |
| Agents | Specialized AI personas | Code reviewer, performance engineer |
| Commands | Slash commands across tools | /review, /deploy, /test |
Organization at Scale
ai-rulez scales from solo projects to large organizations:
Domains — Group content by feature, language, or team:
.ai-rulez/domains/backend/rules/
.ai-rulez/domains/frontend/rules/
Profiles — Generate different configs for different audiences:
[profiles]
backend = ["backend", "database"]
frontend = ["frontend", "ui"]
Remote Includes — Share rules across repositories:
[[includes]]
name = "company-standards"
source = "https://github.com/company/ai-rules.git"
merge_strategy = "local-override"
Include sources can use a bare/flattened layout — expose rules/, context/, skills/, agents/
directly (at the repo root or a sub-path via path = "modules/core") with no .ai-rulez/ wrapper.
Recommended for shared, skill-first modules.
Native rules folders — Rules are written to each tool's own rules folder (.claude/rules, .cursor/rules, .github/instructions, .windsurf/rules, ...) with native paths/globs frontmatter, so path-scoped rules load only when relevant. split is the default since 4.22.0; set [rules] mode = "inline" to keep rules in the root files. See docs/rules.md.
Local overrides — Personal, machine-local instructions that never get committed:
ai-rulez add rule my-scratch-notes --local # → .ai-rulez/local/rules/, generates CLAUDE.local.md
.ai-rulez/local/ and the generated *.local.md outputs are gitignored unconditionally. See
docs/local-overrides.md.
Reasoning effort across providers — Tune how hard each AI tool thinks:
# .ai-rulez/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews code for security regressions
effort: high
---
# .ai-rulez/config.toml
[defaults]
effort = "medium" # global default for every supported preset
[defaults.effort_by_preset]
codex = "high" # overrides the global default for Codex
claude = "xhigh" # …and for Claude
Accepted values: low, medium, high, xhigh, max, inherit. ai-rulez emits the right field per preset:
- Claude —
effortin.claude/agents/*.mdfrontmatter (per-agent) - Codex —
model_reasoning_effortin.codex/config.tomland.codex/agents/*.toml - Amp —
amp.anthropic.effortin.amp/settings.json(global) - Windsurf —
reasoning_effortin.windsurf/agents/*.mdfrontmatter (per-agent) - Opencode —
variantin.opencode/agents/*.mdfrontmatter (per-agent); joins the agent'smodelasmodel#variant - Xum —
ai.thinkingLevelin.xum/agents/*.mdfrontmatter (per-agent)
Each preset maps the value to its own vocabulary; tools without a documented config surface (Cursor, Copilot, Gemini, etc.) are silently skipped. See docs/configuration.md for the full mapping table.
Per-preset model selection for subagents — Model strings differ per provider, so the same agent can declare a different model for each preset it targets:
# .ai-rulez/agents/research-helper.md
---
name: research-helper
description: Multi-provider research subagent
claude_model: opus
copilot_model: gpt-5
cursor_model: claude-3.7-sonnet
---
# .ai-rulez/config.toml — project-wide defaults
[defaults.model_by_preset]
claude = "sonnet" # used when an agent doesn't set its own claude_model
copilot = "gpt-5"
Per-agent <preset>_model wins over defaults.model_by_preset; the legacy single model: field on an agent is the lowest-priority fallback for backward compatibility.
Installed Skills — Pull reusable skills from external repos:
[[installed_skills]]
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"
Committing generated output — every generated file carries a Content-Hash and a Source-Hash line. Source-Hash covers the whole source set, so editing one skill rewrites a line in every generated file. If you commit the output, keep headers stable:
[header]
hashes = "content" # "full" (default) | "content" (Content-Hash only) | "none"
MCP Server
ai-rulez includes a built-in MCP server with 36 tools that lets AI assistants manage their own governance. Add rules, update context, generate configs — all programmatically.
[[mcp_servers]]
name = "ai-rulez"
command = "npx"
args = ["-y", "ai-rulez@latest", "mcp"]
Or let generate add it for you. With [mcp] self_server = true the entry is merged into the project .mcp.json, pinned to the running ai-rulez version, without touching hand-authored servers or .claude/settings.json:
[mcp]
self_server = true
Installation
No install needed — npx ai-rulez@latest <command> works out of the box. Pick a permanent option below:
Homebrew (macOS / Linux)
brew install goldziher/tap/ai-rulez
npx (no install)
npx ai-rulez@latest <command>
npm (global)
npm install -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
pre-commit hook
Add to .pre-commit-config.yaml:
repos:
- repo: https://github.com/Goldziher/ai-rulez
rev: v4.22.1
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 AI-Rulez 4.9.0+ and Poly 0.14.0+:
[[hooks.sources]]
id = "ai-rulez"
git = "https://github.com/Goldziher/ai-rulez.git"
revision = "v4.22.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
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
In a monorepo, ai-rulez generate --recursive and ai-rulez validate --recursive (-r) 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 4.22.1
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-4.22.1.tar.gz | 19.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ai_rulez-4.22.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 32.1 kB
Release files / ai_rulez-4.22.1.tar.gz
| Download URL | ai_rulez-4.22.1.tar.gz |
|---|---|
| Size | 19.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
95797474e0f1ae19cf9d8f825e53a44ea9d8ef6fe8054a24f2df261e05d6ce6f
|
|
BLAKE2b-256 checksum How to use checksums |
603328bc33dfd52fabf2309ab7440118c47b38fb7488ee5d40cd3a6ea675b7ff
|
| 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 3, 2026.
Transparency logRelease files / ai_rulez-4.22.1-py3-none-any.whl
| Download URL | ai_rulez-4.22.1-py3-none-any.whl |
|---|---|
| Size | 12.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b509e4c1b6a66c6f5eb54ca8d274a74d9c69ed5001f51dd42060b089854d418
|
|
BLAKE2b-256 checksum How to use checksums |
229f3f35fecdaad0343bdd9d81d58d0511587e482e86b48a521b00672b25b7e3
|
| 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 3, 2026.
Transparency log
