Metadata-Version: 2.4
Name: ai-rulez
Version: 4.23.1
Summary: Complete AI development workflow for 14 AI coding tools. Ships with builtin rules, agents, and conventions. Generate native configs for Claude, Cursor, Copilot, Windsurf, Gemini, Codex and more from a single source.
Home-page: https://github.com/Goldziher/ai-rulez
Author: Na'aman Hirschfeld
Author-email: nhirschfeld@gmail.com
Project-URL: Homepage, https://goldziher.github.io/ai-rulez/
Project-URL: Documentation, https://goldziher.github.io/ai-rulez/
Project-URL: Bug Reports, https://github.com/Goldziher/ai-rulez/issues
Project-URL: Source, https://github.com/Goldziher/ai-rulez
Project-URL: Changelog, https://github.com/Goldziher/ai-rulez/releases
Project-URL: Funding, https://github.com/sponsors/Goldziher
Keywords: ai,ai-assistant,ai-rules,claude,cursor,copilot,windsurf,gemini,cline,continue-dev,mcp,model-context-protocol,cli,configuration,config,rules,generator,golang,go,development,developer-tools,automation,workflow,productivity,pre-commit,git-hooks,code-generation,ai-development,assistant-configuration,monorepo,presets,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Pre-processors
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Go
Classifier: Operating System :: OS Independent
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

<p align="center">
  <img src="https://raw.githubusercontent.com/Goldziher/ai-rulez/main/docs/assets/ai-rulez-banner.png" alt="AI-Rulez" width="820" />
</p>

<h1 align="center">ai-rulez</h1>

<p align="center">
  <strong>A complete development workflow for AI coding tools</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/ai-rulez"><img src="https://img.shields.io/npm/v/ai-rulez" alt="npm version"></a>
  <a href="https://pypi.org/project/ai-rulez/"><img src="https://img.shields.io/pypi/v/ai-rulez" alt="PyPI version"></a>
  <a href="https://github.com/Goldziher/ai-rulez/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Goldziher/ai-rulez" alt="License"></a>
  <a href="https://goldziher.github.io/ai-rulez/"><img src="https://img.shields.io/badge/docs-ai--rulez-blue" alt="Documentation"></a>
</p>

<p align="center">
  <a href="https://goldziher.github.io/ai-rulez/"><strong>Documentation</strong></a> &middot;
  <a href="https://goldziher.github.io/ai-rulez/quick-start/"><strong>Quick Start</strong></a> &middot;
  <a href="https://goldziher.github.io/ai-rulez/examples/"><strong>Examples</strong></a>
</p>

---

## 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
```

Prefer the project-level [`.config/` convention](https://github.com/pi0/config-dir)? `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](docs/configuration.md#provider-backed-presets-full-parity).

Set `agents_md = true` to write `AGENTS.md` and `.agents/skills/` once for the tools that read them (Codex, Cursor, Copilot, Gemini, Claude through an `@AGENTS.md` shim, and more) instead of one copy per tool. Off by default. See [docs/agents-md.md](docs/agents-md.md).

## 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](https://agent-plugins.org) packages.

```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 — 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](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, 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) that is read on every
request — rules in `.claude/rules/` under the default split mode (inlined into `CLAUDE.md` with
`[rules] mode = "inline"`), context and the agent roster in `CLAUDE.md` — 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`

```toml
# .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:

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

**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](docs/rules.md).

**Local configuration** — Personal, machine-local content and settings that never get committed:

```bash
ai-rulez add rule my-scratch-notes --local   # → .ai-rulez/local/rules/, generates .claude/rules/my-scratch-notes.local.md
ai-rulez local set presets '["codex", "!cursor"]'   # → .ai-rulez/config.local.toml overlay
```

`.ai-rulez/local/`, the `config.local.*` overlay and the generated `*.local.*` outputs are gitignored
unconditionally, and `generate` refuses to let local config change tracked shared files (use
`--no-local` for the teammate view). 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** — `variant` in `.opencode/agents/*.md` frontmatter (per-agent); a separate key beside the agent's `provider/model`
- **Xum** — `ai.thinkingLevel` in `.xum/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 `<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:

```toml
[[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:

```toml
[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.

```toml
[[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`:

```toml
[mcp]
self_server = true
```

## Installation

No install needed — `npx ai-rulez@latest <command>` works out of the box. Pick a permanent option below:

<details>
<summary><strong>Homebrew (macOS / Linux)</strong></summary>

```bash
brew install goldziher/tap/ai-rulez
```

</details>

<details>
<summary><strong>npx (no install)</strong></summary>

```bash
npx ai-rulez@latest <command>
```

</details>

<details>
<summary><strong>npm (global)</strong></summary>

```bash
npm install -g ai-rulez
```

</details>

<details>
<summary><strong>uvx (no install)</strong></summary>

```bash
uvx ai-rulez <command>
```

</details>

<details>
<summary><strong>uv tool</strong></summary>

```bash
uv tool install ai-rulez
```

</details>

<details>
<summary><strong>pip / pipx</strong></summary>

```bash
pip install ai-rulez
# or, isolated:
pipx install ai-rulez
```

</details>

<details>
<summary><strong>pre-commit hook</strong></summary>

Add to `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/Goldziher/ai-rulez
    rev: v4.23.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.
</details>

<details>
<summary><strong>poly hook source</strong></summary>

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

```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.
</details>

<details>
<summary><strong>lefthook</strong></summary>

Add to `lefthook.yml`:

```yaml
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.*` 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](docs/poly-hooks.md#machine-local-configuration-in-hooks).

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

## Documentation

Full documentation at [goldziher.github.io/ai-rulez](https://goldziher.github.io/ai-rulez/).

## License

MIT
