![\"AI-Rulez\"](\"https://raw.githubusercontent.com/Goldziher/ai-rulez/main/docs/assets/ai-rulez-banner.png\")
\n\n \n
\n A complete development workflow for AI coding tools\n
\n\n\n ![\"npm](\"https://img.shields.io/npm/v/ai-rulez\")
![\"PyPI](\"https://img.shields.io/pypi/v/ai-rulez\")
![\"License\"](\"https://img.shields.io/github/license/Goldziher/ai-rulez\")
![\"Documentation\"](\"https://img.shields.io/badge/docs-ai--rulez-blue\"){kind=icon}
\n Documentation ·\n Quick Start ·\n Examples\n
\n\n---\n\n## The Problem\n\nEvery 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.\n\n## The Solution\n\nWrite your rules, context, skills, agents, and commands once in `.ai-rulez/`. Run `generate`. Get native configs for every tool you use.\n\n```bash\nnpx ai-rulez@latest init && npx ai-rulez@latest generate\n```\n\nai-rulez generates correct, tool-native output for **13 platforms**: Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Continue.dev, Codex, OpenCode, Hermes, Amp, Junie, and Antigravity. Each preset respects the target tool's conventions — proper frontmatter, directory structure, file extensions, agent formats.\n\n## Generate Plugins, Not Just Config\n\nai-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.\n\n```bash\nai-rulez generate --plugin # write plugin bundles + marketplace.json\nai-rulez generate --plugin --dry-run # preview\nai-rulez verify --plugin # prove committed output matches its sources\n```\n\nWrite 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).\n\n## What Ships Out of the Box\n\nai-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.\n\n### Builtin Rules (auto-included)\n\nThese activate automatically. No configuration needed.\n\n| Domain | What it enforces |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **ai-governance** | No AI signatures in commits. Concise communication. Systematic debugging. Verification before claiming success. Critical review of subagent output. |\n| **code-quality** | Anti-patterns prevention. Complexity limits. Dead code removal. Error handling standards. Readability. |\n| **testing** | TDD workflow (red-green-refactor, no exceptions). Testing anti-patterns. Meaningful assertions. Test independence. |\n| **git-workflow** | Atomic commits. Conventional commit messages. Safe operations. Branch hygiene. |\n| **security** | Secrets handling. Input validation. Dependency auditing. Least privilege. |\n| **token-efficiency** | Task runner usage. Incremental approach. Context preservation. Batch operations. |\n| **agent-delegation** | Multi-agent coordination and delegation patterns. |\n\n### Builtin Agents\n\nSpecialized agents ready to use as subagents:\n\n| Agent | Domain | Model | What it does |\n| -------------------- | ------------- | ------ | -------------------------------------------------------------------------------- |\n| **code-reviewer** | ai-governance | sonnet | Reviews changes for correctness, security, and conventions. Reports by severity. |\n| **test-writer** | testing | sonnet | Writes tests following strict TDD. Fails first, then implements. |\n| **security-auditor** | security | sonnet | Audits dependencies, scans for CVEs, reviews input validation. |\n| **docs-writer** | ai-governance | haiku | Writes clear, concise documentation. No fluff. |\n| **devops-engineer** | cicd | haiku | CI/CD pipelines, GitHub Actions, Docker, deployment automation. |\n| **release-engineer** | cicd | haiku | Version management, changelogs, multi-registry publishing. |\n\n### Opt-in Domains\n\nEnable these based on your stack:\n\n**Languages** (10): `rust`, `python`, `typescript`, `go`, `java`, `ruby`, `php`, `elixir`, `csharp`, `r`\n\n**Bindings** (10): `pyo3`, `napi-rs`, `magnus`, `ext-php-rs`, `rustler`, `wasm`, `jni-rs`, `extendr`, `cgo`, `vite-plus`\n\n**Operational**: `cicd`, `docker`, `observability`, `documentation`, `polyglot-bindings`, `default-commands`\n\n```toml\n# .ai-rulez/config.toml\nbuiltins = [\"rust\", \"python\", \"pyo3\", \"cicd\", \"docker\", \"default-commands\"]\n```\n\nLanguage, binding, `polyglot-bindings`, and `security` (OWASP + dependency) conventions are emitted as\n**on-demand Agent Skills** (`.claude/skills/