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.
```bash
npx ai-rulez@latest init && npx ai-rulez@latest generate
```
ai-rulez generates correct, tool-native output for **20 platforms**: Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Continue.dev, Codex, OpenCode, Hermes, Amp, Junie, Antigravity, and more. Each preset respects the target tool's conventions — proper frontmatter, directory structure, file extensions, agent formats.
## 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.
```bash
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; 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](docs/plugins.md).
## What Ships Out of the Box
ai-rulez isn't just a config generator. It ships with **33 builtin domains** containing opinionated rules, agents, and workflows that establish a professional development baseline immediately.
### Builtin Rules (auto-included)
These activate automatically. No configuration needed.
| Domain | What it enforces |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ai-governance** | No AI signatures in commits. Concise communication. Systematic debugging. Verification before claiming success. Critical review of subagent output. |
| **code-quality** | Anti-patterns prevention. Complexity limits. Dead code removal. Error handling standards. Readability. |
| **testing** | TDD workflow (red-green-refactor, no exceptions). Testing anti-patterns. Meaningful assertions. Test independence. |
| **git-workflow** | Atomic commits. Conventional commit messages. Safe operations. Branch hygiene. |
| **security** | Secrets handling. Input validation. Dependency auditing. Least privilege. |
| **token-efficiency** | Task runner usage. Incremental approach. Context preservation. Batch operations. |
| **agent-delegation** | Multi-agent coordination and delegation patterns. |
### 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 | haiku | Writes clear, concise documentation. No fluff. |
| **devops-engineer** | cicd | haiku | CI/CD pipelines, GitHub Actions, Docker, deployment automation. |
| **release-engineer** | cicd | haiku | Version management, changelogs, multi-registry publishing. |
### 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`
```toml
# .ai-rulez/config.toml
builtins = ["rust", "python", "pyo3", "cicd", "docker", "default-commands"]
```
Language, binding, `polyglot-bindings`, and `security` (OWASP + dependency) conventions are emitted as
**on-demand Agent Skills** (`.claude/skills//SKILL.md`) rather than inlined into `CLAUDE.md`, so the
always-loaded file stays small and the conventions load only when relevant. Always-on rules
(`code-quality`, `testing`, `git-workflow`, `ai-governance`, …) remain inline. `!domain` and
`!domain/name` exclusions work for skill entries too.
## 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:
```text
.ai-rulez/domains/backend/rules/
.ai-rulez/domains/frontend/rules/
```
**Profiles** — Generate different configs for different audiences:
```toml
[profiles]
backend = ["backend", "database"]
frontend = ["frontend", "ui"]
```
**Remote Includes** — Share rules across repositories:
```toml
[[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.
**Local overrides** — Personal, machine-local instructions that never get committed:
```bash
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](docs/local-overrides.md).
**Reasoning effort across providers** — Tune how hard each AI tool thinks:
```yaml
# .ai-rulez/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews code for security regressions
effort: high
---
```
```toml
# .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** — `effort` in `.claude/agents/*.md` frontmatter (per-agent)
- **Codex** — `model_reasoning_effort` in `.codex/config.toml` and `.codex/agents/*.toml`
- **Amp** — `amp.anthropic.effort` in `.amp/settings.json` (global)
- **Windsurf** — `reasoning_effort` in `.windsurf/agents/*.md` frontmatter (per-agent)
- **Opencode** — `reasoningEffort` in `.opencode/agents/*.md` frontmatter (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](docs/configuration.md#defaults) 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:
```yaml
# .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
---
```
```toml
# .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 `_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:
```toml
[[installed_skills]]
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"
```
## MCP Server
ai-rulez includes a built-in MCP server with 35+ tools that lets AI assistants manage their own governance. Add rules, update context, generate configs — all programmatically.
```toml
[[mcp_servers]]
name = "ai-rulez"
command = "npx"
args = ["-y", "ai-rulez@latest", "mcp"]
```
## Installation
No install needed — `npx ai-rulez@latest ` works out of the box. Pick a permanent option below:
Homebrew (macOS / Linux)
```bash
brew install goldziher/tap/ai-rulez
```
npx (no install)
```bash
npx ai-rulez@latest
```
npm (global)
```bash
npm install -g ai-rulez
```
uvx (no install)
```bash
uvx ai-rulez
```
uv tool
```bash
uv tool install ai-rulez
```
pip / pipx
```bash
pip install ai-rulez
# or, isolated:
pipx install ai-rulez
```
pre-commit hook
Add to `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/Goldziher/ai-rulez
rev: v4.11.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`,
`ai-rulez-plugin-verify`, `ai-rulez-enforce`, and
`ai-rulez-enforce-fix`. 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+:
```toml
[[hooks.sources]]
id = "ai-rulez"
git = "https://github.com/Goldziher/ai-rulez.git"
revision = "v4.11.1"
hooks = ["ai-rulez-recursive", "ai-rulez-plugin-verify"]
```
The source also provides `ai-rulez-validate`, `ai-rulez-generate`,
`ai-rulez-enforce`, `ai-rulez-enforce-fix`, 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:
```bash
poly hooks update
git add poly.toml poly-hooks.lock
poly hooks install
```
See the [Poly hooks guide](docs/poly-hooks.md) for local sources, machine install
preferences, hook behavior, and the producer catalog.
lefthook
Add to `lefthook.yml`:
```yaml
pre-commit:
commands:
ai-rulez:
glob: ".ai-rulez/**"
run: ai-rulez generate --recursive
```
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](https://goldziher.github.io/ai-rulez/).
## License
MIT