ai-rulez ⚡

AI-powered development governance. One config to rule them all.

The Complete AI Development Platform

AI-Rulez is the definitive platform for AI-powered development governance. Beyond just generating configuration files, it provides real-time rule enforcement, automated code quality assurance, and intelligent governance across your entire development workflow.

🚀 Two Powerful Capabilities

1. Universal Configuration Management - Write once, deploy everywhere 2. AI-Powered Rule Enforcement - Real-time governance with automated fixes

Why AI-Rulez?

Modern development teams need more than just configuration management:

⚠️ The Problem

Configuration Hell: Each AI tool needs its own format (.cursorrules, CLAUDE.md, .windsurfrules, etc.)
Rule Enforcement Gap: No way to automatically validate that code follows your standards
Team Inconsistency: Different developers get different AI guidance
Manual Quality Control: Time-consuming code reviews for basic rule violations
Reactive Governance: Finding issues after they're already committed

✨ The Solution

AI-Rulez provides proactive development governance with a single ai-rulez.yaml that:

Generates configurations for every AI tool automatically
Enforces rules in real-time using AI agents (Claude, Gemini, etc.)
Applies automatic fixes for code quality issues
Integrates with your workflow (Git hooks, CI/CD, pre-commit)
Scales across teams with consistent standards

📝 Configuration Management (via npx ai-rulez)

🤖 AI-Powered Rule Enforcement (via uvx ai-rulez@latest)

📖 Read the Full Documentation

🚀 Core Capabilities

1. 📋 Universal Configuration Management

Write once, deploy everywhere with intelligent AI-powered project analysis:

# AI analyzes your codebase and generates tailored config
npx ai-rulez init "My Project" --preset popular

Features:

AI Project Analysis: Automatically detects your tech stack, patterns, and conventions
Universal Output Generation: One YAML → all AI tool formats (CLAUDE.md, .cursorrules, .windsurfrules, etc.)
Smart Gitignore Management: Automatically excludes generated files from version control
MCP Integration: Auto-configure MCP servers across CLI tools (Claude, Gemini, etc.)
Team Collaboration: Remote includes, local overrides, monorepo support

2. 🤖 AI-Powered Rule Enforcement

Real-time governance with automated fixes using multiple AI agents:

# Check for violations with AI analysis
uvx ai-rulez@latest enforce --agent claude

# Automatically apply fixes
uvx ai-rulez@latest enforce --agent claude --fix

# Multi-agent review workflow
uvx ai-rulez@latest enforce --agent gemini --review --review-agent claude

Features:

Multi-Agent Support: Claude, Gemini, AMP, Cursor, Codex, Continue.dev, Junie
Automated Fixes: AI suggests and applies code improvements
Review Workflows: Iterative improvement with quality thresholds
Multiple Output Formats: Table, JSON, CSV, summary reports
CI/CD Integration: Git hooks, pre-commit, workflow automation
Quality Scoring: 0-100% compliance with configurable thresholds

How It Works

AI-Rulez operates as a comprehensive AI development governance platform:

📝 Configuration Phase: Your ai-rulez.yml serves as the single source of truth
🏗️ Generation Phase: Automatically creates native files for every AI tool
🔍 Enforcement Phase: AI agents continuously validate code against your rules
🛠️ Fix Phase: Automatic corrections and improvements applied in real-time
📊 Reporting Phase: Detailed compliance reports and quality metrics

Think of it as CI/CD for code quality - proactive governance instead of reactive fixes.

Example: `ai-rulez.yml`

$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json

metadata:
  name: "My SaaS Platform"
  version: "2.0.0"

# Use presets for common configurations
presets:
  - "popular"  # Includes Claude, Cursor, Windsurf, Copilot, and Gemini

rules:
  - name: "Go Code Standards"
    priority: high
    content: "Follow standard Go project layout (cmd/, internal/, pkg/). Use meaningful package names and export only what is necessary."

sections:
  - name: "Project Structure"
    priority: critical
    content: |
      - `cmd/`: Main application entry point
      - `internal/`: Private application code (business logic, data access)
      - `pkg/`: Public-facing libraries

agents:
  - name: "go-developer"
    description: "Go language expert for core development"
    system_prompt: "You are an expert Go developer. Your key responsibilities include writing idiomatic Go, using proper error handling, and creating comprehensive tests."

# MCP servers for direct AI tool integration
mcp_servers:
  - name: "ai-rulez"
    command: "npx"
    args: ["-y", "ai-rulez@latest", "mcp"]
    description: "AI-Rulez MCP server for configuration management"

Run ai-rulez generate → get all your configuration files, perfectly synchronized.

⚡ Quick Start

📋 Configuration Management

# 1. AI-powered project analysis and setup
npx ai-rulez@latest init "My Project" --preset popular

# 2. Generate all AI tool configuration files
npx ai-rulez@latest generate

# 3. Your AI tools now have comprehensive, project-specific context!

🤖 AI-Powered Rule Enforcement

# 1. Check for rule violations
uvx ai-rulez@latest enforce --agent claude --format table

# 2. Get detailed analysis and suggestions
uvx ai-rulez@latest enforce --agent claude --format json

# 3. Apply automatic fixes
uvx ai-rulez@latest enforce --agent claude --fix

# 4. Set up review workflow
uvx ai-rulez@latest enforce --agent claude --review --review-iterations 2

That's it! You now have both intelligent configuration management AND real-time rule enforcement powered by AI.

🗂️ .gitignore Management

AI-Rulez manages your .gitignore to keep generated files out of version control.

Automatic updates:

# During init (enabled by default)
ai-rulez init --preset claude

# During generate (optional)
ai-rulez generate --update-gitignore

# Disable if needed
ai-rulez init --preset popular --no-gitignore

What gets ignored:

Generated markdown files (CLAUDE.md, GEMINI.md, AGENTS.md)
AI tool directories (.claude/, .cursor/, .windsurf/, .clinerules/, etc.)
Config files (.mcp.json, .gemini/settings.json)

All entries are added under # AI Rules generated files without duplicates.

Best practice: Commit ai-rulez.yaml and .gitignore, but not the generated AI configuration files.

🤖 AI-Powered Rule Enforcement

The killer feature that sets AI-Rulez apart: real-time rule enforcement using AI agents. No more manual code reviews for basic violations—let AI catch and fix issues automatically.

✨ Key Benefits

Proactive Quality Control: Catch issues before they reach production
Multi-Agent Support: Claude, Gemini, AMP, Cursor, Codex—use the best AI for each task
Automatic Fixes: AI doesn't just find problems, it solves them
Workflow Integration: Git hooks, CI/CD, pre-commit—enforcement everywhere
Team Consistency: Same standards for everyone, from junior to senior devs

🎯 Real-World Use Cases

# Prevent console.log in production builds
ai-rulez enforce --agent claude --only-rules "no-console-output" --fix

# Ensure all functions have proper error handling
ai-rulez enforce --agent gemini --level strict --format json

# Multi-agent review for critical code changes
ai-rulez enforce --agent claude --review --review-agent gemini --review-threshold 95

# Automated fixes in CI/CD pipeline
ai-rulez enforce --agent claude --fix --format csv --output violations.csv

📊 Output Formats & Integration

Format	Use Case	Command
Table	Human-readable terminal output	`--format table`
JSON	API integration, detailed analysis	`--format json --pretty`
CSV	Data analysis, reporting	`--format csv --output report.csv`
Summary	Quick overview with scores	`--format summary`

🔄 Advanced Workflows

Review Pipeline: Multi-agent validation with quality gates

ai-rulez enforce --agent claude --review --review-iterations 3 --review-threshold 85

Fix & Verify: Apply fixes and validate improvements

ai-rulez enforce --agent gemini --fix --review --require-improvement

Team Standards: Consistent enforcement across the entire codebase

ai-rulez enforce --include-files "src/**/*.{js,ts,py}" --level strict --agent claude

Prefer manual setup?

# Basic initialization without AI assistance
ai-rulez init "My Project" --preset popular --no-agent

# Add your project-specific context
ai-rulez add rule "Tech Stack" --priority critical --content "This project uses Go and PostgreSQL."

# Generate files
ai-rulez generate

MCP Server Integration

ai-rulez provides seamless Model Context Protocol (MCP) integration, automatically configuring both file-based and CLI-based AI tools with your MCP servers.

Automatic CLI Configuration

When you run ai-rulez generate, MCP servers are automatically configured for available CLI tools:

ai-rulez generate
# ✅ Generated 3 file(s) successfully
# ✅ Configured claude MCP server: ai-rulez
# ✅ Configured gemini MCP server: database-tools

Supported CLI tools:

Claude CLI: claude mcp add with full env/transport support
Gemini CLI: gemini mcp add with automatic configuration

Hybrid Configuration

ai-rulez supports both CLI and file-based configurations simultaneously:

mcp_servers:
  - name: "database-tools"
    command: "uvx"
    args: ["mcp-server-postgres"]
    env:
      DATABASE_URL: "postgresql://localhost/mydb"
    targets: 
      - "@claude-cli"        # Configure Claude CLI
      - "@gemini-cli"        # Configure Gemini CLI  
      - ".cursor/mcp.json"   # Generate Cursor config file

This single configuration:

✅ Executes claude mcp add commands
✅ Executes gemini mcp add commands
✅ Generates .cursor/mcp.json file

Control Options

Default behavior (recommended):

ai-rulez generate
# Configures all available CLI tools + generates files

Disable CLI configuration when needed:

ai-rulez generate --no-configure-cli-mcp
# Only generates files, skips CLI tool configuration

Target specific tools:

mcp_servers:
  - name: "github-integration"
    command: "npx"
    args: ["@modelcontextprotocol/server-github"]
    targets: ["@claude-cli"]  # Only configure Claude CLI

Built-in MCP Server

ai-rulez includes its own MCP server for configuration management:

# Start the ai-rulez MCP server
ai-rulez mcp

# Or configure it automatically via your ai-rulez.yaml
mcp_servers:
  - name: "ai-rulez"
    command: "npx"
    args: ["-y", "ai-rulez@latest", "mcp"]
    description: "Configuration management server"

AI-Powered Rule Enforcement

AI-Rulez provides real-time rule enforcement using AI agents to automatically detect violations and apply fixes across your codebase.

Basic Enforcement

# Check for violations (read-only by default)
ai-rulez enforce

# Automatically apply fixes
ai-rulez enforce --fix

# Use specific AI agent
ai-rulez enforce --agent gemini --fix

Advanced Enforcement Options

# Enforce with specific level
ai-rulez enforce --level strict --agent claude

# Review workflow with iterative improvement
ai-rulez enforce --review --review-iterations 3 --review-threshold 85

# Multi-agent review (different agents for enforcement vs review)
ai-rulez enforce --agent gemini --review --review-agent claude

# Target specific files and rules
ai-rulez enforce --include-files "src/**/*.js" --only-rules "no-console-output"

# Output formats for automation
ai-rulez enforce --format json --output violations.json
ai-rulez enforce --format csv --output report.csv

Supported AI Agents

AI-Rulez integrates with all major AI coding assistants:

Claude (claude) - Anthropic's AI assistant
Gemini (gemini) - Google's AI model
Cursor (cursor) - AI-powered code editor
AMP (amp) - Sourcegraph's AI assistant
Codex (codex) - OpenAI's code model
Continue.dev (continue-dev) - Open-source coding assistant
Junie (junie) - JetBrains AI assistant

Enforcement Levels

warn: Log violations but don't fail (default)
error: Fail on violations but don't auto-fix
fix: Automatically apply suggested fixes
strict: Fail immediately on any violation

Integration with Git Hooks

Add enforcement to your Git workflow:

# .lefthook.yml
pre-commit:
  commands:
    ai-rulez-enforce:
      run: ai-rulez enforce --level error --agent gemini
      stage_fixed: true

# Or with pre-commit hooks
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: ai-rulez-enforce
        name: AI-Rulez Enforcement
        entry: ai-rulez enforce --level error
        language: system
        pass_filenames: false

Review Workflow

The review system provides iterative code improvement:

# Enable review with quality scoring
ai-rulez enforce --review --review-threshold 80

# Multiple review iterations
ai-rulez enforce --review --review-iterations 5

# Auto-approve after reaching threshold
ai-rulez enforce --review --review-auto-approve

# Require improvement between iterations
ai-rulez enforce --review --require-improvement

The AI reviewer analyzes:

✅ Code quality and adherence to rules
✅ Suggested fixes and their appropriateness
✅ Overall improvement between iterations
✅ Compliance with project standards

📦 Installation

Choose your installation method based on your primary use case:

🚀 Quick Start (No Installation)

For Configuration Management (project setup, file generation):

# Node.js - Best for web/JS projects
npx ai-rulez@latest init "My Project" --preset popular
npx ai-rulez@latest generate

For Rule Enforcement (AI-powered validation):

# Python - Latest features, fastest updates
uvx ai-rulez@latest enforce --agent claude --fix
uvx ai-rulez@latest enforce --agent gemini --review

For Go Projects:

go run github.com/Goldziher/ai-rulez/cmd@latest init

🔧 Global Installation

For teams and frequent usage:

Homebrew (Recommended for macOS/Linux)

brew install goldziher/tap/ai-rulez
ai-rulez init "My Project"
ai-rulez enforce --agent claude

npm (Best for Node.js teams)

npm install -g ai-rulez

pip (Best for Python teams)

pip install ai-rulez

Go (For Go developers)

go install github.com/Goldziher/ai-rulez/cmd@latest

Pre-commit Hooks

You can use ai-rulez with pre-commit to automatically validate and generate your AI configuration files.

Add the following to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Goldziher/ai-rulez
    rev: v2.3.0
    hooks:
      - id: ai-rulez-validate
      - id: ai-rulez-generate

Documentation

Quick Start Guide
Full CLI Reference
Configuration Guide
Migration Guide - Upgrading from v1.x to v2.0

Contributing

Contributions are welcome! Please see the Contributing Guide to get started.

Name		Name	Last commit message	Last commit date
Latest commit History 261 Commits
.github		.github
cmd		cmd
docs		docs
homebrew-tap @ 194c7dd		homebrew-tap @ 194c7dd
internal		internal
release		release
schema		schema
site		site
testing		testing
tests		tests
.commitlintrc		.commitlintrc
.gitignore		.gitignore
.gitmodules		.gitmodules
.golangci.yaml		.golangci.yaml
.goreleaser.yaml		.goreleaser.yaml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ai-rulez.yaml		ai-rulez.yaml
go.mod		go.mod
go.sum		go.sum
lefthook.yaml		lefthook.yaml
mkdocs.yaml		mkdocs.yaml
package.json		package.json
pyproject.toml		pyproject.toml
taskfile.yaml		taskfile.yaml
uv.lock		uv.lock

License

Goldziher/ai-rulez

Folders and files

Latest commit

History

Repository files navigation

ai-rulez ⚡

The Complete AI Development Platform

🚀 Two Powerful Capabilities

Why AI-Rulez?

⚠️ The Problem

✨ The Solution

📖 Read the Full Documentation

🚀 Core Capabilities

1. 📋 Universal Configuration Management

2. 🤖 AI-Powered Rule Enforcement

How It Works

Example: ai-rulez.yml

⚡ Quick Start

📋 Configuration Management

🤖 AI-Powered Rule Enforcement

🗂️ .gitignore Management

🤖 AI-Powered Rule Enforcement

✨ Key Benefits

🎯 Real-World Use Cases

📊 Output Formats & Integration

🔄 Advanced Workflows

MCP Server Integration

Automatic CLI Configuration

Hybrid Configuration

Control Options

Built-in MCP Server

AI-Powered Rule Enforcement

Basic Enforcement

Advanced Enforcement Options

Supported AI Agents

Enforcement Levels

Integration with Git Hooks

Review Workflow

📦 Installation

🚀 Quick Start (No Installation)

🔧 Global Installation

Pre-commit Hooks

Documentation

Contributing

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 37

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Example: `ai-rulez.yml`

Packages